go Command

Start interactive agent sessions directly from the command line

Overview

The go command launches an interactive agent session without requiring a separate agent.py file. It’s the fastest way to start chatting with an AI agent and test MCP server integrations.

fast-agent go                          # Start with default configuration
fast-agent go --model=sonnet          # Use a specific model
fast-agent go --url https://hf.co/mcp # Connect to a remote MCP server
fast-agent go -x                      # Enable shell runtime

Usage

fast-agent go [OPTIONS]

Options

Agent Configuration

--name · string · default: "fast-agent"

Name for the agent instance.

--instruction · string

Path to file or URL containing instruction for the agent. Sets the base system prompt.

fast-agent go --instruction instructions.txt
fast-agent go -i https://example.com/prompt.txt

--model · string

Override the default model. Supports model aliases and full identifiers.

fast-agent go --model=haiku
fast-agent go --model=gpt-4
fast-agent go --model=generic.qwen2.5
fast-agent go --models=opus,sonnet  # Multi-model mode

--agent · string

Target a specific agent by name for messages and initial interactive mode.

MCP Server Configuration

--config-path · string

Path to fastagent.config.yaml file. If not specified, searches recursively from current directory.

fast-agent go --config-path ./config/fastagent.config.yaml
fast-agent go -c ./fastagent.config.yaml

--servers · string

Comma-separated list of server names to enable from config.

fast-agent go --servers filesystem,docker
fast-agent go --servers fetch,brave

--url · string

Comma-separated list of HTTP/SSE URLs to connect to.

fast-agent go --url https://hf.co/mcp
fast-agent go --url https://api.example.com/mcp,https://api2.example.com/mcp

--auth · string

Authorization token value for URL-based servers. The ‘Bearer ’ prefix is optional.

fast-agent go --url https://api.example.com/mcp --auth YOUR_TOKEN

--client-metadata-url · string

OAuth Client ID Metadata Document URL for servers that don’t support dynamic client registration.

Agent Cards

--agent-cards · string

Path or URL to an AgentCard file or directory. Can be specified multiple times.

fast-agent go --agent-cards ./cards/
fast-agent go --card https://example.com/agent.md

--card-tool · string

Path or URL to an AgentCard file or directory to load as tools. Can be specified multiple times.

fast-agent go --card-tool ./tool-cards/

STDIO MCP Servers

--npx · string

NPX package and args to run as MCP server (quoted).

fast-agent go --npx "@modelcontextprotocol/server-filesystem /tmp"

--uvx · string

UVX package and args to run as MCP server (quoted).

fast-agent go --uvx "mcp-server-fetch"

--stdio · string

Command to run as STDIO MCP server (quoted).

fast-agent go --stdio "python mcp_server.py"

Message Handling

--message · string

Message to send to the agent. Skips interactive mode and exits after response.

fast-agent go --message "What is the weather in New York?"
fast-agent go -m "Explain quantum computing"

--prompt-file · string

Path to a prompt file to use (either text or JSON).

fast-agent go --prompt-file ./prompts/analyze.txt
fast-agent go -p ./prompts/data.json

--results · string

Write resulting history to file. For multi-model mode, creates per-model suffixed files.

fast-agent go --results output.json

Session Management

--resume · string

Resume the last session or a specified session ID.

fast-agent go --resume              # Resume last session
fast-agent go --resume session-123  # Resume specific session

--reload · boolean · default: false

Enable manual AgentCard reloads via /reload command.

fast-agent go --reload

--watch · boolean · default: false

Watch AgentCard paths and reload automatically when files change.

fast-agent go --watch

Environment

--env · path

Override the base fast-agent environment directory.

fast-agent go --env ~/.fast-agent-dev

--noenv · boolean · default: false

Run without implicit environment-side effects.

fast-agent go --noenv

--skills-dir · path

Override the default skills directory.

fast-agent go --skills-dir ./my-skills

Shell Runtime

--shell · boolean · default: false

Enable a local shell runtime and expose the execute tool (bash or pwsh).

fast-agent go --shell
fast-agent go -x

Shell runtime gives the agent access to execute commands on your system. Only use with trusted models and prompts.

Smart Agent

--smart · boolean · default: false

Prefer a smart default agent when fast-agent creates the default agent.

fast-agent go --smart

Output Control

--quiet · boolean · default: false

Disable progress/chat/tool output and print only direct command output.

fast-agent go --quiet --message "Calculate 2+2"
fast-agent go -q -m "What is the capital of France?"

Examples

Basic Interactive Session

fast-agent go

Starts an interactive session with default configuration. You can chat with the agent and use slash commands.

With MCP Servers from Config

fast-agent go --servers filesystem,fetch

Launches an agent with the filesystem and fetch MCP servers defined in your config.

Remote MCP Server

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

Connects to a remote MCP server over HTTP.

With Shell Access

fast-agent go -x

Enables the shell runtime, allowing the agent to execute system commands.

One-Shot Query

fast-agent go --message "List files in current directory" --servers filesystem --quiet

Sends a single message, gets a response, and exits. Use --quiet to suppress extra output.

Multi-Model Comparison

fast-agent go --models=opus,sonnet,haiku --message "Explain recursion"

Sends the same prompt to multiple models and displays responses side-by-side.

With Custom Model

fast-agent go --model=generic.qwen2.5

Uses Ollama’s Qwen 2.5 model through the generic provider.

With Agent Cards

fast-agent go --agent-cards ./cards/ --watch

Loads agent cards from a directory and watches for changes.

Resume Previous Session

fast-agent go --resume

Continues your last conversation with full context preserved.

Interactive Mode

When running in interactive mode, you can use slash commands:

Command	Description
/help	Show available commands
/exit or /quit	Exit the session
/clear	Clear conversation history
/model	Switch models
/agent	Switch between agents (if multiple loaded)
/tools	List available MCP tools
/prompt	Apply an MCP prompt
/reload	Reload agent cards (with —reload flag)

Multi-Model Mode

Specify multiple models with comma-separated values:

fast-agent go --models=opus,sonnet,haiku

In multi-model mode:

• The same message is sent to all models
• Responses are displayed side-by-side
• Results can be saved to separate files

Environment Detection

fast-agent prevents running nested shell sessions:

# If already inside a fast-agent shell:
fast-agent go
# Error: fast-agent is already running inside a fast-agent shell command

Exit the shell or unset FAST_AGENT_SHELL_CHILD to continue.

Configuration Precedence

Settings are applied in this order (later overrides earlier):

1. Default values
2. Config file (fastagent.config.yaml)
3. Environment variables
4. Command-line options

Related Commands

scaffold

Create config files for persistent agent definitions

auth

Manage OAuth tokens for MCP servers

check

Verify your configuration and API keys

serve

Run fast-agent as an MCP server