From 04e1bcb80b4264a1ef262ffc89b011ea70a82462 Mon Sep 17 00:00:00 2001 From: Aqil Aziz Date: Sat, 23 May 2026 07:49:40 +0700 Subject: [PATCH] docs(model-routing): document per-agent model pins (#2431) --- .../developing/architecture/agent-harness.md | 2 +- gitbooks/features/model-routing/README.md | 36 +++++++++++++++++++ .../native-tools/agent-coordination.md | 2 ++ 3 files changed, 39 insertions(+), 1 deletion(-) diff --git a/gitbooks/developing/architecture/agent-harness.md b/gitbooks/developing/architecture/agent-harness.md index 1ef70c85e..f37cab39b 100644 --- a/gitbooks/developing/architecture/agent-harness.md +++ b/gitbooks/developing/architecture/agent-harness.md @@ -159,7 +159,7 @@ Custom archetypes ship as TOML files under `$OPENHUMAN_WORKSPACE/agents/*.toml` When the orchestrator calls `spawn_subagent` (or one of the `delegate_*` convenience tools), the runner: 1. Reads the parent's execution context from a task-local - the parent's provider, sandbox mode, cancellation fence, transcript root. -2. Resolves the sub-agent's model - inherit from parent, follow a hint (`fast` / `reasoning` / `summarization`), or pin an exact model. +2. Resolves the sub-agent's model - inline `model` override first, then config-level pins (`[orchestrator].model`, `[teams.*].lead_model`, `[teams.*].agent_model`), then the archetype hint or inherited parent model. 3. Filters the parent's tool registry per the definition's `tools`, `disallowed_tools`, and `skill_filter`. In `fork` mode, the parent's full registry is inherited verbatim. 4. Builds a narrow system prompt, omitting the sections the definition asks to strip. 5. Runs an inner tool-call loop using the same machinery as the parent. diff --git a/gitbooks/features/model-routing/README.md b/gitbooks/features/model-routing/README.md index 0c7e77691..01682cb0b 100644 --- a/gitbooks/features/model-routing/README.md +++ b/gitbooks/features/model-routing/README.md @@ -52,6 +52,42 @@ Routing happens behind a single OpenHuman subscription. You don't hold separate - **Per call**. pass a concrete model name (no `hint:` prefix) and the router falls through to the default provider with that exact model. - **For a skill**. skills can pin a hint or a model in their manifest. +## Per-agent model pins + +Sub-agents can also pin an exact model without disabling automatic routing for the rest of the app. Use this when an orchestrator or team lead needs a stronger model, while high-volume leaf agents should stay on a cheaper one. + +Inline calls win for one delegation: + +```json +{ + "agent_id": "researcher", + "model": "anthropic/claude-sonnet-4", + "prompt": "Collect source notes for the launch memo." +} +``` + +Persistent defaults live in `config.toml`: + +```toml +[orchestrator] +model = "anthropic/claude-sonnet-4" + +[teams.research] +lead_model = "openai/gpt-5.1" +agent_model = "groq/llama-3.1-8b-instant" + +[teams.code] +agent_model = "qwen/qwen3-coder" +``` + +Resolution order: + +1. Inline `model` on `spawn_subagent` or an archetype delegation call. +2. `[orchestrator].model` or `[teams.]` / built-in aliases such as `[teams.research]` and `[teams.code]`. +3. The archetype's own model hint and the normal route table. + +For `[teams.*]`, `lead_model` applies to agents that can delegate and `agent_model` applies to leaf workers. If only one is set, the harness falls back to it for both roles. + ## Why this isn't just "model switcher" Routing isn't a UI dropdown. The agent loop itself emits hints based on what it's about to do. You don't pick the model; the *task* does. That's the difference between "multi-model" and "smart routing". diff --git a/gitbooks/features/native-tools/agent-coordination.md b/gitbooks/features/native-tools/agent-coordination.md index fb0a1a683..419a7d663 100644 --- a/gitbooks/features/native-tools/agent-coordination.md +++ b/gitbooks/features/native-tools/agent-coordination.md @@ -21,6 +21,8 @@ Beyond doing the work, the agent has tools for *organising* the work - planning | `plan_exit` | Exit a planning phase and start executing. | | `check_onboarding_status` / `complete_onboarding` | Gate behaviour on whether the user has finished onboarding. | +`spawn_subagent` and archetype delegation calls accept an optional `model` field for a one-off exact model pin. If it is omitted, the harness uses config-level per-agent pins when present and otherwise falls back to the normal model-routing hints. + ## Why these are tools, not implicit behaviour Long tasks fall apart when the agent tries to keep everything in one head. Splitting work via TODOs and subagents means: