Skip to main content

Agent Team tools

The agent_team_* family is the C# layer underneath the Multi-Agent Studio. Where MAS is the user-facing concept ("specialists with brief contexts"), agent_team_* is the wire-level API that makes specialist orchestration deterministic and replayable.

Every multi-agent run can be reduced to a sequence of agent_team_* calls. The studio UI is just sugar on top.

The core verbs​

ToolPurpose
agent_team_list_specialistsEnumerate available specialists, their tool views, and their input/output schemas.
agent_team_handoffDirector → specialist handoff. Takes {specialist, brief, tool_view, model?, temperature?}. Returns a handle.
agent_team_queryPoll a handle for status / partial output / completion.
agent_team_cancelCooperatively cancel an in-flight specialist run.
agent_team_recordPersist a complete director-and-specialists trace to disk as a replayable JSON file.
agent_team_replayRe-run a recorded trace against the current registry. Useful for regression tests.

A handoff in JSON​

{
  "tool": "agent_team_handoff",
  "input": {
    "specialist": "clothing-rigger",
    "brief": "Rig 'Assets/Garments/Jacket.fbx' onto Player avatar. Bake weights with 4 bones max per vertex. Save the rigged prefab to 'Assets/Rigged/Jacket_Player.prefab'.",
    "tool_view": ["clothing_*", "asset_*"],
    "model": "anthropic/sonnet-4-7",
    "temperature": 0.2
  }
}

Response (immediate, async):

{
  "ok": true,
  "handle": "team_8f4a2c1",
  "status": "running",
  "estimated_steps": null
}

Poll:

{
  "tool": "agent_team_query",
  "input": { "handle": "team_8f4a2c1" }
}

Response (when complete):

{
  "ok": true,
  "handle": "team_8f4a2c1",
  "status": "done",
  "tool_calls": 17,
  "duration_ms": 24310,
  "artifact": {
    "rigged_prefab": "Assets/Rigged/Jacket_Player.prefab"
  },
  "report": "Detected 0.4mm avg garment-to-skin gap. Aligned via 14 anchor points. Bake produced 3.2 avg bones per vertex (under cap). 0 inverted normals."
}

Tool views as glob filters​

The tool_view parameter is an array of glob patterns. The specialist sees only matching tools:

"tool_view": ["clothing_*", "asset_*", "prefab_apply", "prefab_unpack"]

This list resolves at handoff time, so a specialist run never sees a stale tool that was removed mid-session. Patterns:

  • family_* matches every tool with that prefix.
  • exact_name matches one tool.
  • * (alone) matches everything — equivalent to no filter, useful for debug specialists.

Models per specialist​

agent_team_handoff accepts an optional model parameter that overrides the specialist's default. Letting different specialists run on different models is one of the highest-leverage optimizations available:

  • Use Opus / GPT-4o for the director (planning is expensive to get wrong).
  • Use Haiku / GPT-4o-mini for read-heavy specialists (scene-inspector, console-reader).
  • Use Sonnet / Gemini Flash for write-heavy specialists with deterministic tools.

Recording for regression​

Every multi-agent run can be recorded:

{
  "tool": "agent_team_record",
  "input": { "handle": "team_8f4a2c1", "output_path": "Assets/BurilTests/JacketRig_2026_05_19.json" }
}

Later, replay the recording:

{
  "tool": "agent_team_replay",
  "input": { "trace_path": "Assets/BurilTests/JacketRig_2026_05_19.json" }
}

The replay does not call the LLM again — it issues the same tool calls in the same order and validates that the same artifacts are produced. This is how Buril's autoplay regression suite catches behavior drift after refactors.

Failure modes​

Specialists can fail at three levels. Each is reported distinctly:

FailureWhat it meansRecovery
status: "blocked"A required tool is missing from the registry (e.g., the user uninstalled a companion).Director re-routes to another specialist or asks the user to install the missing dependency.
status: "errored"A tool call returned ok: false. The error is surfaced verbatim in the report.Director can retry once, then ask the user.
status: "cancelled"User pressed Stop, or agent_team_cancel was invoked.No retry — return to the user.

From C#​

You can call the studio from your own code without going through chat:

var handle = await BurilAgentTeam.Handoff(
    specialist: "clothing-rigger",
    brief: "Rig Assets/Garments/Jacket.fbx onto Player avatar.",
    toolView: new[] { "clothing_*", "asset_*" }
);

var result = await BurilAgentTeam.WaitFor(handle, timeoutMs: 60000);
Debug.Log(result.Report);

This is the recommended pattern for headless / CI pipelines.