Skip to main content

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.

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:
KindURI formNotes
claude_managedanthropic://agents/<anthropic-agent-id>Production today
copilot_agentcopilot://agents/<copilot-agent-id>Future

​
3. Reference from a runbook step

From inside any @ui_step method, call ntro.workflow.agents.invoke: 
from ntro.workflow.agents import invoke

@ui_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

ResourceAPICLIMCP
CreatePOST /workspace/registry/agentsntro agent create --path …ntro_agent_create
ListGET /workspace/registry/agentsntro agent listntro_agent_list
GetGET /workspace/registry/agents/:idntro agent get <id>ntro_agent_get
DeleteDELETE /workspace/registry/agents/:idntro agent delete <id>ntro_agent_delete
Create versionPOST /workspace/registry/agents/:id/versionsntro agent create-versionntro_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 @ui_step.