> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xenovia.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Sub-agents

> Give one step of an agent its own key and checks, and link the other agents it may call.

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:

| Kind | What it is | How a call is attributed to it |
| - | - | - |
| **Inline** | A step inside the agent, such as a planner or a billing step. It uses the agent's provider and model, and adds its own guardrails and capabilities. | The call is made with a key scoped to it. Nothing else a caller sends (a header, a body field) selects one. |
| **Linked** | Another agent of your organization that this agent may call. It keeps its own provider, keys, policies and guardrails. | The calling agent's key is sent to the linked agent's endpoint. |

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:

```python theme={null}
import os
from openai import OpenAI

billing = OpenAI(
    base_url="https://runtime.xenovia.io/<agent_id>/v1",
    api_key=os.environ["XENOVIA_BILLING_KEY"],  # a key of the "billing" sub-agent
)
```

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](#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](https://docs.xenovia.io/organization/hybrid.md).

### 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.

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:

```python theme={null}
import os
from openai import OpenAI

researcher = OpenAI(
    base_url="https://runtime.xenovia.io/<researcher_agent_id>/v1",
    api_key=os.environ["XENOVIA_ORCHESTRATOR_KEY"],  # the calling agent's key
)
```

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](#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:

| Field | Value |
| - | - |
| `input.sub_agent` | With a key scoped to one of this agent's inline sub-agents: `{id, name, kind: "inline", parent_agent_id}`, the parent being this agent. On a linked call: `{id, name: "", kind: "linked", parent_agent_id}`, the id being this agent and the parent the calling agent. `null` for the agent's own keys. |
| `input.caller_agent_id` | On a linked call, the calling agent's ID. Absent otherwise. |
| `input.caller_sub_agent` | On a linked call made with a key scoped to one of the caller's inline sub-agents, `{id, name}`. `null` otherwise. |
| `input.agent_depth` | The value of the `x-xenovia-agent-depth` request header: a whole number your code sets for how deep in a chain of agent calls this call is, capped at 32. `0` when it's absent or not a whole number. |

`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:

```rego theme={null}
package xenovia
import future.keywords.if

default decision = {"action": "allow"}

decision = {"action": "block", "rule": "planner-only"} if {
    input.sub_agent.kind == "linked"
    not input.caller_sub_agent.name == "planner"
}
```

See [Policies and Enforcement](https://docs.xenovia.io/control/policies.md) 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

| Endpoint | What it does |
| - | - |
| `GET /api/v1/agents/{agent_id}/sub-agents` | Lists the agent's inline sub-agents (with how many guardrails, capabilities and keys each has) and its linked sub-agents |
| `POST /api/v1/agents/{agent_id}/sub-agents` | `{"kind": "inline", "name", "description"}` adds an inline sub-agent; `{"kind": "linked", "agent_id"}` links an agent |
| `PATCH /api/v1/agents/{agent_id}/sub-agents/{sub_agent_id}` | Renames or redescribes an inline sub-agent |
| `DELETE /api/v1/agents/{agent_id}/sub-agents/{sub_agent_id}` | Deletes an inline sub-agent, or unlinks an agent |
| `GET /api/v1/agents/{agent_id}/parents` | Lists the agents that link this one |
| `GET`, `POST /api/v1/agents/{agent_id}/sub-agents/{sub_agent_id}/keys` | Lists (masked) or creates an inline sub-agent's keys |
| `DELETE /api/v1/agents/{agent_id}/sub-agents/{sub_agent_id}/keys/{key}` | Revokes a key, given as the masked key the list shows |

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:

| Code | When |
| - | - |
| `invalid_name` | The name isn't 1 to 64 letters, digits, dots, underscores or hyphens |
| `duplicate_name` | The agent already has an inline sub-agent with that name |
| `not_found` | No agent of your organization has that ID |
| `self` | The agent would link itself |
| `hybrid` | The agent to link runs on a hybrid deployment |
| `duplicate_link` | The agent already links that agent |
| `limit` | 50 inline or 200 linked sub-agents reached |
| `not_inline` | Only an inline sub-agent can be changed or given keys |

Every change is recorded in the audit log (`agent.sub_agent.create`, `.update`, `.delete`, `.key.create` and `.key.revoke`).

## What next?

> [card] [Policies](https://docs.xenovia.io/control/policies.md)
>
> Write rules that see which sub-agent called.

> [card] [Neon](https://docs.xenovia.io/control/neon.md)
>
> Add guardrails for one step.

> [card] [Sessions](https://docs.xenovia.io/observability/sessions.md)
>
> See which step made each call.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.