> ## 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. # Claude Managed Agents > Bring an Anthropic-hosted Managed Agent into a runbook step. Build the agent on Anthropic Console, register the reference with Ntropii, invoke from inside a @runbook.step. [Claude Managed Agents](https://platform.claude.com/docs/managed-agents) are Anthropic-hosted agents with bundled `bash` / `write` / `read` tooling, Skills (e.g. the `docx` skill for Word document generation), MCP server bindings authenticated via Anthropic Vaults, and Environments for custom pip packages. Ntropii integrates with them via `ntro.workflow.agents.invoke` from inside a runbook step. This page is the end-to-end walkthrough for the production adapter. The working reference implementation lives in [`claude-managed-agents`](https://github.com/ntropii-com/claude-managed-agents) on GitHub. ## When to use Reach for a Managed Agent when a runbook step needs LLM-driven artefact generation that doesn't fit the deterministic capabilities surface: * Multi-section narrative documents (auditor handover .docx, NAV pack PDF, year-end letter) * Open-ended document drafting where the structure varies by period * Tasks where the agent benefits from `bash` + `python-docx` + the `docx` Skill working together in a sandbox For structured extraction, classification, and quality checks, prefer [`ntro.ai.extract`](/sdk/capabilities/private-ai) and [`ntro.ai.check`](/sdk/capabilities/quality-checks). They're cheaper, faster, and observable through the same Reasoning tab. ## Lifecycle ``` ┌────────────────────────────┐ │ 1. Build on Anthropic │ Anthropic Console — Agents, Environments, Vaults │ Console │ └────────────────────────────┘ ↓ ┌────────────────────────────┐ │ 2. Register with Ntropii │ ntro agent create --path anthropic://agents/ └────────────────────────────┘ ↓ ┌────────────────────────────┐ │ 3. Store API key in Vault │ Plaintext shown once at registration └────────────────────────────┘ ↓ ┌────────────────────────────┐ │ 4. Reference from runbook │ ntro.workflow.agents.invoke(agent_id, …) └────────────────────────────┘ ``` ### 1. Build on Anthropic Console Author the agent in [Anthropic Console](https://platform.claude.com/workspaces/default/agents). The shape of an agent.yaml that registers cleanly with Ntropii: ```yaml theme={null} name: audit-handover model: claude-sonnet-4-6 description: | Produces an auditor handover .docx for a completed NAV close. system: | # System message — what the agent is + how it should behave. # See claude-managed-agents/agents/audit-handover/system-prompt.md # for the production reference. tools: - type: bash - type: write - type: read # mcp_toolset binds the Ntropii MCP server. Vault-injected auth at # session start; no env-var-based auth. - type: mcp_toolset mcp_server_name: ntropii mcp_servers: - type: url name: ntropii url: https://mcp.ntropii.com/mcp # Streamable HTTP MCP path skills: # Anthropic's pre-built docx skill — pairs well with python-docx # for richer document authoring. - skill_id: docx type: anthropic version: latest ``` Three platform objects to set up: | Object | Carries | Notes | | --------------- | ------------------------------------------------------------- | ---------------------------------------------- | | **Agent** | `name`, `model`, `system`, `tools`, `mcp_servers`, `skills` | Per-agent definition | | **Environment** | pip packages (`python-docx`, `ntro`, …), networking, metadata | Reusable across agents | | **Vault** | API keys (Ntropii agent API key) | Injected into MCP server auth at session start | **No env vars on Managed Agents.** Auth flows through Vault → MCP server only. ### 2. Register with Ntropii Once the agent exists in Anthropic Console and you have its native id (e.g. `agent_01SxpziMunFrUbnAYkGB5Hu3`): ```bash theme={null} ntro agent create \ --path anthropic://agents/agent_01SxpziMunFrUbnAYkGB5Hu3 \ --tenant byng \ --name audit-handover ``` The CLI returns the Ntropii agent UUID, the resolved `external_ref`, and an **API key plaintext** shown once. ### 3. Store the API key in an Anthropic Vault Create a Vault on Anthropic, paste the plaintext API key, and reference the Vault from the agent. The Ntropii MCP server uses this key to authenticate the agent's callbacks (e.g. `ntro_task_get`). ### 4. Reference from a runbook step From any `@runbook.step` method: ```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 = { "entity": {"slug": ctx.entity_slug, "currency": "GBP"}, "period": ctx.period, "tb": tb_dict, "journal_proposal": proposal_dict, "documents": [...], } 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 ``` The agent receives `input` as its kickoff user message (JSON-serialised for dicts), runs to terminal status, and emits any output files. The Ntropii adapter handles the rest. ## File output The agent writes generated files to `/mnt/session/outputs/` — Anthropic's runtime auto-promotes that path into the session's file list. The Ntropii adapter: 1. Polls the Anthropic Sessions API until the session is `terminated`. 2. Lists session files via `GET /v1/files?scope_id=` (with backoff for the index-eventual-consistency race). 3. Downloads each file's bytes. 4. Persists to `ingest.submitted_documents` with `source = 'agent_output:'`. The persisted file is then accessible from the task UI like any other document — including via the audit-handover step's download link. ## Reference implementation The [`claude-managed-agents`](https://github.com/ntropii-com/claude-managed-agents) repo on GitHub contains the production-ready definitions and integration spec: ``` claude-managed-agents/ ├── README.md ├── docs/ │ ├── integration-spec.md │ └── sdk-reference.md └── agents/ └── audit-handover/ ├── agent.yaml ├── system-prompt.md ├── tools.md ├── handover-template.md └── README.md ``` Use `audit-handover` as the template for your own Managed Agents. ## Related Generic registration flow, lifecycle, and reference table. `invoke()` signature, `AgentResult` shape, adapter polling + backoff semantics. The runbook-side of invoking an agent inside a `@runbook.step`. Anthropic's reference for Agents, Environments, Vaults, and Sessions.