### Show Available Quickstart Examples

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/ref/cmd_switches.md

Run `fast-agent quickstart` without arguments to list all available example applications for quick project setup.

```bash
fast-agent quickstart
```

--------------------------------

### Create Workflow Quickstart Example

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/ref/cmd_switches.md

Generate a workflow example application in the current directory using `fast-agent quickstart workflow .`. This is useful for understanding agent workflows.

```bash
fast-agent quickstart workflow .
```

--------------------------------

### Create Researcher Quickstart Example

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/ref/cmd_switches.md

Use `fast-agent quickstart researcher .` to create a researcher example application. This helps in setting up agents for research tasks.

```bash
fast-agent quickstart researcher .
```

--------------------------------

### Create Data Analysis Quickstart Example

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/ref/cmd_switches.md

Generate a data analysis example application in the current directory with `fast-agent quickstart data-analysis .`. This is ideal for agents performing data tasks.

```bash
fast-agent quickstart data-analysis .
```

--------------------------------

### Create State Transfer Quickstart Example

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/ref/cmd_switches.md

Use `fast-agent quickstart state-transfer .` to create an example application demonstrating state transfer. This is useful for agents managing persistent states.

```bash
fast-agent quickstart state-transfer .
```

--------------------------------

### Setup fast-agent on Windows

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/mcp/state_transfer.md

Installs fast-agent-mcp and creates the state transfer example project. Ensure you are in a new directory and have a Python environment activated.

```powershell
# create, and change to a new directory
md fast-agent |cd

# create and activate a python environment
uv venv
.venv\Scripts\activate

# setup fast-agent
uv pip install fast-agent-mcp

# create the state transfer example
fast-agent quickstart state-transfer
```

--------------------------------

### Setup fast-agent on Linux/MacOS

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/mcp/state_transfer.md

Installs fast-agent-mcp and creates the state transfer example project. Ensure you are in a new directory and have a Python environment activated.

```bash
# create, and change to a new directory
mkdir fast-agent && cd fast-agent

# create and activate a python environment
uv venv
source .venv/bin/activate

# setup fast-agent
uv pip install fast-agent-mcp

# create the state transfer example
fast-agent quickstart state-transfer
```

--------------------------------

### TensorZero Quickstart Command

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/models/llm_providers.md

Initiate the TensorZero integration setup using the fast-agent quickstart command. This creates a dockerized project.

```bash
fast-agent quickstart tensorzero
```

--------------------------------

### Local Overlay with System Model Reference Example

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/models/model_overlays.md

Demonstrates using a local overlay (`qwen-local`) referenced by a system token (`$system.fast`). This setup allows for stable project-facing tokens while keeping endpoint details in environment-local overlays.

```yaml
default_model: "$system.fast"

model_references:
  system:
    fast: "qwen-local"
```

--------------------------------

### Start fast-agent server

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/mcp/mcp-ui.md

Run this command to start the Model Context Protocol everything server and check your fast-agent installation. Ensure environment variables like OPENAI_API_KEY are set.

```bash
fast-agent --npx @modelcontextprotocol/server-everything
```

--------------------------------

### Setup fast-agent on Linux/MacOS

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/mcp/elicitations.md

Installs fast-agent-mcp and sets up the elicitations demo environment on Linux or MacOS.

```bash
mkdir fast-agent && cd fast-agent

uv venv
source .venv/bin/activate

uv pip install fast-agent-mcp

fast-agent quickstart elicitations

cd elicitations
```

--------------------------------

### Setup fast-agent on Windows

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/mcp/elicitations.md

Installs fast-agent-mcp and sets up the elicitations demo environment on Windows using PowerShell.

```powershell
md fast-agent |cd

uv venv
.venv\Scripts\activate

uv pip install fast-agent-mcp

fast-agent quickstart elicitations

cd elicitations
```

--------------------------------

### Install or Reuse Pack and Launch

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/ref/go_command.md

Installs or reuses a specified pack and immediately launches the agent.

```bash
fast-agent go --pack analyst --model haiku
```

--------------------------------

### Setup Fast-Agent Model References

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/ref/cmd_switches.md

Use the 'setup' subcommand with the model command to configure or update namespaced model references.

```bash
fast-agent model setup
```

--------------------------------

### Start fast-agent session from a pack

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/index.md

Launch an interactive fast-agent session using an installed or marketplace card pack.

```bash
fast-agent go --pack hf-dev

```

--------------------------------

### Install keyring on Ubuntu

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/mcp/mcp-oauth.md

Installs the necessary keyring packages on Ubuntu for token persistence.

```bash
sudo apt-get install gnome-keyring seahorse
```

--------------------------------

### Install fast-agent-mcp

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/getting_started/installation.md

Install the fast-agent-mcp tool using uv. Ensure uv is installed first.

