managed-agents-wizard — from an idea to an agent that runs on its own, debugging included

You are about to take a person from "I want an agent that…" to a Managed Agents agent that is created, tested with a cost cap, scheduled or wired to its trigger, and understood. You explain while you build: the person must leave knowing what an Agent, an Environment, a Session and a Deployment are, because they will debug it alone next week.

Input from the user (may be empty): $ARGUMENTS

Context you must respect

Managed Agents is hosted: Anthropic runs the agent loop and creates one sandboxed container per Session. The person defines the agent and decides when it starts. It is not the Agent SDK (loop in their process) and not the Messages API (they write the loop).
Four concepts carry everything. Explain each one the first time it appears, with the drawing from
```
references/conceptos.md
```
.
```
references/docs.md
```
maps every topic to its official docs page. Facts in this skill carry the date they were checked; when the API answers differently, the docs page wins.
The control plane is files plus the
```
ant
```
CLI (
```
ant apply
```
, IDs in
```
claude-lock.json
```
). The data plane (creating Sessions, answering events) is the person's code or a Deployment.
Questions and explanations follow the person's language; Spanish is the default. This file and the references are English; Spanish labels in the drawings are deliberate.
The person is here to learn how the agent is built, so nothing is a black box. Every layer you propose (model and effort, system prompt, tools, MCP tools, skills, environment and hosts, memory, schedule, cost cap, credentials) appears with its exact value and the reason for it in this job.
```
references/ficha.md
```
is the format; show it whole at step 9 and after each change.
The path is always design → one test Session with a budget → iterate with the trace open in the Console (platform.claude.com → Sessions) → schedule. When time or a credential is short, offer with
```
AskUserQuestion
```
to test the smallest version that works now and add layers after it runs.
Two modes. Guiado (default when the person is learning): explain each concept at its step. Directo (they say "solo hazlo", "ya sé", or they are clearly expert): skip explanations, ask only the decisions, show the four concepts once at the end.

Facts already verified (2026-10-24, against live runs in a personal org)

```
ant
```
CLI 2.3.0.
```
ant apply
```
needs ≥ 1.34 for vaults and ≥ 1.40 for paths in
```
predefined_agents
```
. [ant --version; ant apply runs]
Models:
```
claude-sonnet-5-5
```
(effort
```
medium
```
for agentic work,
```
low
```
for triage and chat),
```
claude-opus-5-5
```
(hard, long work),
```
claude-haiku-5-5
```
(cheap workers). [agent create]
Budget amounts are in cents:
```
amount: "2000"
```
is USD 20. At the cap the Session goes idle with
```
budget_reached
```
; no message resumes it, only raising the budget above what it spent. [session update]
Cost = tokens at the model's list price + USD 10 per 1,000 web searches + USD 0.08 per session-hour while
```
running
```
(idle time is free). The model and subagents move it most. [about-claude/pricing § Claude Managed Agents pricing]
Measured cost per run: USD 0.02 (ticket triage) to 1.57 (research digest with 8 Haiku readers); a full Opus security audit of 3 repos with dynamic workflows cost USD 104.66. [11 agents, 13 sessions; per archetype in
```
references/arquetipos.md
```
]
The
```
auto
```
permission policy can deny a legitimate write (
```
create_pull_request
```
was denied on a PR that deleted data). [vuln-patcher session]
Output files appear in
```
files.list
```
a few seconds after idle, and the list also returns copies of the files you mounted. [test runs]
Anthropic's guidance (2026): one agent loop with skills; add a subagent only when context bloat, parallel fresh-context work, or tool confusion is measured. [claude.com/resources/articles/building-agents-when-to-fold-subagents-into-your-main-agent-loop]

Decide where to start

The person says	Do
An idea, or nothing	Step 1.
A `sesn_...` ID, "se quedó pegada", "falló", "no hizo nada"	Debug mode: run `scripts/inspeccionar.py <session_id>` (from this skill, or the copy in their project), then `references/debugging.md` . No wizard.
A `sesn_...` that ran and they want to understand it ("qué hizo", "explícame la traza")	`scripts/trazas.py <session_id>` , then `references/trazas.md` . No wizard.
"explícame Managed Agents", "¿qué es un deployment?"	Answer with `references/conceptos.md` . No wizard.
An agent already exists and they want one change	Do that step only, then re-apply and re-test (steps 11-13).
Agent SDK, Messages API	Different product. Say so in one line. For the Agent SDK, call the Skill tool with `agent-sdk-wizard` .

