Claude Managed Agents: Setup, ant apply and SDK Trade-offs

Claude Managed Agents is Anthropic's hosted agent harness, in beta at the time of writing. It runs the agent loop, the sandbox and the session log on Anthropic's side, and bills runtime at $0.08 per session-hour on top of tokens, with idle time free. You send events and stream results instead of maintaining that layer yourself. This post is a documented walkthrough of what the service hosts, how the ant apply file-based workflow behaves, and where the Agent SDK is still the better call.

Note: Managed Agents is a beta service at the time of writing. Treat everything here accordingly.

What Claude Managed Agents Hosts for You

The short version: Anthropic runs the agent harness, the compute sandbox, and the session log. You send events and stream results back over HTTP. That's it. You don't manage the container lifecycle, the tool execution environment, or the retry logic for transient failures.

More specifically, here's what lands on Anthropic's side of the fence:

• The agent loop. Claude decides when to call a tool, processes the result, and iterates without you writing the orchestration.
• Built-in tools. Bash, file operations, web search, all accessible through the agent_toolset_20260401 tool type. You don't wire these up yourself.
• Per-session sandboxes. Each session gets its own isolated execution environment. No cross-session bleed.
• Durable session logs. If your application drops the stream, the session hasn't vanished. You reconnect and catch up.
• MCP integration. Custom tools attach as MCP servers. Claude triggers the tool; your service returns results over the protocol. Nothing to bundle into your deploy.
• Prompt caching. Built in at the platform level, which matters once your system prompts get long.

What you keep on your side: the agent definition, your MCP server implementations, and any business logic that decides when to start or stop a session. That's a much smaller surface to own than a full harness.

Hatchworks covers the infrastructure split clearly: inference can start before a container is provisioned, which often nets out faster for cold-start agents even though every tool call crosses a service boundary.

When to Choose Managed Agents, the Agent SDK, or Claude Code

The confusion I see most often is people treating these three as interchangeable. They're not.

Claude Code is a terminal tool. Great for a developer running tasks locally. Not something you embed in a product.

The [Agent SDK](/blog/claude-agent-sdk-guide-2026/) runs the agent loop inside your own process, on your own infrastructure. Direct filesystem access, private network connectivity, full control over the execution environment. You pick the SDK when you need things like local file writes without a service boundary, existing infrastructure you've already paid for, or multi-provider flexibility at the model level (though you're locked to Claude either way with the SDK for now).

Managed Agents is the hosted answer. You get durable sessions, sandboxed compute, and built-in observability without building any of it. The cost model is per session-hour, not per token alone, so it rewards short focused sessions and punishes long idle ones.

Here's the decision table:

One thing worth flagging: as noted in the SDK guide on hidekazu-konishi.com, a common path is prototyping locally with the SDK and migrating to Managed Agents once you want hosted sandboxes you'd rather not operate.

If your specific challenge is building the full agentic product around this, our agentic engineering work might save you a few wrong turns.

Create One Agent and Inspect a Session

This is a documented walkthrough, not a verified production run. I'm describing the procedure from the official documentation; call any code here illustrative until you've run it against your own key.

Getting to a running agent takes four steps.

1. Create an agent definition. This is where you describe what the agent can do: which built-in tools it has access to, which MCP servers it can call, and what its system prompt is.
2. Create an execution environment. The platform provisions a sandbox scoped to your agent definition.
3. Start a session. You send a start event with your user's input. The session ID comes back immediately.
4. Stream events. Tool calls, intermediate results, and the final response all arrive on the stream. You handle them in your application.

