---
title: "Add an inline or a linked sub-agent"
method: POST
path: "/api/v1/agents/{agent_id}/sub-agents"
tags: ["agents"]
---

# Add an inline or a linked sub-agent

`POST /api/v1/agents/{agent_id}/sub-agents`

## Request

- Base URL: `https://cp.xenovia.io` (the document declares no server; this is the origin it was published from)
- URL: `https://cp.xenovia.io/api/v1/agents/{agent_id}/sub-agents`
- Auth: none declared

``{"kind": "inline", "name", "description"?}`` adds a step inside the
agent; ``{"kind": "linked", "agent_id"}`` lets the agent call another
agent of its organisation (not itself, not a hybrid one). At most 50
inline and 200 linked per agent. Audited ``agent.sub_agent.create``; the
agent's config version advances, so the runtime picks it up.

## Path parameters

- `agent_id` string, uuid, required

## Headers

- `Authorization` string, nullable
- `X-Request-ID` string, nullable

## Request body

- union
  - InlineSubAgentCreate
    - `kind` 'inline', required
    - `name` string, required
    - `description` string, nullable
  - LinkedSubAgentCreate
    - `kind` 'linked', required
    - `agent_id` string, uuid, required

## Response `201`

Successful Response

- union
  - InlineSubAgentRead
    - `id` string, uuid, required
    - `kind` 'inline'
    - `name` string, required
    - `description` string, nullable, required
    - `created_at` string, date-time, required
    - `checks_count` integer
    - `capabilities_count` integer
    - `keys_count` integer
  - LinkedSubAgentRead
    - `id` string, uuid, required
    - `kind` 'linked'
    - `agent_id` string, uuid, required
    - `agent_name` string, nullable, required
    - `agent_status` 'draft' | 'active', required
    - `created_at` string, date-time, required

## Other responses

- `422`: Refused (`detail.code`): `invalid_name`, `duplicate_name`, `not_found` (no agent of this organisation has the id), `self`, `hybrid`, `duplicate_link`, `limit`, `not_inline`

## Changes

- **2026-10-26** `3e25bef24f8f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/xenovia/apis/controlplane/changes/api/v1/agents/:agent_id/sub-agents/post.md)

---

[API](https://skmtc.dev/xenovia/apis/controlplane.md) - [All operations](https://skmtc.dev/xenovia/apis/controlplane/llms.txt) - [OpenAPI document](https://skmtc.dev/xenovia/apis/controlplane/revisions/3e25bef24f8f?raw)