fast-agent: a CLI-first Python framework for building, running and evaluating MCP agents
Code, Build and Evaluate agents - excellent Model and Skills/MCP/ACP/A2A Support
At a glance
- What is it?
- fast-agent is an Apache-2.0 Python toolkit that treats agent prompts and MCP server wiring as versionable files, and ships a terminal client for chatting with agents before, during and after a workflow. The core judgement: its MCP feature coverage and transport diagnostics are the reason to pick it, while the rapid 0.10.x release cadence is the reason to pin versions.
- Who is it for?
- Adopt fast-agent if you are building MCP-connected agents in Python and want the agent definition to live in a file you can diff, plus a terminal client that lets you interrogate a running workflow. Do not adopt it if you need a stable API surface across a long release cycle, or if your agents are simple single-call wrappers where the MCP and Skills machinery is dead weight.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem fast-agent targets: agent wiring that lives nowhere in particular
Most agent code starts as a script and ends as a configuration problem. The prompt text, the tool list, the model name and the MCP server endpoints all end up scattered between Python literals, environment variables and a shell history. fast-agent's answer is to make the agent definition a file. The README states that prompts and configurations defining your Agent Applications are stored in simple files with minimal boilerplate, which the project frames as enabling management and version control. That is the whole thesis. If you have ever needed to answer what exactly changed in the agent between last Tuesday and today, the file-based approach is the feature you are buying. The audience is Python developers who are already committed to MCP as their tool transport and who want the agent layer to be inspectable rather than generated. It is not aimed at people who want a hosted agent builder, and it is not aimed at people writing a single LLM call. The scope is deliberately wide: the README describes the project as usable as a coding agent, a development toolkit, and an evaluation or workflow platform, which is three different jobs sharing one runtime.
Declarative agents, card packs and the go command
The mechanism visible in the README is a decorator-based declarative syntax. A basic agent is defined with an @fast decorator followed by the prompt body, which keeps the prompt adjacent to the agent's identity rather than buried in a function argument. Around that sits a layer the README calls card packs. A pack is a packaged starter agent, installed into the selected fast-agent home on demand, and launched with fast-agent go --pack <name> --model <model>. The precedence rule is stated explicitly: --model acts as a fallback for cards without an explicit model setting, and a model declared directly in an AgentCard still wins. That ordering matters in practice, because it means passing --model does not silently override a pack author's intent, and it means a pack with a hardcoded model cannot be retargeted from the command line without editing the card. The interactive surface is a prompt_toolkit-powered terminal prompt with completions and in-terminal menus, streaming responses through rich rather than a full-screen curses interface. The README also lists a registry of skills reachable through the /skills command, covering LSP setup, Agent and Tool Hooks, compaction strategies and automation. Skills are SKILL.md files, so the same file-based principle applies to capability as to prompts.
MCP transport, Sampling, Elicitations and the diagnostics view
This is where fast-agent makes its strongest specific claim. The README says it is the first framework with complete, end-to-end tested MCP Feature support including Sampling and Elicitations, and that it is the only tool allowing inspection of Streamable HTTP Transport usage. Treat the superlatives as marketing, but the underlying capability is concrete: MCP Sampling lets a server ask the client's model to generate, and Elicitations let a server request structured input from the user, and both require the client to route requests back through the model and the terminal. A framework that only implements tool calls will silently fail on servers that use either. The README also shows a screenshot of MCP Transport Diagnostics, which suggests the project treats transport-level debugging as a first-class surface rather than something you diagnose from logs. Connection is handled at runtime with /connect, which the README says supports stdio or streamable http with OAuth, and gives two examples: /connect @modelcontextprotocol/server-everything for a stdio server, and /connect https://huggingface.co/mcp for a streamable HTTP endpoint. OAuth secrets are stored in the system keyring, managed through the fast-agent auth command. If you are deploying against an MCP server behind OAuth, that keyring-backed flow is the part worth reading the docs for before you write your own token handling.
Getting it running: uvx, packs and the model configuration rule
The README gives several entry points and they are not interchangeable. The fastest is uvx fast-agent-mcp@latest -x, which starts an interactive session with shell support. For coding-oriented setups there are packs: uvx fast-agent-mcp@latest --pack hf-dev for Hugging Face inference providers, and uvx fast-agent-mcp@latest --pack codex for agents optimized for OpenAI. The README recommends a persistent install to get shell aliases and tooling, via uv tool install -U fast-agent-mcp, after which fast-agent --model opus -xx runs with shell support and built-in subagents. Local models go through the generic provider, or fast-agent model llamacpp generates the configuration automatically. Project scaffolding is fast-agent scaffold, which creates an example agent and config files, and the resulting script runs with uv run agent.py. The model rule is the one that will bite you: with no configured model, an interactive run opens the model picker, but the README states that automation and server runs must pass --model, set FAST_AGENT_MODEL, configure default_model, or declare a model on the agent. A server started without one of those four will not resolve a model. Model overrides can carry parameters, as in uv run agent.py --model='gpt-5.4-mini?reasoning=low'. Exposing the same script as an MCP server is uv run agent.py --transport http --port 8001, where server mode is implied by the transport flag. Shell access inside the session is entered with !, for example ! cd web && npm run build.
Where fast-agent is the wrong tool
Three cases stand out. First, if your agent is one prompt and one API call, the card system, the pack installer, the skills registry and the MCP client are all overhead you will pay for and never use. Second, if you need a frozen API surface, the release history in the repository metadata is a warning: v0.10.17, v0.10.10 and v0.9.30 all landed within roughly six weeks of each other, and the minor version has already crossed 0.10. Any project moving at that pace will rename things. Pin the version and read release notes before upgrading. Third, if your provider is not one of the native Anthropic, OpenAI or Google integrations, you are on the generic provider or the TensorZero path, and the README does not describe the failure modes there. The README does flag one platform-specific caveat directly: Windows users need configuration changes for the Filesystem and Docker MCP servers, documented inside the configuration files themselves rather than in the main text. That is a thin place in the documentation, and it is the kind of thing you discover at setup time rather than from the README. There is also a naming trap: the PyPI package is fast-agent-mcp while the installed command is fast-agent, so searching for the project name in a requirements file will not find it.
How it differs from LangGraph and the OpenAI Agents SDK
The nearest comparison is LangGraph, and the difference is the unit of composition. LangGraph models an agent as a graph of nodes and edges that you construct in Python, with state passed between nodes; the graph is the artifact and the prompt lives inside a node function. fast-agent inverts this. The agent definition and its prompt are declarative files, and the composition is expressed by which agents and MCP servers you attach, not by an explicit graph you draw. That makes fast-agent easier to diff and review, and harder to express genuinely branching control flow. The README points at Anthropic's building effective agents as the conceptual reference and offers fast-agent quickstart workflow to generate those examples, so the intended shape is the common pattern set (prompt chaining, routing, evaluator-optimizer) rather than arbitrary graphs. Its Researcher Agent example uses an Evaluator-Optimizer workflow, which is one of those named patterns. Against the OpenAI Agents SDK the split is provider posture: that SDK is built around OpenAI's own model and tooling, whereas fast-agent treats provider choice as configuration, with native Anthropic, OpenAI and Google support plus Azure, Ollama, Deepseek and others through TensorZero. If you are single-provider and single-language, the SDK's tighter integration may cost you less. If you are routing across providers or need MCP Sampling and Elicitations, fast-agent's transport layer is the differentiator.
Licence, maintenance and what an upgrade actually costs
The repository is Apache-2.0, which permits commercial use, modification and redistribution provided you retain the licence and notices, and it includes an express patent grant. That is the permissive end of the spectrum and imposes no copyleft obligation on your own code. This is a description of the licence text, not legal advice; if you are embedding the project in a distributed product, have counsel confirm the notice requirements. Maintenance cost is dominated by the release cadence. Three tagged releases inside roughly six weeks means the practical upgrade unit is a version pin plus a release-note read, not a rolling latest. The uvx fast-agent-mcp@latest form in the README is convenient for trying the tool and unsuitable for a production pipeline for exactly that reason. The counterweight is that the project is not archived, the default branch is active, and the README states that documentation lives in the repository under docs/ with a helper script for installing, generating, building, serving, screenshotting and assessing the site. That means you can read the docs at the version you pinned rather than only at the website. The docs helper script is also the thing to run first if you intend to contribute, since it is the project's own path to a working local docs build.
Editorial conclusion
Adopt fast-agent if you are building MCP-connected agents in Python and want the agent definition to live in a file you can diff, plus a terminal client that lets you interrogate a running workflow. Do not adopt it if you need a stable API surface across a long release cycle, or if your agents are simple single-call wrappers where the MCP and Skills machinery is dead weight. Before committing, verify three things against your own setup: that your provider is reachable through the generic or TensorZero path if it is not one of the native Anthropic, OpenAI or Google providers, that your chosen model is passed explicitly for any non-interactive run, and that the pack you intend to use declares a model in its AgentCard rather than relying on the --model fallback.
Community notes