feat(agents): allow create_agent to spawn a child on a different model

Add an optional model override to create_agent so the orchestrator can
deliberately spawn a "second opinion" specialist on a different LLM to
re-review surfaces the primary model already covered (e.g. needs_follow_up
coverage entries, or an under-covered target). The override threads
create_agent -> the spawner callback -> AgentCoordinator.register (persisted
for resume) -> build_strix_agent's SandboxAgent(model=...), falling back to
the run-wide model when omitted; ReportUsageHooks now records/estimates each
agent's cost against its own resolved model instead of always the run's
default. The model string is validated with a new shared
strix.config.models.invalid_model_reason() before spawning, returning a
clean {"success": False, "error": ...} on a bad string instead of a crash.

Also adds the scan_modes/second_opinion skill documenting when and how to
use this, and a short pointer to it in coordination/root_agent.md. No
automatic/heuristic triggering is added -- this is purely an explicit,
deliberately-invoked capability.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Owen 2026-09-12 16:57:44 +01:00
parent 95e085eb6c
commit bf5ae16516
9 changed files with 268 additions and 5 deletions

View file

@ -658,6 +658,7 @@ def build_strix_agent(
system_prompt_context: dict[str, Any] | None = None,
extra_tools: Sequence[Tool] | None = None,
instructions_override: str | None = None,
model: str | None = None,
) -> SandboxAgent[Any]:
"""Build a SandboxAgent for either root or child use.
@ -670,6 +671,12 @@ def build_strix_agent(
registered via ``register_agent_tools``.
instructions_override: Use this verbatim as the system prompt instead
of rendering the built-in scan prompt.
model: Per-agent model override. ``None`` (the default) leaves the
agent's own ``model`` unset, so it runs on the run-wide model
configured on ``RunConfig``. A non-``None`` value overrides that
for this agent only — every other agent in the scan is
unaffected. Used for deliberately spawning a "second opinion"
child on a different model; see ``strix.tools.agents_graph.tools.create_agent``.
"""
if instructions_override is not None:
instructions = instructions_override
@ -715,7 +722,7 @@ def build_strix_agent(
instructions=instructions,
tools=tools,
tool_use_behavior=_finish_tool_use_behavior,
model=None,
model=model,
capabilities=[
Filesystem(
configure_tools=_make_filesystem_configurator(
@ -750,7 +757,7 @@ def make_child_factory(
without the graph tool knowing about runner internals.
"""
def _factory(*, name: str, skills: list[str]) -> SandboxAgent[Any]:
def _factory(*, name: str, skills: list[str], model: str | None = None) -> SandboxAgent[Any]:
return build_strix_agent(
name=name,
skills=skills,
@ -762,6 +769,7 @@ def make_child_factory(
chat_completions_tools=chat_completions_tools,
strict_tool_schemas=strict_tool_schemas,
system_prompt_context=system_prompt_context,
model=model,
)
return _factory

View file

@ -887,6 +887,29 @@ def is_known_openai_bare_model(model_name: str) -> bool:
return bool(entry and entry.get("litellm_provider") == "openai")
def invalid_model_reason(model_name: str | None, *, api_base: str | None = None) -> str | None:
"""Return why ``model_name`` is not a usable model string, or ``None`` if it is fine.
Mirrors the CLI's hard-fail check in ``warm_up_llm`` (``strix.interface.main``):
empty is always invalid, and a bare name (no ``<provider>/`` prefix) must be a
known OpenAI model unless a custom ``LLM_API_BASE``/``api_base`` is configured,
since that could plausibly serve any bare name. This is a structural check only
— it says nothing about whether the model is a *good* choice (see
``is_recommended_or_frontier_model`` for that, which is a warning, not a
rejection).
"""
name = (model_name or "").strip()
if not name:
return "model name is empty"
if "/" not in name and not is_known_openai_bare_model(name) and not api_base:
return (
f"'{name}' is not a known OpenAI model. Bare names route to OpenAI by "
"default. If you meant a non-OpenAI provider, use the '<provider>/<model>' "
"form, e.g. 'anthropic/claude-opus-4-7', 'deepseek/deepseek-v4-pro'."
)
return None
_ANTHROPIC_MODEL_MARKERS = ("anthropic", "claude", "sonnet", "opus", "haiku")

View file

@ -160,6 +160,7 @@ class AgentCoordinator:
*,
task: str | None = None,
skills: list[str] | None = None,
model: str | None = None,
) -> None:
async with self._lock:
self.statuses[agent_id] = "running"
@ -169,6 +170,7 @@ class AgentCoordinator:
self.metadata[agent_id] = {
"task": task or "",
"skills": list(skills or []),
"model": model,
}
self.runtimes.setdefault(agent_id, AgentRuntime())
logger.info("agent.register %s (%s) parent=%s", agent_id, name, parent_id or "-")

View file

@ -315,6 +315,7 @@ async def spawn_child_agent(
task: str,
skills: list[str],
parent_history: list[Any],
model: str | None = None,
event_sink: StreamEventSink | None = None,
hooks: RunHooks[dict[str, Any]] | None = None,
) -> dict[str, Any]:
@ -323,13 +324,14 @@ async def spawn_child_agent(
raise TypeError("Parent agent_id missing from context")
child_id = uuid.uuid4().hex[:8]
child_agent = factory(name=name, skills=skills)
child_agent = factory(name=name, skills=skills, model=model)
await coordinator.register(
child_id,
name,
parent_id,
task=task,
skills=skills,
model=model,
)
await _start_child_runner(
@ -345,6 +347,7 @@ async def spawn_child_agent(
name=name,
parent_id=parent_id,
task=task,
model=model,
initial_input=child_initial_input(
name=name,
child_id=child_id,
@ -414,7 +417,8 @@ async def respawn_subagents(
)
child_skills = list(md.get("skills") or [])
child_agent = factory(name=name, skills=child_skills)
child_model = md.get("model") if isinstance(md.get("model"), str) else None
child_agent = factory(name=name, skills=child_skills, model=child_model)
await _start_child_runner(
parent_ctx=parent_ctx,
coordinator=coordinator,
@ -428,6 +432,7 @@ async def respawn_subagents(
name=name,
parent_id=parent_id,
task=str(md.get("task", "")),
model=child_model,
initial_input=[],
start_parked=start_parked,
event_sink=event_sink,
@ -1001,6 +1006,7 @@ async def _start_child_runner(
parent_id: str | None,
task: str,
initial_input: Any,
model: str | None = None,
start_parked: bool = False,
event_sink: StreamEventSink | None = None,
hooks: RunHooks[dict[str, Any]] | None = None,
@ -1013,6 +1019,11 @@ async def _start_child_runner(
child_ctx["agent_id"] = child_id
child_ctx["parent_id"] = parent_id
child_ctx["task"] = task
if model is not None:
# Lets ReportUsageHooks record/estimate this agent's cost against the
# model it actually runs on, not the run-wide default — see
# ``build_strix_agent``'s ``model`` override.
child_ctx["agent_model"] = model
async def _child_loop() -> None:
# A budget stop is a clean scan-wide shutdown, not a child failure: the

View file

@ -240,11 +240,14 @@ class ReportUsageHooks(RunHooks[dict[str, Any]]):
if not isinstance(agent_id, str) or not agent_id:
agent_id = agent_name or "unknown"
agent_model = ctx.get("agent_model")
model = agent_model if isinstance(agent_model, str) and agent_model else self._model
try:
report_state.record_sdk_usage(
agent_id=agent_id,
agent_name=agent_name,
model=self._model,
model=model,
usage=response.usage,
)
except Exception:

View file

@ -95,6 +95,10 @@ Complex findings warrant specialized subagents:
- Use message passing only when essential (requests/answers, critical handoffs)
- Prefer batched updates over routine status messages
**Second Opinions**
Every agent runs on the scan's configured model by default, but `create_agent` accepts an optional `model` override for the rare case where that isn't enough: deliberately re-reviewing already-covered surfaces (piling-up `needs_follow_up` entries, or a target under-covered relative to its size) with a differently-configured model, since different model families notice different things on the same input. This is not a general-purpose "pick a model for this agent" knob and nothing spawns it automatically — see the `scan_modes/second_opinion` skill before reaching for it.
## Completion
When all agents report completion:

View file

@ -0,0 +1,44 @@
---
name: second-opinion
description: Deliberately re-review already-covered surfaces with a differently-configured model
---
# Second Opinion
Every agent in a scan runs on the same model by default. That is the right default — it is predictable and it is what the operator configured — but different model families notice different things on the same input. A pass that already happened is not necessarily a pass that was thorough; a second, independent look from a different model can surface what the first one missed. This is a deliberate, operator-triggered capability, not something that fires on its own — nothing in Strix spawns a second-opinion agent automatically, and this skill does not ask you to either.
## When to use this
Reach for a second opinion when coverage on a scan that matters is thin or uncertain and there is still budget to spend on it:
- `list_coverage(outcome="needs_follow_up")` is non-empty and piling up faster than it is being resolved — entries sitting open across multiple agents rather than one agent's temporary backlog.
- A target is large or high-value relative to how much of it has actually been exercised — e.g. a handful of endpoints marked `covered` on an API surface with dozens of routes.
- The scan is close to wrapping up and you (the root agent) judge that a fresh pass over what has already been reviewed is worth more than starting a new area from scratch.
Do not reach for this to cover new ground — that is what an ordinary specialist agent is for. This is specifically for **re-examining surfaces someone already looked at**, with a model that might notice something the first pass didn't.
Do not reach for this reflexively on every scan — it is another full agent's worth of tokens and time on top of the primary pass, and it needs a real driver (thin coverage on something that matters, not curiosity).
## How to use this
1. Call `list_coverage(outcome="needs_follow_up")` (and, if useful, look at what is marked `covered` on the target you're worried about) to build a concrete list of surfaces to re-check. A second opinion is only as good as the list of what it's being asked to re-examine — don't hand it a vague "look at the app again."
2. Call `create_agent` with `model` set to a different model string than the one this scan is running on, and a `task` that says explicitly this is a re-review, not fresh recon:
```
create_agent(
name="Second Opinion: Auth Surface",
task=(
"Re-review these already-covered surfaces with fresh eyes: "
"<list the specific endpoints/flows/coverage entries from step 1>. "
"The first pass marked these as needs_follow_up / covered but "
"coverage here is thin relative to the surface's size. Look for "
"anything the first pass could have missed, not new areas."
),
model="anthropic/claude-opus-4-7",
skills=["auth"],
)
```
3. Treat its findings like any other subagent's: filed vulnerability reports and `update_coverage` calls on the entries it resolved. It reports back through the same `agent_finish` / completion-report flow as every other child.
`model` accepts the same `<provider>/<model>` strings as `STRIX_LLM` (e.g. `anthropic/claude-opus-4-7`, `openai/gpt-5.6`, `zai/glm-5.3`). Pick something meaningfully different from the scan's configured model — a second pass on the same model tends to repeat the same blind spots.

View file

@ -12,6 +12,8 @@ from typing import Any, Literal, get_args
from agents import RunContextWrapper, function_tool
from strix.config import load_settings
from strix.config.models import invalid_model_reason
from strix.core.agents import Status, coordinator_from_context
from strix.core.execution import notify_parent_on_terminal
from strix.core.hooks import LLM_TURN_KEY
@ -501,6 +503,7 @@ async def create_agent(
task: str,
inherit_context: bool = True,
skills: list[str] | None = None,
model: str | None = None,
) -> str:
"""Spawn a specialist child agent to run in parallel.
@ -546,6 +549,17 @@ async def create_agent(
when starting a clean-slate task.
skills: List of skill names (e.g. ``["xss", "sql_injection"]``).
Max 5; prefer 1-3.
model: Optional. Leave unset — every child runs on the scan's
configured model by default. Set this only to deliberately get a
**second opinion** from a differently-configured model on
surfaces the scan has already reviewed (e.g. entries sitting at
``needs_follow_up`` in ``list_coverage``, or a target you judge
under-covered relative to its size). This is not a general
"pick any model for this agent" knob — different model
families catch different things, so a second, independent pass
with fresh eyes can surface what the first pass missed. Accepts
the same ``<provider>/<model>`` strings as ``STRIX_LLM``
(e.g. ``"anthropic/claude-opus-4-7"``).
"""
inner = _ctx(ctx)
coordinator = coordinator_from_context(inner)
@ -577,6 +591,16 @@ async def create_agent(
default=str,
)
if model is not None:
api_base = load_settings().llm.api_base
model_error = invalid_model_reason(model, api_base=api_base)
if model_error:
return json.dumps(
{"success": False, "error": f"invalid model: {model_error}", "agent_id": None},
ensure_ascii=False,
default=str,
)
parent_history = list(ctx.turn_input) if inherit_context and ctx.turn_input else []
try:
result = await spawner(
@ -585,6 +609,7 @@ async def create_agent(
task=task,
skills=skill_list,
parent_history=parent_history,
model=model,
)
except Exception as e:
logger.exception("create_agent: scan runner failed to spawn child '%s'", name)

View file

@ -0,0 +1,143 @@
"""Tests for the optional per-agent ``model`` override on ``create_agent``.
``create_agent`` normally spawns children on the scan's configured model.
``model`` lets the caller deliberately give one child a different model (a
"second opinion" specialist) without touching every other agent in the run.
These tests pin down the three contract points: omitting ``model`` must be a
no-op regression guard, a valid alternate model string must be threaded
through to the spawner unchanged, and an invalid model string must fail
cleanly instead of spawning anything or raising.
"""
from __future__ import annotations
import json
from typing import TYPE_CHECKING, Any, cast
import pytest
from agents.tool_context import ToolContext
import strix.tools.agents_graph.tools as agents_graph_tools
from strix.core.agents import AgentCoordinator
from strix.tools.agents_graph.tools import create_agent
if TYPE_CHECKING:
from collections.abc import Iterator
class _FakeLlmSettings:
def __init__(self, api_base: str | None = None) -> None:
self.api_base = api_base
class _FakeSettings:
def __init__(self, api_base: str | None = None) -> None:
self.llm = _FakeLlmSettings(api_base=api_base)
@pytest.fixture
def _no_api_base(monkeypatch: pytest.MonkeyPatch) -> Iterator[None]:
"""Pin ``load_settings()`` so the bare-name validation path is deterministic."""
def _load_fake_settings() -> _FakeSettings:
return _FakeSettings()
monkeypatch.setattr(agents_graph_tools, "load_settings", _load_fake_settings)
yield
async def _graph() -> AgentCoordinator:
coordinator = AgentCoordinator()
await coordinator.register("root", "strix", parent_id=None)
await coordinator.attach_runtime("root", resumable=False)
return coordinator
class _RecordingSpawner:
"""Stand-in for the ``spawn_child_agent`` closure the runner puts in context."""
def __init__(self) -> None:
self.calls: list[dict[str, Any]] = []
async def __call__(self, **kwargs: Any) -> dict[str, Any]:
self.calls.append(kwargs)
return {
"success": True,
"agent_id": "child-1",
"name": kwargs.get("name"),
"parent_id": kwargs.get("parent_ctx", {}).get("agent_id"),
"message": "spawned",
}
async def _call_create_agent(
coordinator: AgentCoordinator, spawner: _RecordingSpawner, args: dict[str, Any]
) -> dict[str, Any]:
ctx = ToolContext(
context={
"coordinator": coordinator,
"agent_id": "root",
"spawn_child_agent": spawner,
},
tool_name=create_agent.name,
tool_call_id="call-1",
tool_arguments="{}",
)
raw: str = await create_agent.on_invoke_tool(ctx, json.dumps(args))
return cast("dict[str, Any]", json.loads(raw))
@pytest.mark.asyncio
async def test_omitting_model_spawns_exactly_as_before(_no_api_base: None) -> None:
coordinator = await _graph()
spawner = _RecordingSpawner()
result = await _call_create_agent(
coordinator, spawner, {"name": "Validator", "task": "check the thing"}
)
assert result["success"] is True
assert len(spawner.calls) == 1
assert spawner.calls[0]["model"] is None
@pytest.mark.asyncio
async def test_valid_alternate_model_is_threaded_through_unchanged(_no_api_base: None) -> None:
coordinator = await _graph()
spawner = _RecordingSpawner()
result = await _call_create_agent(
coordinator,
spawner,
{
"name": "Second Opinion",
"task": "re-review already-covered surfaces",
"model": "anthropic/claude-opus-4-7",
},
)
assert result["success"] is True
assert len(spawner.calls) == 1
assert spawner.calls[0]["model"] == "anthropic/claude-opus-4-7"
@pytest.mark.asyncio
async def test_invalid_model_string_returns_a_clean_error(_no_api_base: None) -> None:
coordinator = await _graph()
spawner = _RecordingSpawner()
result = await _call_create_agent(
coordinator,
spawner,
{
"name": "Second Opinion",
"task": "re-review already-covered surfaces",
"model": "definitely-not-a-real-model",
},
)
assert result["success"] is False
assert "invalid model" in result["error"]
assert result["agent_id"] is None
assert spawner.calls == []