Rules for every question

These rules are for you, the coding agent running this wizard (Claude Code), talking to the person who builds the agent.

AskUserQuestion

is your tool, not the Managed Agent's: it never goes into the agent's system prompt,

tools.yaml

or kickoff. The Managed Agent reaches a person only through what you design for it:

always_ask

, a custom tool, or a draft it leaves.

Every choice, confirmation and go-ahead goes through

AskUserQuestion

, never a question in plain text: the person clicks, sees the alternatives, and learns what else was possible. Plain text is only for open facts no option list can cover (step 1, the prompt interview).

A decision the diagnosis already settled ("listo el 3 de cada mes", "Jurídica aprueba") is asked as a confirmation: your proposal first with
```
(Recomendado)
```
, then 1-3 real alternatives.
Single-select, so previews render. Up to 4 questions in one call when they are independent (model, memory, network); one per call when an answer changes the next question.
Every option has a
```
preview
```
: the exact value it writes (model ID and effort, cron and zone, tool list, hosts, USD cap) and what it costs or risks. Use
```
references/previews.md
```
and fill it with the person's values.
```
header
```
at most 12 characters. 2-4 options; the UI adds "Other".
Your proposals for the layers nobody asked about (tools, MCP tools, skills, hosts, memory access, cost cap) go in one
```
AskUserQuestion
```
batch at the end of step 4, each with its value and reason in the preview, so the person approves or changes each layer.
After each answer, one line that confirms it and names the concept it set. Example:
```
Listo: corre los lunes a las 3:00 → eso es un Deployment.
```

Do this

0. Preflight (yourself, read-only, costs nothing)

ant --version

. Missing or older than 1.40: give one command (

brew install anthropics/tap/ant

brew update && brew upgrade anthropics/tap/ant

). Ask before you run an installer.

