feat/a2a

.github/workflows/checks.yml

@@ -152,3 +152,34 @@ jobs:
 
       - name: Run package install test
         run: bash scripts/test_package_install.sh
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: "Set up Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install the project
+        run: |
+          uv sync --locked --group dev
+
+      - name: Generate reference docs
+        run: uv run scripts/docs.py generate
+
+      - name: Fail on partial docs generation
+        run: test ! -f docs/docs/_generated/_generation_warnings.md
+
+      - name: Check generated docs are committed
+        run: git diff --exit-code -- docs/docs/_generated
+
+      - name: Build docs
+        run: uv run scripts/docs.py build

docs/docs/_generated/model_aliases_google.md

@@ -1,10 +1,12 @@
 | Model Alias | Maps to | Model Alias | Maps to |
 | --- | --- | --- | --- |
-| `gemini` | `gemini-3.1-pro-preview` | `gemini2` | `gemini-2.0-flash` |
-| `gemini-2.0-flash` | `gemini-2.0-flash` | `gemini25` | `gemini-2.5-flash` |
-| `gemini-2.5-flash` | `gemini-2.5-flash` | `gemini25pro` | `gemini-2.5-pro` |
-| `gemini-2.5-pro` | `gemini-2.5-pro` | `gemini3` | `gemini-3-pro-preview` |
-| `gemini-3-flash-preview` | `gemini-3-flash-preview` | `gemini3.1` | `gemini-3.1-pro-preview` |
-| `gemini-3-pro-preview` | `gemini-3-pro-preview` | `gemini3.1flashlite` | `gemini-3.1-flash-lite-preview` |
+| `gemini` | `gemini-3.1-pro-preview` | `gemini25` | `gemini-2.5-flash` |
+| `gemini-2.0-flash` | `gemini-2.0-flash` | `gemini25pro` | `gemini-2.5-pro` |
+| `gemini-2.5-flash` | `gemini-2.5-flash` | `gemini3` | `gemini-3-pro-preview` |
+| `gemini-2.5-pro` | `gemini-2.5-pro` | `gemini3.1` | `gemini-3.1-pro-preview` |
+| `gemini-3-flash-preview` | `gemini-3-flash-preview` | `gemini3.1flashlite` | `gemini-3.1-flash-lite-preview` |
+| `gemini-3-pro-preview` | `gemini-3-pro-preview` | `gemini3.5flash` | `gemini-3.5-flash` |
 | `gemini-3.1-flash-lite-preview` | `gemini-3.1-flash-lite-preview` | `gemini31pro` | `gemini-3.1-pro-preview` |
-| `gemini-3.1-pro-preview` | `gemini-3.1-pro-preview` | `gemini3flash` | `gemini-3-flash-preview` |
+| `gemini-3.1-pro-preview` | `gemini-3.1-pro-preview` | `gemini35` | `gemini-3.5-flash` |
+| `gemini-3.5-flash` | `gemini-3.5-flash` | `gemini35flash` | `gemini-3.5-flash` |
+| `gemini2` | `gemini-2.0-flash` | `gemini3flash` | `gemini-3-flash-preview` |

docs/docs/_generated/model_aliases_hf.md

@@ -1,7 +1,7 @@
 | Model Alias | Maps to |
 | --- | --- |
-| `deepseek-hf` | `hf.deepseek-ai/DeepSeek-V4-Pro:together` |
 | `deepseek-ai/deepseek-v4-pro` | `deepseek-ai/deepseek-v4-pro` |
+| `deepseek-hf` | `hf.deepseek-ai/DeepSeek-V4-Pro:together` |
 | `deepseek32` | `hf.deepseek-ai/DeepSeek-V3.2:fireworks-ai` |
 | `deepseek4-hf` | `hf.deepseek-ai/DeepSeek-V4-Pro:together` |
 | `deepseek4pro-hf` | `hf.deepseek-ai/DeepSeek-V4-Pro:together` |

docs/docs/_generated/models_reference.md

@@ -27,29 +27,30 @@
 | `opus46` | `anthropic` | Text, Vision, Document | `json` (schema) | effort: `auto`, `low`, `medium`, `high`, `max`, `off`<br>Example: `opus46.auto` | — | `web_search` (web_search_20260209)<br>`web_fetch` (web_fetch_20260209)<br>beta: `code-execution-web-tools-2026-02-09` |
 | `opus` | `anthropic` | Text, Vision, Document | `json` (schema) | effort: `auto`, `low`, `medium`, `high`, `xhigh`, `max`, `off`<br>Example: `opus.auto` | — | `web_search` (web_search_20260209)<br>`web_fetch` (web_fetch_20260209)<br>beta: `code-execution-web-tools-2026-02-09` |
 | `codexspark` | `codexresponses` | Text | `json` (schema) | — | — | — |
