evalstate · evalstate · Dec 14, 2025 · Dec 12, 2025 · Dec 14, 2025
diff --git a/.gitignore b/.gitignore
@@ -1 +1,2 @@
 .cache/
+site/
diff --git a/docs/_generated/README.md b/docs/_generated/README.md
@@ -0,0 +1,4 @@
+This directory contains generated Markdown includes used by the docs.
+
+Do not edit files here directly — run `python generate_reference_docs.py` from the repo root to regenerate.
+
diff --git a/docs/_generated/_generation_warnings.md b/docs/_generated/_generation_warnings.md
@@ -0,0 +1 @@
+Generated alias tables successfully, but skipped import-based references: `ModuleNotFoundError: No module named 'mcp'`
diff --git a/docs/_generated/model_aliases_anthropic.md b/docs/_generated/model_aliases_anthropic.md
@@ -0,0 +1,9 @@
+| Model Alias | Maps to | Model Alias | Maps to |
+| --- | --- | --- | --- |
+| `claude` | `claude-sonnet-4-5` | `opus4` | `claude-opus-4-1` |
+| `haiku` | `claude-haiku-4-5` | `opus45` | `claude-opus-4-5` |
+| `haiku3` | `claude-3-haiku-20240307` | `sonnet` | `claude-sonnet-4-5` |
+| `haiku35` | `claude-3-5-haiku-latest` | `sonnet35` | `claude-3-5-sonnet-latest` |
+| `haiku45` | `claude-haiku-4-5` | `sonnet37` | `claude-3-7-sonnet-latest` |
+| `opus` | `claude-opus-4-5` | `sonnet4` | `claude-sonnet-4-0` |
+| `opus3` | `claude-3-opus-latest` | `sonnet45` | `claude-sonnet-4-5` |
diff --git a/docs/_generated/model_aliases_deepseek.md b/docs/_generated/model_aliases_deepseek.md
@@ -0,0 +1,5 @@
+| Model Alias | Maps to |
+| --- | --- |
+| `deepseek` | `deepseek-chat` |
+| `deepseek3` | `deepseek-chat` |
+| `deepseekv3` | `deepseek-chat` |
diff --git a/docs/_generated/model_aliases_google.md b/docs/_generated/model_aliases_google.md
@@ -0,0 +1,6 @@
+| Model Alias | Maps to |
+| --- | --- |
+| `gemini2` | `gemini-2.0-flash` |
+| `gemini25` | `gemini-2.5-flash-preview-09-2025` |
+| `gemini25pro` | `gemini-2.5-pro` |
+| `gemini3` | `gemini-3-pro-preview` |
diff --git a/docs/_generated/model_aliases_groq.md b/docs/_generated/model_aliases_groq.md
@@ -0,0 +1,3 @@
+| Model Alias | Maps to |
+| --- | --- |
+| `kimigroq` | `groq.moonshotai/kimi-k2-instruct-0905` |
diff --git a/docs/_generated/model_aliases_openai.md b/docs/_generated/model_aliases_openai.md
@@ -0,0 +1,11 @@
+| Model Alias | Maps to | Model Alias | Maps to |
+| --- | --- | --- | --- |
+| `gpt-4.1` | `gpt-4.1` | `gpt-5.1-mini` | `gpt-5.1-mini` |
+| `gpt-4.1-mini` | `gpt-4.1-mini` | `gpt-5.1-nano` | `gpt-5.1-nano` |
+| `gpt-4.1-nano` | `gpt-4.1-nano` | `gpt51` | `openai.gpt-5.1` |
+| `gpt-4o` | `gpt-4o` | `o1` | `o1` |
+| `gpt-4o-mini` | `gpt-4o-mini` | `o1-mini` | `o1-mini` |
+| `gpt-5` | `gpt-5` | `o1-preview` | `o1-preview` |
+| `gpt-5-mini` | `gpt-5-mini` | `o3` | `o3` |
+| `gpt-5-nano` | `gpt-5-nano` | `o3-mini` | `o3-mini` |
+| `gpt-5.1` | `gpt-5.1` | `o4-mini` | `o4-mini` |
diff --git a/docs/_generated/model_aliases_xai.md b/docs/_generated/model_aliases_xai.md
@@ -0,0 +1,10 @@
+| Model Alias | Maps to |
+| --- | --- |
+| `grok-3` | `grok-3` |
+| `grok-3-fast` | `grok-3-fast` |
+| `grok-3-mini` | `grok-3-mini` |
+| `grok-3-mini-fast` | `grok-3-mini-fast` |
+| `grok-4` | `grok-4` |
+| `grok-4-0709` | `grok-4-0709` |
+| `grok-4-fast` | `xai.grok-4-fast-non-reasoning` |
+| `grok-4-fast-reasoning` | `xai.grok-4-fast-reasoning` |
diff --git a/docs/agents/defining.md b/docs/agents/defining.md
@@ -1,4 +1,4 @@
-# Defining Agents and Workflows
+# Defining Agents
 
 ## Basic Agents
 
