Agent calls¶
A task has one answering agent. That agent brings in other agents with the
agent tool: {agent, title, brief, background?}. It is the one way a run
calls an agent. The title is a few imperative words (at most 60 characters)
shown on the call's card; the brief is everything the agent is told. Each call
runs the agent as a child run of the caller that carries the call's id
(call_id, htu_<run>_<n>), so its work streams under the call, and its
answer is the call's result. The caller owns the user-facing answer. Parallel
agents are parallel calls.
Access.Spawn grants the tool: an agent that may call others has it without
listing it. Stopping the caller stops the child, the child's spend counts
toward the caller, and a call the callee's policy holds waits for a person. A
client of the humagen MCP makes no agent call of its own: it posts a message
(send_messages), which starts a run.
Background calls¶
With background: true the caller hands the work over and carries on. The
call passes the same checks as one that waits (the spawn allowlist, the
callee's call policy, the action policy, depth, fan-out and budget) and answers
at once with {"status": "launched", "agent", "run"}, never with the work's
result. The run it starts is delegated, not attached: it outlives its caller,
is not stopped with it, and its spend is not rolled into the caller's. It
carries the call's id as call_id, and its answer arrives later, as a response
of its own that names the call it is for and in the inbox.
Earlier names¶
The names an agent called other agents by before are read in one place,
internal/legacy/tools.go, and nothing else names them.
| Stored name | Read as |
|---|---|
call_agent in a spec's tools |
Nothing: Access.Spawn grants the agent tool |
delegate_task in a spec's tools |
Nothing: Access.Spawn grants the agent tool, and a call that does not wait sets background |
call_agent or delegate_task in a spec's approvals |
An approval of the agent tool, once |
tag_<agent> in a spec's tools |
Nothing: no per-agent tool is offered |
tag_<agent> in a spec's approvals |
The agent tool's calls to that one agent wait for a person, asked of the spec's approvers |
| Any of them in a skill's tool restriction | The restriction allows the agent tool (tag_<agent>: for that agent only) |
A saved revision is not rewritten: it keeps loading as it is, and is read this
way each time it runs. The runtime's own calling verbs (session_call,
session_listen, session_status) and per-agent tag_<agent> tools are not
offered to any run. session_read and session_link are still offered to a
run with a session: they read and cite another session, and call nothing.
The tool has one definition, in the system tool registry
(agent operations): its description,
its arguments, its category (call_agents) and who approves a call. A run is
offered that definition with agent narrowed to the agents the caller may
call. A call is held twice: by the called agent's call policy, which names
its own approvers, and by the action policy for call_agents. A caller whose
spec approves tag_<agent> holds its own calls to that agent too.
Calls made for mentions¶
A message that mentions several agents is answered by the entry agent, and the
platform makes those agent calls itself before that run's first model step
(internal/platform/mention_calls.go). Each is an agent call of the run like
any other: a child run through the same call path, checked by the same spawn
allowlist and call policy, keyed by its htu_<run>_<n> id and carrying it as
call_id, with what it spent counted toward the root. The run records each as
a call to the agent tool and its result, so activity shows them where the
entry agent's own calls show. The model is never shown a tool call it did not
make: what each agent said reaches it as content of the person's turn, with the
answer it is to write, each result as given under a heading with its agent's
name, then a short synthesis if one helps. The run's final text is the model's
own; the platform does not rewrite it. A call that is refused or fails is said
so in its place, and stopping the root stops the calls it waits on.
Two checks are made before any of those calls. An agent that lives where not
everyone who reads the conversation's project reads is not called there
(Available, admission's own check): the entry agent is told it cannot answer
here and where it can be asked. A call that waits for a person waits for one
as the same call made by the model does, because both ask the one wrapper every
run tool passes through: the callee's call policy holds it, or the action
policy for call_agents says ask. The root parks on the approval, addressed
to that policy's approvers and tied to the call's id, before anyone is called,
one call at a time. Approved, the call is made; denied or expired, the entry
agent is told so in its place. An action policy of never refuses the call.
Constructing input¶
A program that holds a run calls helpers with a constructed conversation and a
return format through POST /api/runs/{id}/calls. Helpers receive exactly that
conversation and return material for the caller to use. A helper's full result
stays available in execution history.
{
"agent": "researcher",
"messages": [
{"role": "user", "content": [{"type": "text", "text": "Example question"}]},
{"role": "assistant", "content": [{"type": "text", "text": "Example summary"}]},
{"role": "user", "content": [
{"type": "conversation_range", "thread": "thread-id", "from": "first-run-id", "through": "last-run-id"},
{"type": "artifact", "id": "artifact-id", "version": 2},
{"type": "run_result", "run": "completed-run-id"},
{"type": "text", "text": "Assess the approach. Focus on unresolved risks."}
]}
],
"response_format": {"type": "summary", "max_words": 200},
"mode": "subagent"
}
Messages are ordered. Context, examples and the request all use this one list.
Only user and assistant roles are accepted, and the list ends with a user
message. Supplied assistant messages are examples or selected history. They
cannot impersonate tool results or system instructions. No conversation,
source connector credentials, or parent memory is inherited implicitly.
The helper keeps its own pinned definition and its own access grants.
Content is a closed union. text carries inline text; conversation_range
selects inclusive run endpoints on one branch of the named conversation;
artifact requires an exact ID and version and supplies UTF-8 text;
run_result supplies a completed run's answer. Foreign-tenant references are
reported as missing. Unavailable, running, oversized or non-text references
fail the call before a helper starts. References currently follow the existing
workspace visibility model: there is no finer per-project or per-run read ACL.
Inputs allow at most 64 messages, 128 parts and 64,000 serialized bytes. Resolved text has its own 64,000-byte bound. A conversation range contains at most 64 turns. Nothing is silently truncated or summarized during resolution.
Return contracts¶
type ResponseFormat =
| { type: "text"; max_chars?: number }
| { type: "summary"; max_words?: number }
| { type: "json_schema"; schema: JsonSchema };
The discriminator selects both a host-generated instruction and validation.
Fields from another variant, unknown fields and unknown types are errors.
text defaults to 16,000 characters and permits at most 64,000. summary
defaults to 200 whitespace-separated words and permits at most 2,000. JSON
results must consist of one JSON value, with no surrounding prose or fences.
Schemas use saige's compiled JSON Schema validator; unsupported keywords fail
before execution instead of being ignored.
fiber's current provider boundary has a system channel, without a separate developer channel. The host appends the bounded return contract to the helper's system instructions, explicitly subject to its pinned rules. The caller cannot supply arbitrary privileged instruction text. JSON schemas are identified as data. Tools, spawn grants, budgets and tenant scope remain enforced outside the model regardless of what an instruction says.
A summary instruction guides relevance; validation checks its word limit, not its quality. Contracted answer text is withheld from the public event stream until validation succeeds. Other execution events remain live. An invalid result becomes a terminal helper failure and a tool error for the waiting caller. It is never silently clipped, repaired or automatically regenerated. Actions already performed by a helper are not undone by an invalid result.
Execution and ownership¶
| Mode | Calling agent | Result |
|---|---|---|
subagent, the default |
Waits for its helper | Receives validated text as the tool result |
delegate (the agent tool's background) |
Continues immediately | Receives the run reference; the validated result later appears in the inbox and execution history |
Both modes go through Platform.Call and pkg/call. The caller's pinned spawn
allowlist, depth, fan-out, budget and admission policy apply. Waiting calls keep
one execution slot available so a chain of helpers cannot occupy every slot
while waiting. Attached work stops with its caller; delegated work is independent.
A return format never changes these lifecycle or delivery rules.
The agent tool offers a run only the agents available where its calls are filed: one that lives elsewhere would be refused, and the run's readers may not read it. An agent that lives in a project a reader may not read is left out of the spawn list and the call policy lists they read. Naming one when they write either is refused as naming an agent that does not exist, a call to one through the calls endpoint is refused as one the spawn allowlist does not name, and saving what they read keeps what they were not shown (see security).
The low-level API's existing handoff mode is not exposed by the agent tool.
A real handoff needs explicit answer ownership transfer and caller termination;
selecting a return format does neither.
Before acceptance the platform resolves references and stores both their
provenance and the exact resolved messages in the child tag. The run's input
field exposes that snapshot to the existing run-detail and execution-history
views. Retries execute from the snapshot rather than reading the references
again. A repeated call ID joins its accepted child even after references are
removed or the fan-out allowance has been consumed. Reusing a call ID with
different input is an error. Tool call IDs also correlate parallel helper
steps with their runs, independent of start order.
Access.Spawn makes the agent tool available automatically. The calls HTTP
endpoint retains its text shorthand, normalized to a user message and a text
return contract, and also accepts the structured contract under input.
Runtime dependency¶
fiber is saige/flow, pinned with the rest of saige in go.mod
(github.com/urmzd/saige). It carries:
- the call extension;
- model fallbacks with fallback_on, and per-call approvals through
native.Approving (github.com/urmzd/saige/flow/turn/native);
- mcp:<provider>[:write] grants from the tool provider store, which is
Humagen's internal/toolprovider;
- unavailable tools and tool groups dropped with a warning rather than
failing the run.
make test covers fiber and Humagen together.