Overview
The FastAgent class is the core entry point for building Fast Agent applications. It provides decorators for defining agents, manages agent lifecycle, supports AgentCard loading, and handles configuration.
Constructor
FastAgent(
name: str,
config_path: str | None = None,
ignore_unknown_args: bool = False,
parse_cli_args: bool = True,
quiet: bool = False,
environment_dir: str | pathlib.Path | None = None,
skills_directory: str | pathlib.Path | Sequence[str | pathlib.Path] | None = None,
**kwargs
)
Optional path to YAML configuration file
Whether to ignore unknown command line arguments when parse_cli_args is True
If True, parse command line arguments using argparse. Set to False when embedding FastAgent in another framework (like FastAPI/Uvicorn) that handles its own arguments
If True, disable progress display, tool and message logging for cleaner output
environment_dir
str | pathlib.Path | None
default:"None"
Override the base fast-agent environment directory (.fast-agent by default)
skills_directory
str | pathlib.Path | Sequence[str | pathlib.Path] | None
default:"None"
Path(s) to skills directory to use instead of default skills directories
Example
from fast_agent import FastAgent
# Basic initialization
fast = FastAgent("my-app")
# With configuration file
fast = FastAgent(
"my-app",
config_path="config.yaml",
quiet=True
)
# Custom environment and skills directories
fast = FastAgent(
"my-app",
environment_dir="./my-env",
skills_directory=["./skills", "./custom-skills"]
)
Properties
context
@property
def context(self) -> Context
fast = FastAgent("my-app")
config = fast.context.config
servers = fast.context.server_registry
Methods
run()
async def run(self) -> AsyncIterator[AgentApp]
This is an async context manager. Use it with async with to ensure proper initialization and cleanup.
fast = FastAgent("my-app")
@fast.agent(name="assistant")
async def assistant():
pass
async with fast.run() as app:
response = await app.assistant.send("Hello!")
print(response.text)
load_agents()
def load_agents(self, path: str | Path) -> list[str]
Path to AgentCard file (.md, .yaml) or directory containing AgentCard files
fast = FastAgent("my-app")
# Load from directory
names = fast.load_agents("./agent-cards")
print(f"Loaded agents: {names}")
# Load single AgentCard file
fast.load_agents("./agents/specialist.md")
load_agents_from_url()
def load_agents_from_url(self, url: str) -> list[str]
URL to AgentCard file (must end in .md, .markdown, .yaml, or .yml)
fast = FastAgent("my-app")
# Load from GitHub
names = fast.load_agents_from_url(
"https://raw.githubusercontent.com/example/agents/main/specialist.md"
)
def attach_agent_tools(
self,
parent_name: str,
child_names: Sequence[str]
) -> list[str]
Names of child agents to attach as tools
fast = FastAgent("my-app")
# Load some agents
fast.load_agents("./agents")
# Attach specialists to coordinator
added = fast.attach_agent_tools(
parent_name="coordinator",
child_names=["code_expert", "docs_expert"]
)
print(f"Attached: {added}")
def detach_agent_tools(
self,
parent_name: str,
child_names: Sequence[str]
) -> list[str]
Names of child agents to detach
removed = fast.detach_agent_tools(
parent_name="coordinator",
child_names=["code_expert"]
)
reload_agents()
async def reload_agents(self) -> bool
True if any changes were detected and applied, False otherwise
fast = FastAgent("my-app")
fast.load_agents("./agents")
# Later, reload to pick up changes
changed = await fast.reload_agents()
if changed:
print("Agents reloaded successfully")
get_default_agent_name()
def get_default_agent_name(self) -> str | None
config.default=True, excluding tool_only agents. Falls back to the first non-tool_only agent if no explicit default is set.
Returns: The name of the default agent, or None if no agents are registered
fast = FastAgent("my-app")
@fast.agent(name="main", default=True)
async def main():
pass
default = fast.get_default_agent_name()
print(f"Default agent: {default}") # "main"
dump_agent_card_text()
def dump_agent_card_text(
self,
name: str,
*,
as_yaml: bool = False
) -> str
Name of the agent to export
If True, export as YAML; otherwise export as Markdown
fast = FastAgent("my-app")
# Export as Markdown
markdown = fast.dump_agent_card_text("assistant")
print(markdown)
# Export as YAML
yaml_content = fast.dump_agent_card_text("assistant", as_yaml=True)
Command Line Arguments
When parse_cli_args=True (default), FastAgent supports the following command line arguments:
Override the default model for all agents
Agent name for —message/—prompt-file (defaults to the app default agent)
Message to send to the specified agent
Path to a prompt file to use (either text or JSON)
Disable progress display, tool and message logging for cleaner output
Transport protocol to use when running as a server (sse, http, stdio, or acp)
Port to use when running as a server with SSE transport
Host address to bind to when running as a server with SSE transport
Control MCP agent instancing behaviour (shared, connection, request)
Override the base fast-agent environment directory
Path to skills directory to use instead of default skills directories
Enable manual AgentCard reloads (/reload command)
Watch AgentCard paths and reload when files change
Path or URL to an AgentCard file to load as a tool (repeatable)
Example Usage
# Run with custom model
python app.py --model openai:gpt-4
# Send a message
python app.py --message "Hello, agent!"
# Run as HTTP server
python app.py --transport http --port 8080
# Enable auto-reload on AgentCard changes
python app.py --watch
# Load external AgentCard as tool
python app.py --card-tool https://example.com/agent.md
See Also