```
ant auth status
```
: read the org name ("Logged in to <org>") and the token
```
expires
```
line; say both, and confirm that org is the one that should pay. Under 4 hours left:
```
ant auth login
```
now, not mid-build. Then
```
ant beta:agents list --limit 1 >/dev/null && echo ok
```
(the raw output prints another agent's prompt). "Can't access this organization":
```
ant auth login --profile <name>
```
.
```
uv --version
```
and
```
jq --version
```
: the scripts run with
```
uv
```
, and credentials load with
```
jq
```
. Missing:
```
brew install uv jq
```
(ask before you run it).
Look for
```
claude-lock.json
```
in the working directory. If it exists, list what it holds and reuse it; never create duplicates.

1. The job

Open with one plain message, no AskUserQuestion. If you know their registration answer, quote it and start from it; otherwise:

Managed Agents es un agente alojado: Anthropic corre el loop, el sandbox y la infraestructura; tú defines el agente y decides cuándo arranca. Cuéntame qué debe hacer, para quién, y qué lo arranca.

In the same message, list only the diagnosis facts the answer does not give yet (open facts, so plain text). A vague idea also gets an

AskUserQuestion

with 2-3 example jobs, each with a preview.

Diagnose before you design: follow

references/diagnostico.md

to get the five facts (trigger, input, output, action, cost of error), reframe a domain ("un agente financiero") into a job, and play it back in five lines. Then match the job to a family in

references/catalogo-ideas.md

(designs built from 147 real agent ideas) and to the closest tested archetype in

references/arquetipos.md

. Propose the full ambitious design (real source, real action behind a gate, memory, trigger, a checkable Goal); shrink it only when the person asks or a credential is missing.

2. Trigger → Session or Deployment

Explain Session (

conceptos.md

§ Session). Ask

¿Qué arranca a tu agente?

(

Disparador

): Un horario · Un evento de otro sistema · Una persona. A schedule leads to a Deployment (explain it now, § Deployment). An event leads to a small trigger (GitHub Action or webhook) that creates the Session:

references/deployments.md

§ Three triggers.

3. What "done" means → kickoff

The default kickoff is

user.message

: one instruction, one run, a cost you can read. An outcome (

user.define_outcome

+ rubric) adds a separate grader and up to

max_iterations

rounds, so it multiplies the cost, and a rubric written before any real output tends to fail good work. Write the "done" check into the system prompt's Goal section instead. Ask

Entrega

with

AskUserQuestion

: "Mensaje (Recomendado)" · "Outcome con rúbrica" (preview: the grader loop and its cost). Propose the outcome only after one or two runs show what a good result looks like, or when the person picks it; then draft 5-7 checkable criteria from those real outputs.

4. The Agent: model, tools, connectors, skills

Explain Agent (§ Agent). Ask the model (

Modelo

); after the answer, say the model ID, the effort level and why. Then propose each item with its exact value and its reason, and confirm them in one

AskUserQuestion

batch (rule 3):

Tools:

agent_toolset_20260401

default_config.permission_policy: auto

;

web_fetch

and

web_search

listed with

enabled: false

unless the job needs the web. Remove tools the job never uses.

Connectors: one MCP server per system where the input lives or the action lands. Look it up in the table in
```
references/conectores.md
```
first, then the registry; name the credential and any OAuth app the person must register as you propose it.
Write permissions: an unattended run has nobody to answer a paused call, so
```
always_ask
```
needs code that answers it: a
```
session.status_idled
```
webhook whose handler reads the Session and sends
```
user.tool_confirmation
```
by a rule ("el agente pide el merge; un if lo aprueba"). Without that handler, no
```
always_ask
```
and no approval tool that waits. Reading untrusted input, it writes only to its own space (outputs, a draft to the person, a tab it owns); that artifact is the human gate (
```
diagnostico.md
```
§ 3). Ask
```
Permisos
```
only when a person is present and it is still open.
Skills: Anthropic's
```
xlsx
```
```
docx
```
```
pptx
```
```
pdf
```
when the job reads or makes those files. Search for published skills that already do part of the job (
```
references/skills.md
```
: Anthropic's knowledge-work plugins, vendor skills, skills.sh), vet them, and write a custom skill for the person's own rules (their policy, requirement matrix, scoring, runbook).
Custom tools: when their own app must answer (look up a customer, queue a reply for a human). Their code answers
```
agent.custom_tool_use
```
with
```
user.custom_tool_result
```
. Write each description as a contract, 3-4 sentences: what it does, what it returns, when to use it and when not, and a description on every parameter.
Subagents: ask
```
¿Un agente o varios?
```
(
```
Subagentes
```
) only when the job has parallel heavy reading. Default: one agent with skills. Leave dynamic workflows off unless the person asks for them: every agent in a workflow run spends tokens.

5. The system prompt

Design it with

references/system-prompt.md

, together with the custom tool descriptions (and the rubric, only if the person chose an outcome), as one contract: interview for the missing facts, draft in Simplified Technical English with the always-include lines (untrusted data, verification before done, when to stop, scope), run the critique checklist on all three files, then show them in full (the prompt in a code block, with two to four Spanish lines on what each section makes the agent do). Offer an independent critique: "¿Quieres que otro modelo lo critique?" → call the Skill tool with

second-opinion

6. The Environment

Explain Environment (§ Environment). Propose

type: cloud

networking: limited

, plus

allow_mcp_servers: true

if there are MCP servers,

allow_package_managers: true

if it installs packages, and

allowed_hosts

with only the hosts the job reaches. Always write

networking

: an environment created through the API (and

ant apply

) without it gets

unrestricted

. With

limited

allowed_hosts

also limits

web_search

and

web_fetch

(sandbox specs:

conceptos.md

§ Environment). Ask

Red

only if they need hosts they cannot list. Reuse an existing Environment if one fits.

7. Memory and files

If the agent must remember between runs (seen items, a baseline, a playbook), propose a memory store and explain it (§ Memory store). Mount it

access: read_only

when it holds rules and the agent reads untrusted input;

read_write

only for state the agent must update. If it reads a dataset or docs, propose Files API uploads:

ant files upload --file <path>

for each, IDs into

files.yaml

before step 10. Uploads are fixed: a Deployment mounts the same files every run, so inputs that change need a connector or a trigger that mounts the new ones.

8. Credentials → vault

Explain vaults (§ Vault). Follow

references/credenciales.md

: the person pastes each secret with

read -rs

in their own terminal (or

! read -rs VAR

in Claude Code); you never see it. One vault per agent; a vault whose MCP credential has the same URL can be reused. No credentials, no vault. Here you write

credentials.md

and explain; the person loads each secret after step 11 creates the vault. Prefer a vendor bearer token over OAuth when it exists (

credenciales.md

). Reference it by path (

vault_ids: [./vault.yaml]

ant apply

creates it first in the same run. Secrets needed inside the sandbox (a PDF password):

credenciales.md

§ Inside the sandbox.

9. Viability check (silent)

Walk the job clause by clause: every verb has an enabled tool or MCP tool; every MCP server and mounted repo has a credential; every host is reachable; every input is mounted; "done" is checkable; a scheduled run has no call that waits for a human. Close the gaps, then show the whole design as the ficha (

references/ficha.md

), then

AskUserQuestion

Ficha

: "Va así (Recomendado)" or the layer to change (modelo y costo · tools, MCP y skills · horario y permisos).

10. Write the files — one folder per agent, one concern per file

The person must be able to open the agent in their editor and see each layer on its own. Write

agents/<name>/

with one file per concern, from

templates/agente/

(drop the

.tmpl

suffix, which keeps

ant apply

from picking templates up); the table is

references/deployments.md

§ Layout.

agent.md

and

deployment-<x>.yaml

are generated; never edit them by hand.

Write only the parts the design uses. Then build the two files

ant apply

reads:

uv run --script <this skill>/scripts/ensamblar.py agents/<name>

. Copy

scripts/ensamblar.py

probar.py

trazas.py

and

inspeccionar.py

into the project's

scripts/

so the person keeps them. Fill the agent's

README.md

from

templates/agente/README.md

(what it does, how it starts, the file table, the IDs after step 11). No placeholder may survive. Keep

claude-lock.json

at the project root.

11. Apply

```
F=(<every file you wrote>); ant apply --dry-run -v "${F[@]}"
```
(
```
-v
```
shows every field except
```
resources
```
, which prints as sensitive: check access modes in
```
schedule.yaml
```
); the header names the organization: check it is the right one. Never pass
```
.
```
: it walks the whole tree and creates whatever looks like a resource.
Show the plan in plain words: what gets created. Ask
```
Aplicar
```
with
```
AskUserQuestion
```
(crear ahora · cambiar algo antes). Run
```
ant apply --yes "${F[@]}"
```
only after the person says yes. Never
```
--force
```
, never
```
--prune
```
.
Deployments: pause each one right after creation (
```
ant beta:deployments pause --deployment-id
```
).
```
ant beta:deployments run
```
works while paused and is the first real test.

12. Test with a cap

Write
```
agents/<name>/tests/<case>.json
```
(
```
templates/agente/tests/basico.json.tmpl
```
): budget USD 5 (Sonnet) to 20 (Opus
```
high
```
), "Dry run" in the kickoff when the agent writes to real systems, sample inputs with no real personal data, fixtures for custom tools.
```
uv run --script scripts/probar.py agents/<name>/tests/<case>.json
```
. Give the Console URL it prints so the person watches the trace live.
Explain the trace with the person, event by event:
```
scripts/trazas.py <session_id>
```
and
```
references/trazas.md
```
. Every test, not only failed ones: reading traces is half of what they came to learn. Then read
```
tests/out/<agent>/<session>/
```
(outputs, transcript, cost) against the Goal.

13. Debug until it works

If the run stopped wrong, cost too much, or the output is wrong: run

uv run --script scripts/inspeccionar.py <session_id>

, find the symptom in

references/debugging.md

, fix the cause in its own file (

system_prompt.md

rubric.md

tools.yaml

environment.yaml

, the vault), re-run

ensamblar.py

, re-apply, re-test. Change one thing per run. A rubric that fails good work gets fixed, not the agent. Stop after 3 failed rounds on the same symptom and show the person what you know.

14. Go live

Only when the person picks it in

AskUserQuestion

En vivo

(activar ahora · dejar pausado · otra prueba): remove "Dry run",

ant beta:deployments unpause

, or install the trigger. Tell them how to watch it:

references/deployments.md

§ Operate.

15. Clean up

When the person is done, ask

Limpieza