-| `deepseek` | `deepseek` | Text | `json` (schema) | effort: `high`, `max`, `off`<br>Example: `deepseek.high` | — | — |
 | `deepseek-reasoner` | `deepseek` | Text | `json` (schema) | effort: `high`, `max`, `off`<br>Example: `deepseek-reasoner.high` | — | — |
 | `deepseek.deepseek-ai/deepseek-v3.1` | `deepseek` | Text | `json` (schema) | — | — | — |
 | `deepseek3` | `deepseek` | Text | `json` (schema) | — | — | — |
 | `deepseek4flash` | `deepseek` | Text | `json` (schema) | effort: `high`, `max`, `off`<br>Example: `deepseek4flash.high` | — | — |
+| `deepseek` | `deepseek` | Text | `json` (schema) | effort: `high`, `max`, `off`<br>Example: `deepseek.high` | — | — |
 | `passthrough` | `fast-agent` | Text | `json` (schema) | — | — | — |
 | `playback` | `fast-agent` | Text | `json` (schema) | — | — | — |
 | `silent` | `fast-agent` | Text | `json` (schema) | — | — | — |
 | `slow` | `fast-agent` | Text | `json` (schema) | — | — | — |
 | `gemini25` | `google` | Text, Vision, Document, Audio, Video | `json` (schema) | effort: `auto`, `minimal`, `low`, `medium`, `high`, `off`<br>Example: `gemini25.auto` | — | — |
 | `gemini25pro` | `google` | Text, Vision, Document, Audio, Video | `json` (schema) | effort: `auto`, `minimal`, `low`, `medium`, `high`, `off`<br>Example: `gemini25pro.auto` | — | — |
 | `gemini2` | `google` | Text, Vision, Document, Audio, Video | `json` (schema) | — | — | — |
-| `gemini3.1flashlite` | `google` | Text, Vision, Document, Audio, Video | `json` (schema) | effort: `auto`, `minimal`, `low`, `medium`, `high`, `off`<br>Example: `gemini3.1flashlite.auto` | — | — |
-| `gemini3` | `google` | Text, Vision, Document, Audio, Video | `json` (schema) | effort: `auto`, `minimal`, `low`, `medium`, `high`, `off`<br>Example: `gemini3.auto` | — | — |
-| `gemini3flash` | `google` | Text, Vision, Document, Audio, Video | `json` (schema) | effort: `auto`, `minimal`, `low`, `medium`, `high`, `off`<br>Example: `gemini3flash.auto` | — | — |
-| `gemini` | `google` | Text, Vision, Document, Audio, Video | `json` (schema) | effort: `auto`, `minimal`, `low`, `medium`, `high`, `off`<br>Example: `gemini.auto` | — | — |
+| `gemini3.1flashlite` | `google` | Text, Vision, Document, Audio, Video | `json` (schema) | effort: `minimal`, `low`, `medium`, `high`<br>Example: `gemini3.1flashlite.medium` | — | — |
+| `gemini35` | `google` | Text, Vision, Document, Audio, Video | `json` (schema) | effort: `minimal`, `low`, `medium`, `high`<br>Example: `gemini35.medium` | — | — |
+| `gemini3` | `google` | Text, Vision, Document, Audio, Video | `json` (schema) | effort: `minimal`, `low`, `medium`, `high`<br>Example: `gemini3.medium` | — | — |
+| `gemini3flash` | `google` | Text, Vision, Document, Audio, Video | `json` (schema) | effort: `minimal`, `low`, `medium`, `high`<br>Example: `gemini3flash.medium` | — | — |
+| `gemini` | `google` | Text, Vision, Document, Audio, Video | `json` (schema) | effort: `minimal`, `low`, `medium`, `high`<br>Example: `gemini.medium` | — | — |
 | `groq.deepseek-r1-distill-llama-70b` | `groq` | Text | `json` (object) | — | — | — |
 | `groq.qwen/qwen3-32b` | `groq` | Text | `json` (object) | — | — | — |
 | `moonshotai/kimi-k2-instruct-0905` | `groq` | Text | `json` (schema) | — | — | — |
 | `moonshotai/kimi-k2-thinking` | `groq` | Text | `json` (schema) | — | — | — |
 | `moonshotai/kimi-k2` | `groq` | Text | `json` (schema) | — | — | — |
-| `deepseek32` | `hf` | Text | `json` (schema) | — | — | — |
 | `deepseek-hf` | `hf` | Text | `json` (schema) | — | — | — |
+| `deepseek32` | `hf` | Text | `json` (schema) | — | — | — |
 | `glm47` | `hf` | Text | `json` (schema) | toggle: `on`, `off`<br>Example: `glm47?reasoning=off` | — | — |
 | `glm5` | `hf` | Text | `json` (schema) | toggle: `on`, `off`<br>Example: `glm5?reasoning=off` | — | — |
 | `glm` | `hf` | Text | `json` (schema) | toggle: `on`, `off`<br>Example: `glm?reasoning=off` | — | — |
@@ -108,8 +109,8 @@
 | `grok-4-1-fast-reasoning` | `xai` | Text, Vision | `json` (schema) | — | — | — |
 | `grok-4-fast-reasoning` | `xai` | Text, Vision | `json` (schema) | — | — | — |
 | `grok-4-fast` | `xai` | Text, Vision | `json` (schema) | — | — | — |