@@ -60,85 +60,9 @@ from pathlib import Path
 
 ```
 
-## Workflows and MCP Servers
+See [Workflows](workflows.md) for chaining, routing, parallelism, orchestrators, and MAKER.
 
-_To generate examples use `fast-agent quickstart workflow`. This example can be run with `uv run workflow/chaining.py`. fast-agent looks for configuration files in the current directory before checking parent directories recursively._
-
-Agents can be chained to build a workflow, using MCP Servers defined in the `fastagent.config.yaml` file:
-
-```yaml title="fastagent.config.yaml"
-# Example of a STDIO sever named "fetch"
-mcp:
-  servers:
-    fetch:
-      command: "uvx"
-      args: ["mcp-server-fetch"]
-```
-
-
-```python title="social.py"
-@fast.agent(
-    "url_fetcher",
-    "Given a URL, provide a complete and comprehensive summary",
-    servers=["fetch"], # Name of an MCP Server defined in fastagent.config.yaml
-)
-@fast.agent(
-    "social_media",
-    """
-    Write a 280 character social media post for any given text.
-    Respond only with the post, never use hashtags.
-    """,
-)
-@fast.chain(
-    name="post_writer",
-    sequence=["url_fetcher", "social_media"],
-)
-async def main():
-    async with fast.run() as agent:
-        # using chain workflow
-        await agent.post_writer("http://fast-agent.ai")
-```
-
-All Agents and Workflows respond to `.send("message")`. The agent app responds to `.interactive()` to start a chat session.
-
-Saved as `social.py` we can now run this workflow from the command line with:
-
-```bash
-uv run workflow/chaining.py --agent post_writer --message "<url>"
-```
-
-Add the `--quiet` switch to disable progress and message display and return only the final response - useful for simple automations. 
-
-Read more about running **fast-agent** agents [here](running.md)
-
-## Workflow Types
-
-**fast-agent** has built-in support for the patterns referenced in  Anthropic's [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents) paper.
-
-### Chain
-
-The `chain` workflow offers a declarative approach to calling Agents in sequence:
-
-```python
-
-@fast.chain(
-  "post_writer",
-  sequence=["url_fetcher","social_media"]
-)
-
-# we can them prompt it directly:
-async with fast.run() as agent:
-  await agent.interactive(agent="post_writer")
-
-```
-
-This starts an interactive session, which produces a short social media post for a given URL. If a _chain_ is prompted it returns to a chat with last Agent in the chain. You can switch agents by typing `@agent-name`.
-
-Chains can be incorporated in other workflows, or contain other workflow elements (including other Chains). You can set an `instruction` to describe it's capabilities to other workflow steps if needed.
-
-Chains are also helpful for capturing content before being dispatched by a `router`, or summarizing content before being used in the downstream workflow.
-
-### Human Input
+## Human Input
 
 Agents can request Human Input to assist with a task or get additional context:
 
@@ -151,84 +75,7 @@ Agents can request Human Input to assist with a task or get additional context:
 await agent("print the next number in the sequence")
 ```
 