Across the seven official SDKs (Python, TypeScript, Go, Java, C#, Ruby, PHP), the shape of that flow is consistent even if the syntax differs. The agent_toolset_20260401 tool type is what unlocks the full built-in toolset in a single declaration. You don't enumerate bash, file ops, and web search individually.

Once a session is running, you can inspect it through the session log endpoint. This is where the durability benefit shows up concretely. Drop the stream, reconnect, and the log replays from where you left off. For long-running tasks where the client might disconnect, that matters a lot.

Manage Resources with ant apply and claude-lock.json

The ant CLI is a separate tool from the SDK itself. Install it via Homebrew. It provides a file-based workflow for declaring your agent resources (agents, environments, MCP server registrations) in config files, then applying them to the platform.

The ant apply documentation describes the core command:

ant apply

Before you touch production, run the dry-run flag:

ant apply --dry-run

This previews what the apply would do. Important caveat from the official docs: --dry-run can exit 0 even on a plan that would be blocked at apply time. Don't treat a clean dry-run as a guarantee the full apply will succeed. Verify the actual apply in a staging environment first.

The claude-lock.json file is the lockfile that records the current state of your deployed resources. Think of it like a package-lock.json , it pins resource versions and prevents drift between what you declared and what the platform is running. After any ant apply, the lockfile updates to reflect the new state. Commit it. Treat changes to it as meaningful in code review.

One serialisation point that trips people up: partial applies. If ant apply fails partway through, some resources will be in the new state and some won't. The lockfile will reflect the partial update. Before running ant apply again, check the lockfile against what actually deployed, reconcile manually if needed, then re-run. Running a second apply over a broken partial state without checking first can leave resources in a confused intermediate condition.

This is different from tools like Terraform that have a separate plan step in the CLI. There is no ant plan. The dry-run is what you have for preview. Design your CI accordingly.

Review Changes in CI and Handle Partial Failures

For teams running multiple developers against the same Managed Agents environment, applying changes from CI rather than local machines is strongly recommended. Otherwise you get race conditions on the lockfile.

Here's the workflow I'd suggest:

1. PR opens. CI runs ant apply --dry-run and posts the output as a PR comment.
2. Reviewer checks the diff, including any lockfile changes.
3. On merge to main, CI runs ant apply against the staging environment.
4. Promote to production only after staging apply succeeds and sessions behave correctly.

The serialisation requirement is the main operational constraint. You cannot run two ant apply calls in parallel against the same environment. If your CI system can queue multiple merges rapidly, enforce a lock at the pipeline level (most CI platforms have a concurrency group setting for exactly this).

For partial failure handling, the checklist looks like this:

• Check the lockfile immediately after a failed apply. Note which resources updated and which didn't.
• Don't re-run ant apply blindly. Read the error first.
• If the partial state is safe to leave while you investigate, leave it. If resources are in a broken intermediate state, you may need to roll back manually before re-applying.
• Once resolved, run ant apply --dry-run again before the full apply to confirm the plan looks right.

Because --dry-run can exit 0 on a blocked plan, don't skip the review step even if the dry-run looks clean.

Beta Limitations, Costs and a Deployment Checklist

Managed Agents is a beta service. That designation matters for anything production-critical. Features can change. Pricing can change. Availability guarantees in beta are not the same as GA.

Costs. The published rate is $0.08 per session-hour, metered only while a session is running (idle time is not billed), with tokens charged on top at standard model rates. That makes it relatively predictable for short, task-focused sessions. For long-running sessions with substantial tool use, you'll want to monitor session duration actively. The vibecodingacademy guide puts this in context: cost-competitiveness depends on the engineering time you'd spend building equivalent self-managed infrastructure, which is real and often underestimated.

Current constraints in beta:

• Custom tools route through MCP servers, not in-process functions. If your custom tooling is tightly coupled to your application's runtime, you'll need to extract it into an MCP server first.
• Session observability is through the session log endpoint. There's no built-in dashboard equivalent to what you'd build yourself on top of the SDK.
• ant apply partial failure semantics require manual reconciliation. There's no automatic rollback.
• Serialised applies mean pipeline throughput is limited by apply duration.

Pre-deployment checklist:

1. Agent definition reviewed and system prompt finalised
2. MCP servers registered and tested independently before wiring to the agent
3. claude-lock.json committed and treated as a reviewed artefact
4. ant apply --dry-run output reviewed by a second person before any production apply
5. Session duration monitoring in place (watch for unexpectedly long sessions)
6. Partial-failure recovery procedure documented for your team
7. Staging environment validated before production promotion
8. Budget alerts configured at the account level given beta pricing could change

One last thing on the build-vs-buy question. The Agent SDK gives you more control, yes. But control means ownership. As ksred notes about the SDK, agentic sessions that do substantial work can get expensive quickly, and failure recovery is entirely your design in the SDK. Managed Agents trades some of that control for durable sessions and infrastructure you don't operate. Neither is wrong. The choice depends on what your team can actually maintain.

FAQ

Does Managed Agents work with any Claude model, or is it restricted to specific versions?

The official documentation does not list specific model restrictions within Managed Agents at the time of writing. Given the beta status, model availability may shift. Check the overview page directly before committing to a specific model version in a production agent definition.

Can I run the same agent definition locally with the SDK for testing before deploying to Managed Agents?

Not directly. The SDK runs the loop in your own process against your local environment; Managed Agents runs it in Anthropic's sandbox. You can prototype the agent behaviour with the SDK, but the execution context is different enough that you should test the actual Managed Agents deployment in a staging environment before promoting to production.

How does Managed Agents handle authentication for MCP servers that need credentials?

The official documentation describes custom tools as connecting through MCP servers, with Claude triggering the tool and your service returning results. Credential handling for those MCP servers is your responsibility at the server level. Managed Agents does not inject credentials into MCP calls on your behalf based on current documentation.

Is there a way to limit spending per session in Managed Agents the way the SDK's max_budget_usd parameter works?

The SDK's max_budget_usd parameter on query() is an SDK-level control that doesn't translate directly to the Managed Agents REST API. Budget controls within Managed Agents are not documented at the same granularity in the current beta. Account-level spend alerts are the safest backstop right now.

What happens to a running session if the region or sandbox experiences an outage?

Durable session logs are a core design feature of Managed Agents, but the specifics of session recovery across an infrastructure outage are not detailed in the current beta documentation. Given the beta designation, treat the durability guarantee as best-effort until Anthropic publishes an SLA for the service.

The honest summary: Managed Agents is a genuinely useful service that eliminates a large class of infrastructure work. The ant apply workflow is straightforward once you understand the dry-run caveats and the serialisation requirement. But it's beta, the partial-failure semantics require care, and it's not the right answer if you need local filesystem access or already have agent infrastructure you're happy with. Start with the decision table, pick based on what your team actually wants to own, and treat the lockfile as seriously as you'd treat any other state file.