Agents¶
An agent is a model with tools, a budget, and an identity — declared next to the routes it can call.
app.agent(
"assistant",
description="Answers questions about tickets.",
system="You help support staff triage tickets. Prefer read-only tools.",
tools=["list_tickets", "get_tickets", "get_tickets_by_id_summary"],
context=["policy"],
memory="notes",
scopes=["read"],
expose_scopes=["read"],
max_steps=8,
token_budget=50_000,
expose_at="/ask",
)
model defaults to the default alias — see Models — so an agent
need not name a model at all.
What makes this different from writing a tool loop¶
Four things, and they are all enforced by the runtime rather than by your diligence.
1. Tools are the app's own routes¶
Dispatched in-process. Ten tool calls cost ten function calls, not ten loopback HTTP round trips. No second schema, no drift. Other agents, behaviours and flows are routes too, so they are tools too — see Orchestration.
A typo in tools, handoffs or context is a boot error, with a
suggestion:
webcortex: agent "assistant" references tool "list_ticket", which is not an
exposed route. Did you mean "list_tickets"?
2. Authority is delegated, never granted¶
This is the most important line in the runtime:
Delegated scopes are the intersection of what the agent declares and what the caller holds — never the union.
| Caller holds | Agent declares | Agent gets |
|---|---|---|
["read", "write"] |
["read"] |
["read"] |
["read"] |
["read", "write"] |
["read"] — not write |
[] (anonymous) |
["admin"] |
[] — nothing |
["read", "write"] |
[] (unset) |
["read", "write"] — inherits |
An agent is a delegate, never an escalation. This is the confused-deputy defence, and it holds whether the run started over HTTP, over MCP, from a Behaviour, from a supervisor agent, or through a handoff — which intersects once more with what the previous agent held.
scopes and expose_scopes are different questions
scopes— what a run may doexpose_scopes— who may start a run
They default to the same set, because an endpoint that spends tokens and
exercises tools should not be less guarded than the tools themselves.
Passing expose_scopes=[] makes the endpoint public, and so does leaving
both unset; webcortex security reports either. So does an
expose_scopes that app.anonymous_scopes(...) covers: anyone may start
that agent, so give it a token_budget.
3. Budgets are enforced by the runtime — and they compose¶
max_steps and token_budget are checked before each provider call. A looping
model costs a bounded amount rather than whatever the provider will sell you.
max_steps counts model calls, not tool calls: one response may ask for several
tools, and all of them run, so it bounds rounds rather than tool executions.
Scopes and approval gates are what bound which tools can run.
The budget of the outermost run is shared by every agent, behaviour and flow it
calls; see Budgets compose.
{
"status": "budget_exhausted",
"usage": {"steps": 12, "tool_calls": 9,
"input_tokens": 31402, "cache_read_tokens": 88100, "output_tokens": 18730,
"handoffs": 0, "compactions": 1, "tree_tokens": 161240}
}
Possible outcomes: completed, max_tokens (the last response was cut off),
step_limit, budget_exhausted, awaiting_approval, failed.
4. Everything is audited — including refusals¶
{"events": [
{"kind": "agent_started", "run_id": "…", "actor": "agent:assistant#service",
"detail": {"granted_scopes": ["read"], "tools": ["list_tickets", "..."]}},
{"kind": "tool_called", "tool": "list_tickets",
"detail": {"arguments": {"limit": 20}, "ok": true, "duration_ms": 3}},
{"kind": "tool_refused", "tool": "delete_tickets",
"detail": {"reason": "missing required scope(s): write"}},
{"kind": "handoff", "tool": "transfer_to_billing",
"detail": {"from": "front_desk", "to": "billing", "reason": "invoice question"}},
{"kind": "approval_decided", "tool": "create_tickets_purge",
"detail": {"approval_id": "…", "approved": false, "note": "not today"}}
]}
granted_scopes on the start event proves what the run could have done —
usually the fact you want during an incident. Refusals are recorded because
they are the interesting events.
The result¶
{
"run_id": "9f3c…",
"agent": "assistant",
"path": ["assistant"],
"status": "completed",
"output": "Three tickets are urgent: #41, #47 and #52.",
"session_id": "u1-2026-09-13",
"steps": [
{"index": 0, "kind": "model", "result": {"model": "claude-opus-5", "input_tokens": 2104, "output_tokens": 88}, "duration_ms": 1410},
{"index": 1, "kind": "tool_call", "tool": "list_tickets", "arguments": {"limit": 50}, "result": [...], "duration_ms": 3},
{"index": 1, "kind": "model", "result": {...}, "duration_ms": 980}
],
"usage": {"steps": 2, "tool_calls": 1, "input_tokens": 4300, "output_tokens": 210, "tree_tokens": 4510, "...": "..."}
}
path lists every agent the run passed through; agent is the one that
answered. Step kinds are model, tool_call, tool_refused,
approval_requested, approval_denied, handoff, compaction and, for an
agent declared with output=, output.
Since 2.8 the result also carries trace_id, the id of the run's
trace (the span tree of this run and everything it called), and,
for an agent with an output schema, data: the
validated answer as an object.
Approval gates¶
The difference between an agent you can point at production and a demo.
@app.post("/tickets/purge", tool=True, scopes=["admin"], approval="required")
def purge(confirm: bool = False) -> dict:
"""Delete every closed ticket. Requires human approval."""
...
When an agent requests a gated tool, the runtime suspends the run and
returns 202 with an approval request. The tool does not execute.
{
"status": "awaiting_approval",
"run_id": "9f3c…",
"pending_approval": {
"approval_id": "b71e…",
"tool": "create_tickets_purge",
"arguments": {"confirm": true},
"reason": "tool is gated and requires human approval before it runs"
}
}
A human decides at POST /_webcortex/approvals/b71e… with
{"approve": true|false, "note": "…"}, and the run continues — including the
rest of the turn it was interrupted in. See
Approvals that resume.
The run must also hold the route's scopes. If it does not (an agent declared
with scopes=["read"] asking for a tool that needs admin, or a caller who
holds only read), the call is refused at once with WC602 and no approval is
created, because approving a call the run could never make would only fail
afterwards. Since 2.9 the hint names the agent and the scopes it holds, and
says to add the scope to its scopes=. To let an agent propose a gated action,
give it the route's scopes; the intersection with the caller's scopes still
decides whether a given run can.
The gate holds on every path a model can take:
- Directly over MCP — refused (
WC309), because honouring it only inside the agent loop would leave an obvious way around - Wrapped in a Behaviour, alone or inside
ctx.gather— the Behaviour halts - As a flow step, directly or through a nested flow, a parallel branch or a route — a boot error. A flow cannot wait for a human, so such a flow is refused when the app starts, and MCP and behaviours refuse to start a flow that contains one. (Before 2.9 the gated step ran without approval.)
It does not apply to a person calling the route directly over HTTP. A
caller holding the route's scopes gets it at once, like any other route:
scopes decide who may call it at all, and the gate decides that a model may
not call it unattended.
An approval gate on a route that is not exposed as a tool is a boot error: a gate that can never fire is dead configuration giving false confidence.
Invoking an agent¶
Configuration¶
| Argument | Default | Purpose |
|---|---|---|
model |
"default" |
A model name or an alias from app.models |
system |
"" |
System prompt |
tools |
() |
Exposed route tool names — routes, agents, behaviours, flows |
handoffs |
() |
Agents this one may transfer the conversation to |
context |
() |
Context providers resolved at run start |
memory |
None |
A store from app.memory; adds its tools and a hint |
scopes |
() |
What a run may do (intersected with caller) |
expose_scopes |
= scopes |
Who may start a run |
max_steps |
12 |
Provider round trips |
token_budget |
None |
Total tokens for the run and everything it calls |
cache |
True |
Prompt caching of system prompt and tools |
tool_result_limit |
16384 |
Bytes of any tool result the model sees |
context_window |
None |
Measured input tokens beyond which older turns are compacted |
compact_with |
"fast" |
Model used for compaction |
keep_recent |
6 |
Messages kept verbatim by a compaction |
temperature |
None |
Sent only when set; Claude Opus 5, Opus 4.7/4.8 and Sonnet 5 reject it |
reasoning |
None |
none, low, medium or high; sent as reasoning_effort to OpenAI-compatible providers. none makes a local thinking model answer at once |
max_tokens |
16000 |
Per response, thinking included |
max_images |
4 |
Images kept in the conversation as pixels; older ones become placeholders. See Vision and robotics |
expose_at |
/agents/<name-with-hyphens> |
The POST route |
tool |
True |
Expose under the agent's own name |
output |
None |
A dataclass, TypedDict or object schema the answer must match; the validated value is data in the result. See Structured output |
options |
None |
Extra request-body fields for the provider, e.g. {"seed": 7}. See Request options |
Every run records a trace (its id is trace_id in the result), and an agent's
behaviour can be pinned down with evals that replay recorded model responses.
Providers¶
Anthropic (Messages API) and any OpenAI-compatible endpoint (Ollama, vLLM,
LM Studio, OpenAI, Groq, OpenRouter), selected by model name prefix. Set
ANTHROPIC_API_KEY and/or OPENAI_API_KEY; ollama/<model> needs no key.
Models has the details.
An app with declared agents but no key still boots; a run that needs a missing key fails with a message naming the variable, and everything else keeps serving.
Deliberately not a universal LLM abstraction
Two wire formats, each done properly, behind a trait narrow enough that the runtime never knows which one it is talking to. Conversations are kept in one canonical shape, so a session can move between providers.
Limits worth knowing¶
- Runs are ephemeral. Sessions and suspended approvals live in memory, bounded and expiring, and do not survive a restart. Durable, resumable runs mean building a small workflow engine with exactly-once tool execution; that is deliberately not in v2.
- Each caller has a share of those stores. Since 2.9 a caller (the root principal) that fills its share of the session or approval store evicts its own oldest entry, never another caller's, so one key cannot push everyone else's pending approvals out.
- Turns over a WebSocket count against the rate limit, and a socket opened with a JWT stops at the token's expiry. See Security.
- Responses are returned whole. Token-level SSE streaming is the next invasive change and is not claimed.