```bash
uv tool install fast-agent-mcp -U
```

--------------------------------

### Example Full Configuration

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/ref/config_file.md

A comprehensive example demonstrating the structure of a complete Fast Agent configuration file, including model settings, MCP servers, and logging.

```yaml
default_model: "gpt-5-mini?reasoning=low"

# Model provider settings
anthropic:
  api_key: API_KEY

openai:
  api_key: API_KEY
  reasoning_effort: "high"

# MCP servers
mcp:
  servers:
    fetch:
      transport: "stdio"
      command: "uvx"
      args: ["mcp-server-fetch"]
      
    prompts:
      transport: "stdio"
      command: "prompt-server"
      args: ["prompts/myprompt.txt"]
      
    filesys:
      transport: "stdio"
      command: "uvx"
      args: ["mcp-server-filesystem"]
      roots:
        - uri: "file://./data"
          name: "Data Directory"

# Logging configuration
logger:
  type: "file"
  level: "info"
  path: "logs/fastagent.jsonl"
  render_fences_with_syntax: true
  code_word_wrap: false
```

--------------------------------

### Example of running an agent module with specific options

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/mcp/mcp-server.md

This example demonstrates running an agent module as an HTTP server on a specific port with a 'request' instance scope for stateless operation.

```bash
uv run agent.py \
--transport http \
--port 8723 \
--instance-scope request
```

--------------------------------

### Basic Agent Example with Azure OpenAI

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/ref/azure-config.md

Implement a simple agent using fast-agent and Azure OpenAI Service. Ensure the 'fast-agent-mcp[azure]' package is installed and your Azure credentials are configured.

```python
import asyncio
from fast_agent.core.fastagent import FastAgent

# Create the application
fast = FastAgent("Azure OpenAI Example")

# Define the agent using Azure OpenAI deployment
@fast.agent(
    instruction="You are a helpful AI assistant powered by Azure OpenAI Service", 
    model="azure.my-deployment"
)
async def main():
    async with fast.run() as agent:
        # Start interactive prompt
        await agent()

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Start Agent with Instruction from File (CLI)

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/agents/instructions.md

Command-line interface command to start an agent using instructions from a specified file. This is a convenient way to manage prompts.

```bash
fast-agent --instruction mcp-expert.md
```

--------------------------------

### Start Agent with Instruction, Model, and URL (CLI)

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/agents/instructions.md

Command-line interface command to start an agent with specific instructions, model, and server URL. This allows for detailed configuration of the agent session.

```bash
fast-agent --instruction mcp-expert.md --model sonnet --url https://hf.co/mcp
```

--------------------------------

### Install fast-agent using uv tool

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/index.md

Install fast-agent using the uv tool. Specify a Python version if you have multiple Python installations.

```bash
uv tool install fast-agent-mcp

```

```bash
uv tool install fast-agent-mcp --python 3.13.5

```

--------------------------------

### FastAPI Integration Example

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/ref/class_reference.md

Example demonstrating how to integrate fast-agent with a FastAPI application.

```APIDOC
## Example: Integrating with FastAPI

