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

# Register agents

> Record an external agent (Claude Managed, Copilot, …) in the Ntropii registry so workflows can invoke it from inside a runbook step.

A **workflow** is a binding of a **runbook** (the deterministic Python templates that drive the process) to an **entity**, optionally on a schedule. A runbook may invoke external **agents** (Claude Managed, Copilot, …) from inside its steps when it needs LLM-driven artefact generation that doesn't fit the deterministic capabilities surface.

This page covers the registration lifecycle: building an agent on the host platform, recording a reference in Ntropii's registry, and referencing it from a runbook step.

## Why register?

External agents live on host platforms (Anthropic, GitHub/Microsoft, …). Ntropii doesn't host the agent — it holds a **reference** (`kind`, `external_ref`, `tenant_id`) and provisions an API key the agent uses to call back into the Ntropii MCP server. Registration is what makes an agent addressable by Ntropii UUID from inside a runbook step.

The product surface:

* **Workspace API**: `POST /workspace/registry/agents` — creates an agent row, provisions a per-agent API key (hash stored, plaintext returned once).
* **CLI**: `ntro agent create --path <ecosystem-uri> --tenant <slug> --name <slug>`.
* **MCP**: `ntro_agent_create / list / get / delete / create_version`.

## Lifecycle

```
┌──────────────────────────┐    ┌──────────────────────────┐    ┌──────────────────────────┐
│ Build on host platform   │ →  │ Register with Ntropii    │ →  │ Reference from runbook   │
│ (Anthropic Console,      │    │ ntro agent create        │    │ ntro.workflow.agents.    │
│  Copilot Studio, …)      │    │  --path <uri>            │    │  invoke(agent_id, …)     │
└──────────────────────────┘    └──────────────────────────┘    └──────────────────────────┘
```

### 1. Build on the host platform

Each agent kind has its own authoring surface. See the per-platform pages:

<CardGroup cols={2}>
  <Card title="Claude Managed Agents" icon="anthropic" href="/workflows/agents/claude-managed-agents">
    Anthropic-hosted agents with Vault auth + MCP servers + Skills. Production today.
  </Card>

  <Card title="Copilot Agents" icon="microsoft" href="/workflows/agents/copilot-agents">
    GitHub / Microsoft Copilot agents. Coming soon.
  </Card>
</CardGroup>

### 2. Register with Ntropii

Once the agent exists on the host platform and you have its native id, register a reference:

```bash theme={null}
ntro agent create \
  --path anthropic://agents/agent_01SxpziMunFrUbnAYkGB5Hu3 \
  --tenant byng \
  --name audit-handover
```

The CLI returns a JSON payload including the Ntropii **agent id** (a UUID — this is what runbooks use), the resolved `external_ref`, and the **API key plaintext**. The plaintext is shown **once** — store it in the host platform's secrets store (e.g. an Anthropic Vault) so the agent can authenticate to the Ntropii MCP server on callbacks.

The `--path` URI encodes both the kind and the native id:

| Kind             | URI form                                  | Notes            |
| ---------------- | ----------------------------------------- | ---------------- |
| `claude_managed` | `anthropic://agents/<anthropic-agent-id>` | Production today |
| `copilot_agent`  | `copilot://agents/<copilot-agent-id>`     | Future           |

### 3. Reference from a runbook step

From inside any `@runbook.step` method, call `ntro.workflow.agents.invoke`:

```python theme={null}
from ntro.workflow.agents import invoke

@runbook.step(name="draft_auditor_handover", title="Draft auditor handover", icon="FileText")
async def _step_draft_auditor_handover(self, ctx, ...):
    if not ctx.audit_agent_id:
        return None  # Skip when the entity hasn't opted into an agent

    period_summary = {...}  # Compose from upstream step outputs

    result = await invoke(
        ctx.audit_agent_id,
        input={"period_summary": period_summary},
        tenant_slug=ctx.tenant_slug,
        entity_slug=ctx.entity_slug,
        task_id=ctx.task_id,
    )
    return result
```

`agent_id` here is the **Ntropii UUID** returned at registration, not the native id. The adapter resolves it to `(kind, external_ref)` via the registry, picks the right provider (Anthropic Managed Agents in this example), starts a session, polls until terminal, and pulls any output files.

## File passback

When an agent writes files to its sandbox (`/mnt/session/outputs/` for Anthropic Managed Agents), the adapter:

1. Lists session files via the host platform's API.
2. Downloads each file's bytes.
3. Persists to the tenant's `ingest.submitted_documents` with `source = 'agent_output:<ntropii-agent-id>'`.
4. Returns an `AgentResult` containing `output_files: [{document_ref, filename, content_type, size_bytes, source}, …]`.

The persisted rows sit alongside user-uploaded documents in the tenant data plane and are downloadable from the task UI like any other artefact.

## Reference

| Resource       | API                                            | CLI                          | MCP                         |
| -------------- | ---------------------------------------------- | ---------------------------- | --------------------------- |
| Create         | `POST /workspace/registry/agents`              | `ntro agent create --path …` | `ntro_agent_create`         |
| List           | `GET /workspace/registry/agents`               | `ntro agent list`            | `ntro_agent_list`           |
| Get            | `GET /workspace/registry/agents/:id`           | `ntro agent get <id>`        | `ntro_agent_get`            |
| Delete         | `DELETE /workspace/registry/agents/:id`        | `ntro agent delete <id>`     | `ntro_agent_delete`         |
| Create version | `POST /workspace/registry/agents/:id/versions` | `ntro agent create-version`  | `ntro_agent_create_version` |

See [`ntro.workflow.agents`](/sdk/agents) for the invoke API, `AgentResult` shape, and adapter design.

## Related

<CardGroup cols={2}>
  <Card title="Claude Managed Agents" icon="anthropic" href="/workflows/agents/claude-managed-agents">
    End-to-end walkthrough for the Anthropic Managed Agents adapter (production today).
  </Card>

  <Card title="Copilot Agents" icon="microsoft" href="/workflows/agents/copilot-agents">
    Coming soon — GitHub / Microsoft Copilot adapter.
  </Card>

  <Card title="ntro.workflow.agents reference" icon="book" href="/sdk/agents">
    `invoke()` signature, `AgentResult` shape, adapter polling semantics.
  </Card>

  <Card title="Build runbooks" icon="code" href="/workflows/runbooks/overview">
    The runbook-side of invoking an agent inside a `@runbook.step`.
  </Card>
</CardGroup>