-In the example `human_input.py`, the Agent will prompt the User for additional information to complete the task.
-
-### Parallel
-
-The Parallel Workflow sends the same message to multiple Agents simultaneously (`fan-out`), then uses the `fan-in` Agent to process the combined content.
-
-```python
-@fast.agent("translate_fr", "Translate the text to French")
-@fast.agent("translate_de", "Translate the text to German")
-@fast.agent("translate_es", "Translate the text to Spanish")
-
-@fast.parallel(
-  name="translate",
-  fan_out=["translate_fr","translate_de","translate_es"]
-)
-
-@fast.chain(
-  "post_writer",
-  sequence=["url_fetcher","social_media","translate"]
-)
-```
-
-If you don't specify a `fan-in` agent, the `parallel` returns the combined Agent results verbatim.
-
-`parallel` is also useful to ensemble ideas from different LLMs.
-
-When using `parallel` in other workflows, specify an `instruction` to describe its operation.
-
-### Evaluator-Optimizer
-
-Evaluator-Optimizers combine 2 agents: one to generate content (the `generator`), and the other to judge that content and provide actionable feedback (the `evaluator`). Messages are sent to the generator first, then the pair run in a loop until either the evaluator is satisfied with the quality, or the maximum number of refinements is reached. The final result from the Generator is returned.
-
-If the Generator has `use_history` off, the previous iteration is returned when asking for improvements - otherwise conversational context is used.
-
-```python
-@fast.evaluator_optimizer(
-  name="researcher",
-  generator="web_searcher",
-  evaluator="quality_assurance",
-  min_rating="EXCELLENT",
-  max_refinements=3
-)
-
-async with fast.run() as agent:
-  await agent.researcher.send("produce a report on how to make the perfect espresso")
-```
-
-When used in a workflow, it returns the last `generator` message as the result.
-
-See the `evaluator.py` workflow example, or `fast-agent quickstart researcher` for a more complete example.
-
-### Router
-
-Routers use an LLM to assess a message, and route it to the most appropriate Agent. The routing prompt is automatically generated based on the Agent instructions and available Servers.
-
-```python
-@fast.router(
-  name="route",
-  agents=["agent1","agent2","agent3"]
-)
-```
-
-NB - If only one agent is supplied to the router, it forwards directly.
-
-Look at the `router.py` workflow for an example.
-
-### Orchestrator
-
-Given a complex task, the Orchestrator uses an LLM to generate a plan to divide the task amongst the available Agents. The planning and aggregation prompts are generated by the Orchestrator, which benefits from using more capable models. Plans can either be built once at the beginning (`plantype="full"`) or iteratively (`plantype="iterative"`).
-
-```python
-@fast.orchestrator(
-  name="orchestrate",
-  agents=["task1","task2","task3"]
-)
-```
-
-See the `orchestrator.py` or `agent_build.py` workflow example.
+In the example `human_input.py`, the agent will prompt the user for additional information to complete the task.
 
 ## Agent and Workflow Reference
 
@@ -257,7 +104,7 @@ You can customize how an agent interacts with the LLM by passing `request_params
 ### Example
 
 ```python
