Agent Client Protocol

fast-agent has comprehensive support for Zed Industries Agent Client Protocol.

Why use fast-agent?:

Robust, native LLM Provider infrastructure, with Streaming and Structured outputs.
Comprehensive MCP and Agent Skills support, including Tool Progress Notifications and Sampling.
Build custom, multi-agent experiences in a few lines of code.

Features

Feature	Support	Notes
Modes	✅	Each defined Agent appears as a Mode
Tool / Workflow Progress	✅	MCP Tool Progress and Agent Workflow Progress updates
Agent Plan	✅	Iterative Planner reports progress using Agent Plan
Cancellation	✅	LLM Streaming Cancellation
Multimodal	✅	Support for Images
Slash Commands	✅	Save, Load, Status and Clear/Clear Last message
File System / Terminal	✅	Start with `-x` option to enable access to Client terminal
MCP Servers	✅	MCP Servers supplied by the Client are attached to the Agent
Sessions	✅	Session listing supported

ACP MCP commands distinguish inventory, status, configured attachment, and ad-hoc connection:

/mcp list lists attached and configured-but-detached servers.
/mcp status shows detailed MCP connection status.
/mcp attach <name> attaches a configured registry entry.
/mcp connect <target> connects an ad-hoc target.
/connect <name|target> attaches a configured name or connects an ad-hoc target.

Getting Started

Customizing Agents

See Customizing Agents for building ACP-aware agents, slash commands, and controlling the ACP Mode display name/description.

No Install Quick Start:

To try it out immediately with your Client: simply set an API Key environment variable and run:

Hugging Face

export HF_TOKEN=hf_.......
uvx fast-agent-acp@latest --model kimi

OpenAI

export OPENAI_API_KEY=......
uvx fast-agent-acp@latest --model "gpt-5-mini?reasoning=low"

Anthropic

export ANTHROPIC_API_KEY=......
uvx fast-agent-acp@latest --model sonnet

Tip: Use uvx fast-agent-acp check to help diagnose issues.

The default system prompt will read AGENTS.md if present. Use /status system to check.

Note: OAuth keys are stored in your keyring, so check may prompt to read the credential store.

Security note: ACP runs as a local agent process started by an ACP-compatible client. An HF_TOKEN configured in the ACP process environment is a server-side credential for model and MCP calls; it is not an inbound web authentication gate. For public HTTP deployments that should require Hugging Face auth before tool execution, use the MCP or A2A server transports with FAST_AGENT_SERVE_OAUTH=huggingface.

An example Zed configuration is:

...
"agent_servers": {
    "fast-agent-uvx": {
        "command": "uvx",
        "args": [
        "fast-agent-acp@latest",
        "--model",
        "kimi",
        "-x",
        "--url",
        "https://huggingface.co/mcp"
        ],
        "env": { "HF_TOKEN": "hf_xxxxxxxxxxx" }
    }
}

Hugging Face Inference ACP (`hf-inference-acp`)

hf-inference-acp is a dedicated ACP agent for Hugging Face Inference Providers (built on fast-agent-mcp).

Run: uvx hf-inference-acp@latest
Setup mode (when HF_TOKEN is missing) includes: /set-model (lists suggested models when called with no args), /login, /check
/set-model accepts alias, hf.<org>/<model>[:provider], or <org>/<model> (auto-adds hf. and can display available providers)

Installing

uv tool install -U fast-agent-mcp

The ACP Server can then be started with the fast-agent-acp command. Custom agents can be started with uv run <agent.py> --transport acp.

For example:

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

Starts an ACP Agent, with shell access and access to the Hugging Face MCP Server.

Documentation in Progress.

Shell and File Access

fast-agent adds the read and write tools from the Client to enable "follow-along" functionality.

When shell mode is enabled with -x / --shell, fast-agent will normally use the ACP client's terminal capability if the client advertises one. If you want commands to run in the fast-agent process instead, use:

fast-agent-acp -x --prefer-local-shell

The same option is available when using the generic server command:

fast-agent serve --transport acp -x --prefer-local-shell

You can also make this the default in fast-agent.yaml:

shell_execution:
  prefer_local_shell: true

Permissions

Tool calls in ACP mode prompt for permission by default. You will see options for Allow Once / Always Allow / Reject Once / Never Allow.

Disable prompts entirely with fast-agent-acp --no-permissions (all tools are allowed).
Persistent “Always” decisions are stored in the fast-agent home (default .fast-agent/auths.md) so you can audit or edit them later. The file is only created when you choose an “Always” option.
“Once” decisions are remembered only for the current session and are not written to disk. Removing the permissions file clears any saved Always rules. Use fast-agent --home <path> or home in the config file to relocate the home.

`--no-home` in ACP mode

Use fast-agent-acp --no-home (or fast-agent serve --transport acp --no-home) for ephemeral runs.

Session persistence and resume are disabled.
Slash session operations are disabled.
ACP tool permission prompts and permission-store writes (auths.md) are disabled.

Conflicts (fail fast):

--no-home + --home
--no-home + --resume

Structured Outputs

Experimental support for returning Structured Outputs is available.