See [here](https://github.com/evalstate/fast-agent/tree/main/examples/fastapi) for more examples of using FastAPI with **`fast-agent`**.

```python title="fastapi-simple.py"
from contextlib import asynccontextmanager

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

from fast_agent.core.fastagent import FastAgent

# Create FastAgent without parsing CLI args (plays nice with uvicorn)
fast = FastAgent("fast-agent demo", parse_cli_args=False, quiet=True)


# Register a simple default agent via decorator
@fast.agent(name="helper", instruction="You are a helpful AI Agent.", default=True)
async def decorator():
    pass


# Keep FastAgent running for the app lifetime
@asynccontextmanager
async def lifespan(app: FastAPI):
    async with fast.run() as agents:
        app.state.agents = agents
        yield


app = FastAPI(lifespan=lifespan)


class AskRequest(BaseModel):
    message: str


class AskResponse(BaseModel):
    response: str


@app.post("/ask", response_model=AskResponse)
async def ask(req: AskRequest) -> AskResponse:
    try:
        result = await app.state.agents.send(req.message)
        return AskResponse(response=result)
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))
```
```

--------------------------------

### Install fast-agent

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/guides/hf-dev.md

Installs the `fast-agent-mcp` executable using `uv`. Ensure Python 3.13 or above is installed.

```bash
uv tool install -U fast-agent-mcp
```

--------------------------------

### Start fast-agent with Hugging Face Dev Pack

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/guides/hf-dev.md

Starts `fast-agent` pre-configured with a coding agent and filesystem search sub-agent using the Hugging Face development pack.

```bash
uvx fast-agent-mcp@latest --pack hf-dev
```

--------------------------------

### Install a Skill by Name or Number

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/agents/skills.md

Use the `/skills add` command to install skills from the marketplace. You can specify the skill by its name or its numerical index displayed in the available skills list.

```bash
/skills add
/skills add skill-name
/skills add 1
```

--------------------------------

### Fast-Agent Model Setup and Doctor Flows

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/models/model_overlays.md

Utilize `fast-agent model setup` to create or update namespaced model references and `fast-agent model doctor` to inspect model onboarding readiness and reference resolution.

```bash
fast-agent model setup
```

```bash
fast-agent model doctor
```

--------------------------------

### Install fast-agent using uvx

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/index.md

Run this command to install the latest version of fast-agent using the uv package manager.

```bash
uvx fast-agent-mcp@latest -x

```

--------------------------------

### Install fast-agent-mcp

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/getting_started.md

Use this command to install or upgrade the fast-agent-mcp package.

```bash
uv tool install -U fast-agent-mcp
```

--------------------------------

### Run fast-agent

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/getting_started.md

This is the basic command to start the fast-agent.

```bash
fast-agent go
```

--------------------------------

### Start FastAgent Server

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/ref/class_reference.md

Starts the FastAgent application as an MCP server. Configure transport protocol, host, port, and server details.

```python
await fast.start_server(
    transport: str = "http",
    host: str = "0.0.0.0",
    port: int = 8000,
    server_name: str | None = None,
    server_description: str | None = None,
    tool_description: str | None = None,
    instance_scope: str = "shared",
    permissions_enabled: bool = True,
)
```

--------------------------------

### Example Environment Output

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/agents/instructions.md

This shows the typical output format for the {{env}} template variable, which includes workspace root, client, and host platform details.

```markdown
Environment:
- Workspace root: /home/user/project
- Client: Zed 0.232
- Host platform: Linux-6.6.87.2-microsoft-standard-WSL2
```

--------------------------------

### FastAgent Methods

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/ref/class_reference.md

Core methods for running agents and starting the server.

```APIDOC
## FastAgent Methods

### Description
Core methods for running agents and starting the server.

### `run()`

#### Description
An async context manager that initializes all registered agents and returns an `AgentApp` instance that can be used to interact with the agents.

#### Usage
```python
async with fast.run() as agent:
    # Use agent here
```

### `start_server()`

#### Description
Starts the application as an MCP server.

#### Parameters
- **transport** (str) - Optional - Default: `"http"` - Transport protocol to use (`http`, `sse`, `stdio`, `acp`)
- **host** (str) - Optional - Default: `"0.0.0.0"` - Host address for the server when using HTTP or SSE
- **port** (int) - Optional - Default: `8000` - Port for the server when using HTTP or SSE
- **server_name** (str | None) - Optional - Default: `None` - Optional custom name for the MCP server
- **server_description** (str | None) - Optional - Default: `None` - Optional description for the MCP server
- **tool_description** (str | None) - Optional - Default: `None` - Customise the exposed `send` tool description (supports `{agent}` placeholder)
- **instance_scope** (str) - Optional - Default: `"shared"` - Control how clients receive isolated agent instances (`shared`, `connection`, `request`); ACP is always connection-scoped
- **permissions_enabled** (bool) - Optional - Default: `True` - Enable tool permission requests (ACP only)

#### Usage
```python
await fast.start_server(
    transport="http",
    host="0.0.0.0",
    port=8000,
    server_name="MyFastAgent",
    server_description="An example FastAgent server",
    tool_description="Send a message to {agent}",
    instance_scope="request",
    permissions_enabled=False
)
```
```

--------------------------------

### Quick Start: OpenAI ACP Agent

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/acp/index.md

Set the OPENAI_API_KEY environment variable and run the fast-agent-acp command with a specified model for a quick start with OpenAI.

```bash
export OPENAI_API_KEY=......

uvx fast-agent-acp@latest  --model <your_model> [e.g. gpt-5-mini.low]
```

--------------------------------

### Define a Basic Agent with Multiple Configurations

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/agents/defining.md

Shows a comprehensive example of defining an agent with various parameters including name, instruction, servers, model, history, request parameters, and human input.

```python
@fast.agent(
  name="agent",                          # name of the agent
  instruction="You are a helpful Agent", # base instruction for the agent
  servers=["filesystem"],
  #tools={"filesystem": ["tool_1", "tool_2"]}
  #resources={"filesystem": ["resource_1", "resource_2"]}
  #prompts={"filesystem": ["prompt_1", "prompt_2"]}
  #function_tools=[helper_fn, "tools.py:other_helper"],
  model="o3-mini.high",                  # specify a model for the agent
  use_history=True,                      # agent maintains chat history
  request_params=RequestParams(temperature= 0.7), # additional parameters for the LLM (or RequestParams())
  human_input=True,                      # agent can request human input
  elicitation_handler=ElicitationFnT,    # custom elicitation handler (from mcp.client.session)
  api_key="programmatic-api-key",        # specify the API KEY programmatically, it will override which provided in config file or env var
)
```

--------------------------------

### Command-Line Tool Embedding Example

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/ref/class_reference.md

Example showing how to embed fast-agent within a custom command-line tool.

```APIDOC
## Example: Embedding in a Command-Line Tool

Here's an example of embedding FastAgent in a custom command-line tool:

```python
import asyncio
import argparse
import sys
from fast_agent.core.fastagent import FastAgent

# Parse our own arguments first
parser = argparse.ArgumentParser(description="Custom AI Tool")
parser.add_argument("--input", help="Input data for analysis")
parser.add_argument("--format", choices=["text", "json"], default="text", help="Output format")
args, remaining = parser.parse_known_args()

# Create FastAgent with parse_cli_args=False since we're handling our own args
fast = FastAgent("Embedded Agent", parse_cli_args=False)

@fast.agent(instruction="You are a data analysis assistant")
async def analyze():
    async with fast.run() as agent:
        if not args.input:
            print("Error: --input is required")
            sys.exit(1)
            
        result = await agent.send(f"Analyze this data: {args.input}")
        
        if args.format == "json":
            import json
            print(json.dumps({"result": result}))
        else:
            print(result)

if __name__ == "__main__":
    asyncio.run(analyze())
```

This example shows how to:
1. Parse your application's own arguments using `argparse`
2. Create a FastAgent instance with `parse_cli_args=False`
3. Use your own command-line arguments in combination with **`fast-agent`**
```

--------------------------------

### Start fast-agent session with a remote MCP

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/index.md

Connect to a remote MCP server to start an interactive fast-agent session.

```bash
fast-agent go --url https://hf.co/mcp

```

--------------------------------

### Use Codex Planning Model

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/models/llm_providers.md

Command to start fast-agent using the default Codex planning model alias.

```bash
# Use the Codex planning model
fast-agent --model codexplan
```

--------------------------------

### Agents As Tools Workflow Example

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/agents/workflows.md

Demonstrates the Agents As Tools pattern where complex tasks are broken into subtasks, calling other agents as tools. Supports routing, parallelization, and orchestrator-worker decomposition.

```python
@fast.agent(
    name="NY-Project-Manager",
    instruction="Return NY time + timezone, plus a one-line project status.",
    servers=["time"],
)
@fast.agent(
    name="London-Project-Manager",
    instruction="Return London time + timezone, plus a one-line news update.",
    servers=["time"],
)
@fast.agent(
    name="PMO-orchestrator",
    instruction=(
        "Get reports. Always use one tool call per project/news. "
        "Responsibilities: NY projects: [OpenAI, Fast-Agent, Anthropic]. London news: [Economics, Art, Culture]. "
        "Aggregate results and add a one-line PMO summary."
    ),
    default=True,
    agents=["NY-Project-Manager", "London-Project-Manager"],
)
async def main() -> None:
    async with fast.run() as agent:
        await agent("Get PMO report. Projects: all. News: Art, Culture")
```

--------------------------------

### Setup fast-agent default models

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/guides/hf-dev.md

Configure the default coding and search models used by `fast-agent`. This command prompts for model selection.

```bash
uvx fast-agent-mcp@latest model setup
```

--------------------------------

### Programmatically Start MCP Server

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/agents/running.md

Starts an MCP server programmatically within a Python application. Configures server details like transport, host, and port.

```python
import asyncio
from fast_agent.core.fastagent import FastAgent

fast = FastAgent("Server Agent")

@fast.agent(instruction="You are an API agent")
async def main():
    # Start as a server programmatically
    await fast.start_server(
        transport="http",
        host="0.0.0.0",
        port=8080,
        server_name="API-Agent-Server",
        server_description="Provides API access to my agent",
        tool_description="Send a message to the {agent} agent",
    )

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Run Interactive Forms Demo

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/mcp/elicitations.md

Starts the interactive forms demonstration for MCP Elicitations, showcasing various field types and validations.

```bash
uv run forms_demo.py
```

--------------------------------

### Minimal Example with Tool Runner Hooks

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/agents/tool_runner.md

Demonstrates how to implement and attach custom hooks to the Tool Runner for modifying LLM calls and logging tool results. Requires implementing ToolRunnerHookCapable and exposing tool_runner_hooks.

```python
import asyncio

from fast_agent import FastAgent
from fast_agent.agents.agent_types import AgentConfig
from fast_agent.agents.tool_agent import ToolAgent
from fast_agent.agents.tool_runner import ToolRunnerHooks
from fast_agent.context import Context
from fast_agent.interfaces import ToolRunnerHookCapable
from fast_agent.types import PromptMessageExtended


def get_video_call_transcript(video_id: str) -> str:
    return "Assistant: Hi, how can I assist you today?\n\nCustomer: Hi, I wanted to ask you about last invoice I received..."


class HookedToolAgent(ToolAgent, ToolRunnerHookCapable):
    def __init__(self, config: AgentConfig, context: Context | None = None):
        super().__init__(config, [get_video_call_transcript], context)
        self._hooks = ToolRunnerHooks(
            before_llm_call=self._add_style_hint,
            after_tool_call=self._log_tool_result,
        )

    @property
    def tool_runner_hooks(self) -> ToolRunnerHooks | None:
        return self._hooks

    async def _add_style_hint(
        self, runner, messages: list[PromptMessageExtended]
    ) -> None:
        if runner.iteration == 0:
            runner.append_messages("Keep the answer to one short sentence.")

    async def _log_tool_result(self, runner, message: PromptMessageExtended) -> None:
        if message.tool_results:
            tool_names = ", ".join(message.tool_results.keys())
            print(f"[hook] tool results received: {tool_names}")


fast = FastAgent("Example Tool Use Application (Hooks)")


@fast.custom(HookedToolAgent)
async def main() -> None:
    async with fast.run() as agent:
        await agent.default.generate("What is the topic of the video call no.1234?")


if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Use GPT-5.2 Codex Planning Model

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/models/llm_providers.md

Command to start fast-agent using a specific GPT-5.2 Codex planning model alias via OAuth.

```bash
# Use the GPT-5.2 Codex planning model via OAuth
fast-agent --model codexplan52
```

--------------------------------

### Start fast-agent as an MCP stdio Server

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/agents/running.md

Deploys the fast-agent application as a stdio server for inter-process communication.

```bash
# Start as a stdio server
uv run agent.py --transport stdio
```

--------------------------------

### Run agent_two (Linux/MacOS)

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/mcp/state_transfer.md

Starts agent_two, which can then receive the conversation context from agent_one via an MCP Prompt.

```bash
# start agent_two as an MCP Server:
uv run agent_two.py
```

--------------------------------

### Start fast-agent with the codex pack

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/guides/codex.md

Use this command to launch `fast-agent` pre-configured for a Codex-style coding workflow. It includes a dev agent, search helper, and WebSocket transport.

```bash
uvx fast-agent-mcp@latest --pack codex
```

--------------------------------

### Run Custom Elicitation Handler Demo

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/mcp/elicitations.md

Starts the custom elicitation handler demonstration where the agent generates a game character using a custom handler.

```bash
uv run game_character.py
```

--------------------------------

### Configure prompt-server in fastagent.config.yaml

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/agents/prompting.md

Configure an MCP Server to serve prompt files and resources using the 'prompt-server' command. This example shows how to serve 'prompt_secret_plans.txt'.

```yaml
mcp:
  servers:
    prompts:
      command: "prompt-server"
      args: ["prompt_secret_plans.txt"]
```

--------------------------------

### Configure Agent Request Parameters

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/agents/defining.md

Example of defining an agent with custom request parameters like maxTokens, use_history, and max_iterations.

```python
from fast_agent.types import RequestParams

@fast.agent(
  name="CustomAgent",                              # name of the agent
  instruction="You have my custom configurations", # base instruction for the agent
  request_params=RequestParams(
    maxTokens=8192,
    use_history=False,
    max_iterations=20
  )
)
```

--------------------------------

### Start Interactive Session with AgentApp

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/ref/class_reference.md

Initiate an interactive prompt session with a specified agent. Allows for a default prompt and options for pretty printing parallel responses.

```python
await agent.interactive(
    agent_name: str | None = None,
    default_prompt: str = "",
    pretty_print_parallel: bool = False,
    request_params: RequestParams | None = None,
) -> str
```

--------------------------------

### Connect to mcp-ui demo server

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/mcp/mcp-ui.md

Connect to a local mcp-ui demo server using a specific model like gpt-5-mini with low reasoning effort. The URL should point to your running demo server.

```bash
fast-agent --url http://localhost:3000 --model=gpt-5-mini.low
```

--------------------------------

### Install Privacy Extra with pip

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/guides/privacy_filter.md

Install the privacy extra for fast-agent-mcp using pip.

```bash
pip install "fast-agent-mcp[privacy]"
```

--------------------------------

### Install Privacy Extra with uv pip

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/guides/privacy_filter.md

Install the privacy extra for fast-agent-mcp using uv pip.

```bash
uv pip install "fast-agent-mcp[privacy]"
```

--------------------------------

### Install fast-agent with Privacy Dependencies

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/guides/privacy_filter.md

Install fast-agent with the necessary privacy-related dependencies using uv tool.

```bash
uv tool install -U "fast-agent-mcp[privacy]"
```

--------------------------------

### Instruction from URL

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/agents/instructions.md

Load agent instructions directly from an HTTP(S) URL using `pydantic.AnyUrl`. This is convenient for referencing prompts hosted online.

```python
from pydantic import AnyUrl

@fast.agent(name="mcp-expert",
    instruction=AnyUrl("https://gist.githubusercontent.com/evalstate/d432921aaaee2c305cf46ae320840360/raw/eb9c7ff93adc780171bfb0ae2560be2178304f16/gistfile1.txt"))

# --> fast-agent system prompt demo
```

--------------------------------

### Start an interactive fast-agent session

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/index.md

Initiate an interactive session with fast-agent. This command starts a local session.

```bash
fast-agent go

```

--------------------------------

### Basic fast-agent serve command

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/mcp/mcp-server.md

Use this command to start a Streamable HTTP MCP Server. It allows specifying the URL of an MCP server, instance scope for agent state isolation, a custom description for the tool, and the model to use.

```bash
fast-agent serve \
  --url https://huggingface.co/mcp \
  --instance-scope connection \
  --description "Interact with the {agent} workflow" \
  --model haiku
```

--------------------------------

### Install fast-agent with specific Python version

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/guides/hf-dev.md

Installs the `fast-agent-mcp` executable using `uv` for a specific Python version, such as 3.13.

```bash
uv tool install --python 3.13 -U fast-agent-mcp
```

--------------------------------

### Define Agents with Default and Named Instructions

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/agents/defining.md

Demonstrates creating agents with default names and specific names along with their instructions.

```python
@fast.agent("You are a helpful agent")          # Create an agent with a default name.
@fast.agent("greeter","Respond cheerfully!")    # Create an agent with the name "greeter"
```

--------------------------------

### fast-agent serve with npx and custom prompt

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/mcp/mcp-server.md

This command starts an MCP Server using a specific npm package for the server implementation. It configures the instance scope to 'request' for stateless operation, provides a custom description, and uses a system prompt from a file.

```bash
fast-agent serve \
  --npx @modelcontextprotocol/server-everything \
  --instance-scope request \
  --description "Ask me anything!" \
  -i system_prompt.md \
  --model kimi
```

--------------------------------

### TensorZero Model Invocation Example

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/models/llm_providers.md

Example of invoking a TensorZero function as a model name, prefixed with 'tensorzero.'. This leverages the OpenAI-compatible inference API.

```bash
uv run agent.py --model=tensorzero.test_chat
```

--------------------------------

### Instruction from Local File

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/agents/instructions.md

Load agent instructions from a local file using `pathlib.Path`. This allows for easier editing of complex prompts.

```python
from pathlib import Path

@fast.agent(name="mcp-expert",
    instruction=Path("./mcp-expert.md"))
async def main():
    pass
```

--------------------------------

### Quick Start: Anthropic ACP Agent

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/acp/index.md

Set the ANTHROPIC_API_KEY environment variable and run the fast-agent-acp command with a specified model for a quick start with Anthropic.

```bash
export ANTHROPIC_API_KEY=......

uvx fast-agent-acp@latest --model <your_model> e.g. [sonnet]
```

--------------------------------

### Display Fast-Agent Configuration File

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/ref/cmd_switches.md

Use the 'show' subcommand with the check command to display the contents of the configuration file.

```bash
fast-agent check show
```

--------------------------------

### Run a Model Overlay from CLI

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/models/model_overlays.md

This command demonstrates how to use a defined model overlay token ('qwen-local') to run a fast-agent task. The overlay's configuration will be applied during model creation.

```bash
fast-agent go --model qwen-local
```

--------------------------------

### Example Privacy Filter Redaction Summary

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/guides/privacy_filter.md

This is an example of the summary output when the privacy filter is used during an export, showing the counts of different types of redacted data.

```text
Privacy filter redacted 12 text span(s) in 4.3s:
  private_email: 3
  private_person: 4
  secret: 5
```

--------------------------------

### Use Kimi Presets and Instant Mode

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/models/llm_providers.md

Select Kimi presets for different modes (thinking or instant). Instant mode disables reasoning.

```bash
fast-agent --model "hf.moonshotai/Kimi-K2.6?instant=on"   # instant mode
fast-agent --model "hf.moonshotai/Kimi-K2.6?instant=off"  # thinking mode
fast-agent --model "hf.moonshotai/Kimi-K2.5?instant=on"   # legacy Kimi 2.5 instant mode
```

--------------------------------

### Scaffold Agent and Configuration files

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/index.md

Generate initial Agent and Configuration files for Python development using fast-agent.

```bash
fast-agent scaffold

```

--------------------------------

### Connect to STDIO server

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/ref/go_command.md

Use the `--stdio` option to run a command and attach a STDIO server. Enclose command arguments in quotes.

```bash
fast-agent go --stdio "<command> <options>"
```

--------------------------------

### Quick Start: Hugging Face ACP Agent

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/acp/index.md

Set the HF_TOKEN environment variable and run the fast-agent-acp command with a specified model for a quick start with Hugging Face.

```bash
export HF_TOKEN=hf_.......

uvx fast-agent-acp@latest --model <your_model> [e.g. kimi]
```

--------------------------------

### Update Installed Skills

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/agents/skills.md

Check for and apply updates to your installed skills using the `/skills update` command. You can update specific skills by name or number, or update all managed skills.

```bash
/skills update
/skills update skill-name
/skills update 1
/skills update all
```

--------------------------------

### Run fast-agent with an instruction file

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/getting_started.md

Execute fast-agent using instructions from a local Markdown file or a URL.

```bash
fast-agent go -i prompt.md
```

```bash
fast-agent go -i https://gist.github.com/....

```

--------------------------------

### Instruction with URL Content

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/agents/instructions.md

Load agent instructions by embedding content from a specified URL using the `{{url:...}}` syntax. This allows for dynamic fetching of prompt components.

```python
@fast.agent(name="mcp-expert",
    instruction="""
    You are have expert knowledge of the
    MCP (Model Context Protocol) schema.

    {{url:https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/refs/heads/main/schema/2025-11-25/schema.ts}}

    Answer any questions about the protocol by referring
    to and quoting the schema where necessary.
    """)
```

--------------------------------

### Load Prompt File from Hugging Face Hub

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/ref/cmd_switches.md

Load a prompt file directly from Hugging Face Hub storage using a `hf://` URI.

```bash
uv run agent.py --prompt-file hf://buckets/evalstate/home/demo.md
```

--------------------------------

### Start ACP Agent with Hugging Face MCP Server

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/acp/index.md

Starts an ACP Agent with shell access enabled and configured to use the Hugging Face MCP Server, authenticating with a provided token.

```bash
fast-agent-acp -x --model kimi --url https://huggingface.co/mcp --auth ${HF_TOKEN}
```

--------------------------------

### Defining Agents

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/agents/defining.md

Provides an example of defining a basic agent with various configuration options.

```APIDOC
### Defining Agents

#### Basic Agent

```python
@fast.agent(
  name="agent",                          # name of the agent
  instruction="You are a helpful Agent", # base instruction for the agent
  servers=["filesystem"],
  #tools={"filesystem": ["tool_1", "tool_2"]}
  #resources={"filesystem": ["resource_1", "resource_2"]}
  #prompts={"filesystem": ["prompt_1", "prompt_2"]}
  #function_tools=[helper_fn, "tools.py:other_helper"],
  model="o3-mini.high",
  use_history=True,
  request_params=RequestParams(temperature= 0.7),
  human_input=True,
  elicitation_handler=ElicitationFnT,
  api_key="programmatic-api-key",
)
```

Workflow definitions (chain/parallel/router/orchestrator/maker) are documented on the [Workflows](workflows.md) page.
```

--------------------------------

### Run Agent with Async Context Manager

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/ref/class_reference.md

Use the `fast.run()` async context manager to initialize registered agents and obtain an `AgentApp` instance for interaction.

```python
async with fast.run() as agent:
    # Use agent here
```

--------------------------------

### Use Curated Hugging Face Presets

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/models/llm_providers.md

Select curated Hugging Face presets directly via the command line for convenience.

```bash
fast-agent --model kimi26
fast-agent --model kimi26instant
fast-agent --model deepseek32
fast-agent --model qwen35
```

--------------------------------

### Regenerate Docs with Local Checkout

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/ref/generated_docs.md

If `fast_agent` is not installed in the docs venv, use this command to run against a local checkout.

```bash
FAST_AGENT_REPO_PATH=../fast-agent uv run python generate_reference_docs.py
```

--------------------------------

### Install fast-agent-mcp for a specific Python version

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/getting_started.md

If you have multiple Python versions, pin the one required by fast-agent using this command.

```bash
uv tool install -U fast-agent-mcp --python 3.13.5
```

--------------------------------

### Run UVX package as STDIO server

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/ref/go_command.md

Use the `--uvx` option to run a UVX package as a STDIO server. Enclose package and arguments in quotes.

```bash
fast-agent go --uvx "@package/name <options>"
```

--------------------------------

### Start fast-agent as an MCP HTTP Server

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/agents/running.md

Deploys the fast-agent application as a Streamable HTTP server. Accessible at http://localhost:8080/mcp.

```bash
# Start as a Streamable HTTP server (http://localhost:8080/mcp)
uv run agent.py --transport http --port 8080
```

--------------------------------

### Load and Use Playback Model with Fast-Agent

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/models/internal_models.md

Demonstrates how to load a conversation from a file using `load_message_multipart` and then use the playback agent to generate responses and structured outputs.

```python
@fast.agent(name="playback",model="playback")

...

playback_messages: List[PromptMessageExtended] = load_message_multipart(Path("playback.txt"))
# Set up the Conversation
assert ("HISTORY LOADED") == agent.playback.generate(playback_messages)

response: str = agent.playback.send("Good morning!") # Returns Hello
temperature, _ = agent.playback.structured("Generate some JSON")
```

--------------------------------

### Common Configuration Format

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/models/llm_providers.md

Example of common configuration parameters for LLM providers in fastagent.config.yaml. The API key can be overridden by an environment variable.

```yaml
anthropic:
  api_key: "your_api_key" # Override with API_KEY env var
  base_url: "https://api.example.com" # Base URL for API calls
  default_headers: # Optional - custom headers for all API requests
    X-Custom-Header: "value"
```

--------------------------------

### FastAPI Integration with FastAgent

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/ref/class_reference.md

Example of integrating FastAgent with FastAPI, setting up a lifespan for the FastAgent and defining an API endpoint to interact with agents.

```python
from contextlib import asynccontextmanager

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

from fast_agent.core.fastagent import FastAgent

# Create FastAgent without parsing CLI args (plays nice with uvicorn)
fast = FastAgent("fast-agent demo", parse_cli_args=False, quiet=True)


# Register a simple default agent via decorator
@fast.agent(name="helper", instruction="You are a helpful AI Agent.", default=True)
async def decorator():
    pass


# Keep FastAgent running for the app lifetime
@asynccontextmanager
async def lifespan(app: FastAPI):
    async with fast.run() as agents:
        app.state.agents = agents
        yield


app = FastAPI(lifespan=lifespan)


class AskRequest(BaseModel):
    message: str


class AskResponse(BaseModel):
    response: str


@app.post("/ask", response_model=AskResponse)
async def ask(req: AskRequest) -> AskResponse:
    try:
        result = await app.state.agents.send(req.message)
        return AskResponse(response=result)
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))
```

--------------------------------

### Register Custom Elicitation Handler

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/mcp/elicitations.md

Example of registering a custom elicitation handler within a fast.agent decorator. The handler is imported from 'game_character_handler.py'.

```python
@fast.agent(
    "character-creator",
    servers=["elicitation_forms_server"],
    # Register our handler from game_character_handler.py
    elicitation_handler=game_character_elicitation_handler,
)
```

--------------------------------

### Use Prompt from Hugging Face Hub

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/ref/go_command.md

Uses a prompt file stored in Hugging Face Hub generic storage.

```bash
fast-agent go --prompt-file hf://buckets/evalstate/home/demo.md --model=haiku
```

--------------------------------

### Load Prompt File

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/ref/cmd_switches.md

Load and apply a prompt from a local file. Ensure the file path is correct.

```bash
uv run agent.py --prompt-file my_conversation.txt
```

--------------------------------

### Minimal fast-agent OAuth Configuration

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/mcp/mcp-oauth.md

Example configuration for enabling OAuth on a specific MCP server. OAuth is enabled by default for HTTP/SSE servers.

```yaml
mcp:
  servers:
    myserver:
      transport: http                    # (optional, defaults to http) or sse
      url: http://localhost:8001/mcp     # use /sse for SSE
      auth:
        oauth: true                      # default true
        persist: keyring                 # default keyring; use memory to disable persistence
        redirect_port: 3030              # default 3030
        redirect_path: /callback         # default /callback
        # scope: "user"                  # optional (server defaults used if omitted)
```

--------------------------------

### Model Overlay Configuration

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/ref/config_file.md

Define local, environment-specific model configurations with custom providers, base URLs, and defaults. Use overlays for short local tokens like `qwen-local`.

```yaml
name: qwen-local
provider: openresponses
model: unsloth/Qwen3.5-9B-GGUF
connection:
  base_url: http://localhost:8080/v1
  auth: none
defaults:
  temperature: 0.8
  top_p: 0.95
  max_tokens: 2048
metadata:
  context_window: 75264
  max_output_tokens: 2048
picker:
  label: Qwen local
  description: Imported from llama.cpp
  current: true

```

--------------------------------

### Prompt File Including Resource

Source: https://github.com/evalstate/fast-agent-docs/blob/main/docs/agents/index.md

Prompt files can reference resources. This example shows a prompt file that requests extraction of colors from `index.css`.

```markdown
---
USER
Please extract the major colours from this CSS file:
---
RESOURCE
index.css
```