-from fast_agent.core.request_params import RequestParams
+from fast_agent.types import RequestParams
 
 @fast.agent(
   name="CustomAgent",                              # name of the agent
@@ -306,85 +153,16 @@ from fast_agent.core.request_params import RequestParams
 )
 ```
 
-#### Chain
-
-```python
-@fast.chain(
-  name="chain",                          # name of the chain
-  sequence=["agent1", "agent2", ...],    # list of agents in execution order
-  instruction="instruction",             # instruction to describe the chain for other workflows
-  cumulative=False,                      # whether to accumulate messages through the chain
-  continue_with_final=True,              # open chat with agent at end of chain after prompting
-)
-```
-
-#### Parallel
-
-```python
-@fast.parallel(
-  name="parallel",                       # name of the parallel workflow
-  fan_out=["agent1", "agent2"],          # list of agents to run in parallel
-  fan_in="aggregator",                   # name of agent that combines results (optional)
-  instruction="instruction",             # instruction to describe the parallel for other workflows
-  include_request=True,                  # include original request in fan-in message
-)
-```
-
-#### Evaluator-Optimizer
-
-```python
-@fast.evaluator_optimizer(
-  name="researcher",                     # name of the workflow
-  generator="web_searcher",              # name of the content generator agent
-  evaluator="quality_assurance",         # name of the evaluator agent
-  min_rating="GOOD",                     # minimum acceptable quality (EXCELLENT, GOOD, FAIR, POOR)
-  max_refinements=3,                     # maximum number of refinement iterations
-)
-```
-
-#### Router
-
-```python
-@fast.router(
-  name="route",                          # name of the router
-  agents=["agent1", "agent2", "agent3"], # list of agent names router can delegate to
-  instruction="routing instruction",     # any extra routing instructions
-  servers=["filesystem"],                # list of servers for the routing agent
-  #tools={"filesystem": ["tool_1", "tool_2"]  # Filter the tools available to the agent. Defaults to all
-  #resources={"filesystem: ["resource_1", "resource_2"]} # Filter the resources available to the agent. Defaults to all
-  #prompts={"filesystem": ["prompt_1", "prompt_2"]}  # Filter the prompts available to the agent. Defaults to all
-  model="o3-mini.high",                  # specify routing model
-  use_history=False,                     # router maintains conversation history
-  human_input=False,                     # whether router can request human input
-  api_key="programmatic-api-key",        # specify the API KEY programmatically, it will override which provided in config file or env var
-)
-```
-
-#### Orchestrator
-
-```python
-@fast.orchestrator(
-  name="orchestrator",                   # name of the orchestrator
-  instruction="instruction",             # base instruction for the orchestrator
-  agents=["agent1", "agent2"],           # list of agent names this orchestrator can use
-  model="o3-mini.high",                  # specify orchestrator planning model
-  use_history=False,                     # orchestrator doesn't maintain chat history (no effect).
-  human_input=False,                     # whether orchestrator can request human input
-  plan_type="full",                      # planning approach: "full" or "iterative"
-  max_iterations=5,                      # maximum number of full plan attempts, or iterations
-  api_key="programmatic-api-key",        # specify the API KEY programmatically, it will override which provided in config file or env var
-)
-```
+Workflow definitions (chain/parallel/router/orchestrator/maker) are documented on the [Workflows](workflows.md) page.
 
 #### Custom
 
 ```python
 @fast.custom(
-  cls=Custom                             # agent class
+  cls=Custom,                            # agent class
   name="custom",                         # name of the custom agent
   instruction="instruction",             # base instruction for the orchestrator
   servers=["filesystem"],                # list of MCP Servers for the agent
-  MCP Servers for the agent
   #tools={"filesystem": ["tool_1", "tool_2"]  # Filter the tools available to the agent. Defaults to all
   #resources={"filesystem: ["resource_1", "resource_2"]} # Filter the resources available to the agent. Defaults to all
   #prompts={"filesystem": ["prompt_1", "prompt_2"]}  # Filter the prompts available to the agent. Defaults to all
@@ -396,4 +174,3 @@ from fast_agent.core.request_params import RequestParams
   api_key="programmatic-api-key",        # specify the API KEY programmatically, it will override which provided in config file or env var
 )
 ```
-
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,4 @@
		This directory contains generated Markdown includes used by the docs.

		Do not edit files here directly — run `python generate_reference_docs.py` from the repo root to regenerate.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Generated alias tables successfully, but skipped import-based references: `ModuleNotFoundError: No module named 'mcp'`