Talon agent
One agent.talon.yaml, one vault-bound key, one derived tenant and one effective policy.
Control-plane pillar · Session understanding
Understand the coding session, not just each provider call.
A coding workflow can fan out across requests, subagents and providers. Talon authenticates the AI use case with one agent key, stays out of orchestration, groups asserted sessions inside that agent boundary, rolls up cache-aware spend, records denials and provider history, applies session soft caps, and leaves signed evidence.
authenticated agent: coding-fleet
session: sess-feature-4711
claude-code generator €2.41
codex executor €1.18
claude-code reviewer €0.64
TOTAL €4.23
talon audit verify --session sess-feature-4711
✓ every signed record VALIDAgent-key authenticationAsserted sessionsProvider/model pathSubagent attributionSession budgetsSigned verification
Two identity layers
Authenticate the AI use case; attribute the subagents inside it.
The Talon agent and the workflow's subagent labels solve different problems. The vault-bound agent key is the policy and budget principal. Session, subagent, parent, client and stage headers explain the work performed inside that authenticated boundary.
Asserted session
A client- or vendor-supplied grouping key scoped by tenant and authenticated agent.
Subagent attribution
Free-form runtime labels such as generator or executor—useful for explanation, not independent authentication.
Session-first view
Move from request logs to a run you can explain.
The primary question is not “what HTTP requests happened?” It is “what happened in this session, what did it cost, which providers and subagents were involved, what was denied, and why did it end?” Talon answers those questions for traffic routed through the authenticated agent path.
History
List requests in one asserted session with providers, models, outcomes and denials.
Cost
Roll up provider-aware session cost, including supported cache token semantics.
Attribution
Carry client-supplied subagent, parent-agent and stage labels for explanation—not workload attestation.
Neutral orchestration contract
The role names belong to your workflow, not Talon.
Planner, generator, reviewer and executor are examples only. Talon does not spawn or authenticate them. Generic X-Talon-* metadata and supported client mappings provide attribution so the session history can be explained.
Authorization: Bearer <talon-agent-key>
X-Talon-Session-ID: sess-feature-4711
X-Talon-Agent-ID: executor
X-Talon-Parent-Agent-ID: generator
X-Talon-Client: my-orchestrator
X-Talon-Stage: generation
# bearer key authenticates the Talon agent
# X-Talon-* values attribute the workflowIdentity topology
Choose whether tools share one budget or keep separate ones.
One Talon agent allowed on both providers gives an orchestrated fleet one cross-provider session budget. Separate Talon agents for Claude Code and Codex give each tool its own policy and budget; the same session string then creates two isolated sessions.
one agent, two providers
→ one (tenant, agent, session) budget
→ subagent labels explain fan-out
separate agents
→ separate keys + policies
→ separate session budgets
→ same session text does not join themSession cost control
Stop a new request when the authenticated agent's session crosses its soft cap.
A new request is denied once accumulated spend plus the pre-request estimate exceeds policies.session_limits.max_cost across provider routes allowed by the agent's effective policy. The denial uses the provider's native error shape and carries structured signed evidence.
Boundary: in-flight and concurrent requests can overshoot; strict atomic reservation is not claimed.
policies:
session_limits:
max_cost: 10.00
cost_limits:
daily: 50.00
monthly: 500.00
# session cap is soft
# concurrent in-flight requests can overshootOperator proof
Inspect one asserted session as one unit.
| Need | Surface | What you get |
|---|---|---|
| See session history | talon audit list --session <id> | Requests, outcomes, providers, models, cost and attribution facts inside the authenticated agent boundary. |
| Hand off evidence | talon audit export --session <id> | Session-scoped signed records. |
| Verify integrity | talon audit verify --session <id> | HMAC verification of records in the session. |
| Read cost in automation | talon costs --session <id> --json | Machine-readable session cost. |
| Inspect agent cost | talon costs --agent <name> | Effective caps and spend for the authenticated AI use case. |
Honest boundaries
What session visibility does not mean.
No fake grouping
Synthetic request-level IDs are evidence correlation, not invented multi-request sessions.
No local action visibility
Files edited, commands run and tools executed locally remain invisible when they never cross Talon.
No subagent attestation
The Talon agent key authenticates the use case. Client-supplied subagent and session labels are not cryptographic workload attestation.
Reproduce the session
Run one multi-provider coding scenario and inspect the full history.
The current demo exercises one authenticated Talon agent across supported Anthropic and OpenAI paths, subagent attribution, cache-aware cost, a session-budget denial and signed verification without requiring real provider keys.