Core Concepts Guide

The mental model

A fast-agent environment is a small folder that travels with a project or a team workflow. It can contain agents, config, MCP servers, skills, sessions, plugins and card packs.

One agent is the default. Add another agent by dropping a Markdown file into agent-cards/. Share the whole setup by publishing it as a pack.

$ fast-agent go --pack codex --model sonnet
loaded dev, planner, reviewer

fast-agent> @planner
switched planner is now the active agent

planner> #reviewer check this plan for risky assumptions
loaded reviewer response into your input buffer

What is an environment?

An environment is the active fast-agent home. By default it is ./.fast-agent in your current project.

.fast-agent/
├── fast-agent.yaml          # providers, model defaults, MCP servers, registries
├── fast-agent.secrets.yaml  # optional local secrets, same shape as config
├── agent-cards/             # runnable agents loaded by default
├── tool-cards/              # agents attached as tools to another agent
├── card-packs/              # installed packs and provenance metadata
├── plugins/                 # command plugins and hook support files
├── skills/                  # Agent Skills available through {{agentSkills}}
├── sessions/                # persisted chat/session history
├── model-overlays/          # optional local model definitions
├── ui/                      # generated MCP UI assets
└── auths.md                 # environment-scoped permission/auth history

The defaults are deliberately useful:

• fast-agent go selects ./.fast-agent unless you choose another environment.
• The configuration file (fast-agent.yaml) is loaded from the active environment first, then the current directory if no environment config is present.
• AgentCards in <env>/agent-cards/ are loaded as runnable agents.
• ToolCards in <env>/tool-cards/ are loaded and attached as tools.
• Sessions are saved in <env>/sessions/ so you can resume work later.
• Skills are discovered from the active environment's skills/ directory (normally .fast-agent/skills), plus .agents/skills and .claude/skills.

If no AgentCards are present, fast-agent go still starts a simple default agent from the command-line options you provide.

The built-in default prompt is already practical: it includes AGENTS.md from the current project when that file exists, so project conventions are picked up without making an AgentCard first. If you want a more capable generated default, run:

fast-agent go --smart

--smart asks fast-agent to use a smart default agent. A smart agent has extra guidance for working with fast-agent concepts, including creating and delegating to sub-agents.

Make your first environment

Create a project environment with one default coding agent and two supporting agents:

mkdir -p .fast-agent/agent-cards

---
name: dev
type: smart
default: true
model: $system.default
shell: true
---

You help with software development. Be direct, make small changes, and explain
trade-offs clearly.

{{agentSkills}}
{{file_silent:AGENTS.md}}
{{env}}

---
name: planner
model: $system.default
---

You turn ambiguous software work into a short, testable plan. Prefer milestones,
risks, and explicit assumptions over long prose.

---
name: reviewer
model: $system.default
---

You review plans and code for correctness, maintainability, missing tests, and
unnecessary complexity. Be concise and specific.

Run it:

fast-agent go --model sonnet

Because each card uses model: $system.default, the selected model comes from --model, then the environment config, then normal provider defaults. If no default is found an interactive model picker is displayed.

Work with multiple agents in the TUI

Inside the interactive prompt, agents are lightweight to move between:

dev> @planner
switched planner

planner> sketch a migration plan for the auth module

planner> #reviewer find risks in this plan
response copied into your input buffer for editing

planner> ##reviewer check quietly and draft comments
quiet response loaded without streaming display

• @agent_name switches the active conversation.
• #agent_name message asks another agent and loads its response into your input buffer. There must be no space after #; # Heading remains normal Markdown text.
• ##agent_name message is the quiet form. It suppresses interactive display and still loads the response into your buffer.
• /agent, /card, /reload, /history, /session, /connect, and /skills are available while you work.

Add MCP servers to an agent

MCP Servers can be connected at any time with the /connect command. This supports both remote servers with a URL as well as npx, uvx or other STDIO servers.

MCP servers can also be configured once in fast-agent.yaml, then referenced by agents.

default_model: gpt-5.4-mini?reasoning=low

mcp:
  servers:
    fetch:
      command: uvx
      args: [mcp-server-fetch]
    filesystem:
      command: npx
      args:
        - -y
        - "@modelcontextprotocol/server-filesystem"
        - .

---
name: researcher
servers: [fetch, filesystem]
model: $system.default
---

You research technical topics and cite sources. Use the filesystem for local
notes and fetch for public pages.

You can also define servers directly on an AgentCard:

---
name: papers
mcp_connect:
  - target: https://papers.example.com/mcp
    name: papers
    headers:
      Authorization: Bearer ${PAPERS_TOKEN}
---

You find and summarize relevant papers.

Use configured servers for shared infrastructure. Use mcp_connect when the server is part of the agent definition itself.

Add small tools and sub-agents

When an AgentCard is attached as a tool, fast-agent uses the card's description as the tool description. This is the short hint the parent agent sees when deciding whether to call that sub-agent.

---
name: reviewer
description: Review a proposed plan or patch for risks, missed tests, and unnecessary complexity.
tool_only: true
model: $system.default
---

You are a concise software reviewer. Focus on correctness, maintainability and
test coverage.

For a plain Python function, add it to an agent with function_tools:

def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

---
name: calculator
function_tools:
  - tools.py:add
---

You can do small calculations.

Hooks and command plugins are the next step when you want to change lifecycle behaviour or add reusable commands. Use the fast-agent skill for guided setup, or see Command Plugins.

Model references and --model

A model string can be a provider model, a shorthand alias, a model overlay, or a model reference.

