Skip to main content
Give each step of a multi-step agent its own checks, and decide which other agents it may call. For example, an orchestrator has a 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.
An agent can have up to 50 inline sub-agents.

Keys and what they scope

A sub-agent key is an xe_ 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:
A call made with it is the sub-agent’s:
  • 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.
A sub-agent key doesn’t count as the agent’s own key for activation: an agent needs one of its own keys to be activated. Sub-agent keys work only against Xenovia’s cloud runtime, not a hybrid deployment.

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

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.
An agent can link up to 200 agents. A linked agent’s Used by view lists the agents that link it. Unlink refuses the calling agent’s calls to it from then on; the linked agent itself doesn’t change. Deleting an agent removes it from every agent that links it, and so does moving it onto a hybrid deployment.

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 runtime accepts the call only when all of these hold:
  • 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.
Otherwise the call gets the same 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:
See Policies and Enforcement for the decision contract.

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 carries sub_agents (the inline sub-agents that made its turns) and has_linked_calls.
  • Trace records carry sub_agent, caller_agent_id, caller_agent, caller_sub_agent and agent_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.