fastagent-explorations

Four organizational patterns for building MCP-powered AI agents with FastAgent, in increasing order of substance.

Script	Pattern	When to use
basic_agent.py	Minimal FastAgent, no tools, no instructions file	Smoke-testing the install
markdown_instructions_agent.py	Load the agent's system instruction from a sibling instructions.example.md file	When the instructions are long enough that you want them version-controlled separately from the code
json_instructions_agent.py	Load a structured tool-usage spec from JSON and format it into the system prompt at startup	When your MCP server already publishes a machine-readable usage spec and you want to keep the prompt and the spec in sync
logged_agent.py	Same as the markdown one, plus structured startup logging and an extra "display rules" block appended to the instructions	When you want a Cursor-style "what the agent is doing" trace alongside the conversation

All four connect to whatever MCP server you wire up in fastagent.config.yaml. Out of the box the agents try to load a server called my-mcp-server (HTTP at http://localhost:8000/mcp/) plus the standard filesystem server.

Setup

Uses uv.

uv sync
cp fastagent.secrets.example.yaml fastagent.secrets.yaml
# edit fastagent.secrets.yaml and put in your OpenAI / Anthropic key

Point my-mcp-server in fastagent.config.yaml at the MCP server you want to talk to.

Run

uv run python basic_agent.py
uv run python markdown_instructions_agent.py
uv run python json_instructions_agent.py
uv run python logged_agent.py

Each agent drops you into a chat. :exit quits.

Customizing the JSON-driven agent

json_instructions_agent.py reads example_usage_help.json and pours it into the system prompt. The schema it expects:

{
  "description": "...",
  "recommended_workflow": ["step 1", "step 2"],
  "important_instructions_to_agent": ["rule 1"],
  "common_mistakes": ["mistake 1"],
  "query_parameters": {
    "required": [{ "name": "...", "type": "...", "meaning": "...", "usage": "..." }],
    "optional": [{ "name": "...", "type": "...", "meaning": "...", "format": "..." }]
  }
}

The bundled example_usage_help.json describes a fictitious weather-data MCP server. Replace it with the spec your own MCP server publishes.

Why four scripts instead of one configurable one

Each script is small enough to read in one sitting. Collapsing them into a single --mode CLI would obscure the differences. The point of the project is to show the patterns side by side, not to be a polished CLI.