-| `grok-4-latest` | `xai` | Text | `json` (schema) | effort: `none`, `low`, `medium`, `high`, `off`<br>Example: `grok-4-latest.low` | — | — |
-| `grok-4.3-latest` | `xai` | Text | `json` (schema) | effort: `none`, `low`, `medium`, `high`, `off`<br>Example: `grok-4.3-latest.low` | — | — |
-| `grok-4` | `xai` | Text | `json` (schema) | effort: `none`, `low`, `medium`, `high`, `off`<br>Example: `grok-4.low` | — | — |
-| `grok` | `xai` | Text | `json` (schema) | effort: `none`, `low`, `medium`, `high`, `off`<br>Example: `grok.low` | — | — |
-| `grok` | `xai` | Text | `json` (schema) | effort: `none`, `low`, `medium`, `high`, `off`<br>Example: `grok.low` | — | — |
+| `grok-4-latest` | `xai` | Text, Vision | `json` (schema) | effort: `none`, `low`, `medium`, `high`, `off`<br>Example: `grok-4-latest.low` | — | — |
+| `grok-4.3-latest` | `xai` | Text, Vision | `json` (schema) | effort: `none`, `low`, `medium`, `high`, `off`<br>Example: `grok-4.3-latest.low` | — | — |
+| `grok-4` | `xai` | Text, Vision | `json` (schema) | effort: `none`, `low`, `medium`, `high`, `off`<br>Example: `grok-4.low` | — | — |
+| `grok` | `xai` | Text, Vision | `json` (schema) | effort: `none`, `low`, `medium`, `high`, `off`<br>Example: `grok.low` | — | — |
+| `grok` | `xai` | Text, Vision | `json` (schema) | effort: `none`, `low`, `medium`, `high`, `off`<br>Example: `grok.low` | — | — |

docs/docs/_generated/request_params_reference.md

@@ -9,28 +9,28 @@
 | --- | --- | --- | --- |
 | `task` | `mcp.types.TaskMetadata | None` | `None` |  |
 | `meta` | `mcp.types.RequestParams.Meta | None` | `None` |  |
-| `messages` | `list` | `[]` |  |
+| `messages` | `list[mcp.types.SamplingMessage]` | `[]` |  |
 | `modelPreferences` | `mcp.types.ModelPreferences | None` | `None` |  |
 | `systemPrompt` | `str | None` | `None` |  |
-| `includeContext` | `Optional` | `None` |  |
+| `includeContext` | `Literal['none', 'thisServer', 'allServers'] | None` | `None` |  |
 | `temperature` | `float | None` | `None` |  |
 | `maxTokens` | `int` | `2048` |  |
 | `stopSequences` | `list[str] | None` | `None` |  |
-| `metadata` | `dict[str, typing.Any] | None` | `None` |  |
+| `metadata` | `dict[str, Any] | None` | `None` |  |
 | `tools` | `list[mcp.types.Tool] | None` | `None` |  |
 | `toolChoice` | `mcp.types.ToolChoice | None` | `None` |  |
 | `model` | `str | None` | `None` |  |
 | `use_history` | `bool` | `True` |  |
-| `max_iterations` | `int` | `99` |  |
+| `max_iterations` | `int` | `199` |  |
 | `parallel_tool_calls` | `bool` | `True` |  |
-| `response_format` | `typing.Any | None` | `None` |  |
-| `structured_schema` | `dict[str, typing.Any] | None` | `None` |  |
-| `structured_tool_policy` | `Literal` | `'auto'` |  |
-| `template_vars` | `dict` | `PydanticUndefined` |  |
-| `mcp_metadata` | `dict[str, typing.Any] | None` | `None` |  |
-| `tool_execution_handler` | `typing.Any | None` | `None` |  |
+| `response_format` | `Any | None` | `None` |  |
+| `structured_schema` | `dict[str, Any] | None` | `None` |  |
+| `structured_tool_policy` | `Literal['auto', 'always', 'defer', 'no_tools']` | `'auto'` |  |
+| `template_vars` | `dict[str, Any]` | `PydanticUndefined` |  |
+| `mcp_metadata` | `dict[str, Any] | None` | `None` |  |
+| `tool_execution_handler` | `Any | None` | `None` |  |
 | `emit_loop_progress` | `bool` | `False` |  |
-| `tool_result_mode` | `Literal` | `'postprocess'` |  |
+| `tool_result_mode` | `Literal['postprocess', 'passthrough', 'selectable']` | `'postprocess'` |  |
 | `batch_context` | `fast_agent.llm.request_params.BatchRequestContext | None` | `None` |  |
 | `streaming_timeout` | `float | None` | `300.0` |  |
 | `top_p` | `float | None` | `None` |  |
@@ -39,4 +39,4 @@
 | `presence_penalty` | `float | None` | `None` |  |
 | `frequency_penalty` | `float | None` | `None` |  |
 | `repetition_penalty` | `float | None` | `None` |  |
-| `service_tier` | `Optional` | `None` |  |
+| `service_tier` | `Literal['fast', 'flex'] | None` | `None` |  |