billing step. Give billing its own key and a guardrail that only it runs, and link the researcher agent so the orchestrator may call it, and nothing else.
An agent can have sub-agents of two kinds:
An agent may call only the agents it links. With no linked sub-agents, it may call none. Inline sub-agents are not agents: they have no sub-agents of their own.
Sub-agents replace agent roles. The
x-xenovia-agent-role header, and an agent_role field sent to the decision endpoint, are refused with 400; use a key scoped to an inline sub-agent instead.
Inline sub-agents
Add one
1
Open the Sub-agents tab
Open the agent and go to the Sub-agents tab, then the Sub-agents view.
2
Add the sub-agent
Choose Add sub-agent. Enter a Name: 1 to 64 letters, digits, dots, underscores or hyphens. Names are case-sensitive and unique within the agent. Add a Description (optional), then choose Add sub-agent.
3
Add its guardrails and capabilities
Open the sub-agent. Under Extra guardrails, add the guardrails that run only on this step’s calls. Under Extra capabilities, add what this step may also be asked to do.
4
Create a key
Under Keys, choose Create key. The key is shown once. Connect this step shows how to send the step’s model calls through the agent with it.
Keys and what they scope
A sub-agent key is anxe_ key of the agent that also names the sub-agent. Use it with the agent’s own endpoint, exactly as you would an agent key:
- Guardrails. Every agent-wide guardrail applies, plus the sub-agent’s own. A sub-agent can only add guardrails, never remove one.
- Capabilities. The sub-agent’s capabilities are added to the agent-wide ones; one with the same name as an agent-wide capability replaces it for this step. The purpose gate judges the call against that set.
- Policies are agent-wide. They see the sub-agent in
input.sub_agent(see Policy fields). - Provider, model and hosted tool allow-list are the agent’s.
Rename or delete one
Renaming an inline sub-agent keeps its guardrails, capabilities and keys. Deleting it deletes them too, and its keys stop working at once.Linked sub-agents
Link an agent
1
Open Linked sub-agents
Open the calling agent, go to the Sub-agents tab, then Linked sub-agents.
2
Link the agent
Choose Link agent and pick the agent. The agent itself, hybrid agents and agents already linked are not listed.
Call a linked agent
Send the request to the linked agent’s endpoint with the calling agent’s key. A key scoped to one of the caller’s inline sub-agents works too:- the key is valid and its agent is active;
- the linked agent is an active agent of the same organization;
- the calling agent links it.
401 invalid api key for this agent as any key that can’t act as that agent, so the answer never reveals whether the agent exists. A linked agent still in draft is refused this way until it’s activated.
What governs a linked call
The call runs as the linked agent: its provider and fallbacks, its policies and its guardrails apply, and its turn is recorded on it. The caller still limits what the call may do:- Purpose gate. The calling agent’s purpose and agent-wide capabilities judge the call too, and so do the capabilities of the caller’s inline sub-agent when its key is scoped to one.
- Hosted tools. A hosted tool the request declares must be allowed by both agents’ allow-lists.
- Policies of the linked agent see who called it (see Policy fields).
X-Xenovia-Workflow-Id only groups the calls of a multi-agent run into one workflow; it never lets a key call an agent it doesn’t link. To keep an orchestrator’s turns and its linked calls in one session, send the same X-Xenovia-Session-Id to each agent; agents of the same organization can share a session.
Policy fields
Policies receive the call’s identity, built from the verified key only:agent_depth is a label your code supplies, not something the runtime measures. For example, this policy lets only the caller’s planner step call the agent:
Sessions and traces
In Sessions, a turn made with a sub-agent key shows a Sub-agent chip with its name, and a linked call shows Called by with the calling agent. The Sub-agent filter keeps the sessions with any turn made by that inline sub-agent. The management API returns the same identity:GET /api/v1/sessions?sub_agent=<name>filters sessions by inline sub-agent. Each session summary carriessub_agents(the inline sub-agents that made its turns) andhas_linked_calls.- Trace records carry
sub_agent,caller_agent_id,caller_agent,caller_sub_agentandagent_depth.
Manage sub-agents with the API
Guardrails and capabilities take a
sub_agent_id to scope them to an inline sub-agent (null for the whole agent).
Key management is for signed-in people only: an organization API key can’t list, create or revoke sub-agent keys. A refused change answers 422 with a detail object holding a code and a message, and changes nothing:
Every change is recorded in the audit log (
agent.sub_agent.create, .update, .delete, .key.create and .key.revoke).
What next?
Policies
Write rules that see which sub-agent called.
Neon
Add guardrails for one step.
Sessions
See which step made each call.