Register agents

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:

Claude Managed Agents

Anthropic-hosted agents with Vault auth + MCP servers + Skills. Production today.

Copilot Agents

GitHub / Microsoft Copilot agents. Coming soon.

2. Register with Ntropii

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

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:

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:

Lists session files via the host platform’s API.
Downloads each file’s bytes.
Persists to the tenant’s ingest.submitted_documents with source = 'agent_output:<ntropii-agent-id>'.
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 for the invoke API, AgentResult shape, and adapter design.

Claude Managed Agents

End-to-end walkthrough for the Anthropic Managed Agents adapter (production today).

Copilot Agents

Coming soon — GitHub / Microsoft Copilot adapter.

ntro.workflow.agents reference

invoke() signature, AgentResult shape, adapter polling semantics.

Build runbooks

The runbook-side of invoking an agent inside a @runbook.step.

Get Started

Tooling

Building workflows

Ntro SDK

API Reference

Deploy & Run

Register agents

Why register?

Lifecycle

1. Build on the host platform

Claude Managed Agents

Copilot Agents

2. Register with Ntropii

3. Reference from a runbook step

File passback

Reference

Claude Managed Agents

Copilot Agents

ntro.workflow.agents reference

Build runbooks

​Why register?

​Lifecycle

​1. Build on the host platform

Claude Managed Agents

Copilot Agents

​2. Register with Ntropii

​3. Reference from a runbook step

​File passback

​Reference

​Related

Claude Managed Agents

Copilot Agents

ntro.workflow.agents reference

Build runbooks

Why register?

Lifecycle

1. Build on the host platform

2. Register with Ntropii

3. Reference from a runbook step

File passback

Reference

Related