fast-agent go --model sonnet
fast-agent go --model 'openai.gpt-5?web_search=on'
fast-agent go --model 'xai.grok-4.3?x_search=on'

Model references are exact tokens like $system.fast. Define them in the environment config and reuse them in cards:

default_model: $system.fast

model_references:
  system:
    fast: gpt-5-mini?reasoning=low
    plan: claude-sonnet-4-5
    research: openai.gpt-5?web_search=on

---
name: planner
model: $system.plan
---

You create concise plans.

$system.default is a special reference for reusable cards. It means "use the current run's default model". That makes packs easy to share: the card author sets model: $system.default, and the user chooses the model with --model or default_model in their environment.

Explicit card models usually win over --model. Use $system.default when you want --model to remain in control.

Use fast-agent model setup to see and set configured references.

Multiple environments

Use more than one environment when you want different bundles for different workflows:

# Coding environment
fast-agent go --env .fast-agent-coding --pack codex 

# Research environment
fast-agent go --env .fast-agent-research --agent researcher \
  --model 'openai.gpt-5?web_search=on'

# Ephemeral run: no implicit env cards, sessions, pack installs or permission-store side effects
fast-agent go --no-env --model haiku --message "summarize this directory"

Selection order for the environment is:

1. --env <path>
2. FAST_AGENT_HOME
3. legacy ENVIRONMENT_DIR
4. ./.fast-agent

You can also set environment_dir in fast-agent.yaml, or override skills for one run:

fast-agent go --env ~/agent-envs/client-a --skills ~/agent-skills/client-a

--no-env is useful for clean tests, one-off MCP inspection, or automation that should not read project AgentCards or write session state. It cannot be combined with --pack, --env, or --resume.

Skills are environment tools for knowledge

Skills are folders containing a SKILL.md manifest plus optional scripts, references and assets. They let agents load specialized procedures only when needed. By default, fast-agent looks in:

• the active environment's skills/ directory — normally .fast-agent/skills
• .agents/skills
• .claude/skills

The easiest way to get started is to install skills from an existing registry from inside the TUI. fast-agent includes public registries for fast-agent, Hugging Face and Anthropic skills, and teams can add their own.

Common workflow:

/skills            # list available skills
/skills add        # browse and install from the active registry
/skills remove 1   # remove by number or name
/skills registry   # view or switch registries

/skills add presents the available skills as a numbered list, so installing one is usually just:

/skills add
/skills add 1

If an agent or sub-agent should not see the default skills, make that explicit in its AgentCard:

---
name: reviewer
skills: []
---

You can also point a card at specific skill folders instead of the defaults:

---
name: release-manager
skills:
  - .fast-agent/skills/release
  - ~/team-skills/compliance
---

Environment config can pin skill directories and registries:

skills:
  directories:
    - .fast-agent/skills
    - ~/team/agent-skills
  marketplace_urls:
    - https://github.com/fast-agent-ai/skills
    - https://github.com/my-org/private-skills

See Agent Skills for the full skill workflow.

Share it as a pack

A card pack is a publishable bundle of AgentCards, ToolCards and supporting files. Packs are how teams distribute a good environment without asking everyone to copy files by hand.

Install and run one immediately:

fast-agent go --pack codex --model sonnet

Manage packs explicitly:

fast-agent cards add codex
fast-agent cards update codex
fast-agent cards readme codex
fast-agent cards publish codex --message "Improve reviewer prompt"

Packs are installed into the selected environment under card-packs/, and their managed files are copied into places like agent-cards/, tool-cards/, plugins/, or the environment root.

A minimal pack looks like this:

packs/coding/
├── card-pack.yaml
├── README.md
└── agent-cards/
    ├── dev.md
    ├── planner.md
    └── reviewer.md

# packs/coding/card-pack.yaml
schema_version: 2
name: coding
kind: card
install:
  agent_cards:
    - agent-cards/dev.md
    - agent-cards/planner.md
    - agent-cards/reviewer.md
  files:
    - README.md
model_references_recommended:
  - $system.fast
plugins:
  recommended:
    - agent-finder

A registry is a marketplace file that points at packs:

{
  "entries": [
    {
      "name": "coding",
      "description": "A dev agent with planning and review helpers",
      "kind": "card",
      "repo": "https://github.com/my-org/agent-packs",
      "ref": "main",
      "path": "packs/coding"
    }
  ]
}

Use the default registry, a URL, or a local registry while developing:

fast-agent cards add coding
fast-agent cards --registry https://github.com/my-org/agent-packs add coding
fast-agent go --pack coding --pack-registry ./marketplace.json

GitHub repository URLs are accepted as registries when they contain a marketplace.json file. During development, a local JSON file or local GitHub checkout is often enough:

{
  "entries": [
    {
      "name": "coding-local",
      "description": "Local pack while iterating",
      "repo_url": ".",
      "repo_path": "packs/coding"
    }
  ]
}

fast-agent go --pack coding-local --pack-registry ./marketplace.json

Two common bundles

• AgentCards and ToolCards — advanced card fields, ToolCards, runtime MCP targets and loading rules.
• Configuration Reference — every fast-agent.yaml setting, including providers, MCP, sessions, skills and model references.
• fast-agent go — all CLI switches for environments, packs, models, cards, skills and non-interactive runs.
• MCP configuration — configure and inspect MCP servers.
• Model Features — model strings, provider web tools and overlays.
• fast-agent skills - Skills to work with Agent Cards, Hooks, Plugins, Automations and more.