Claude Managed Agents API Migration Guide

Anthropic's July 22 Claude Platform release notes add five pieces that fit one production story: model effort on agent definitions, environment and memory-store webhooks, up to 50 initial_events on session creation, optional optimistic-concurrency versions on agent updates, and event deltas on per-thread streams. The changes can remove requests and polling from an integration, but they do not make webhooks durable, deltas authoritative, or concurrent updates safe by default.

This is a Managed Agents API migration guide, not a general Claude terminal tutorial. Use the Claude Platform ant CLI guide when you need installation, authentication, profiles, request-body syntax, or shell transforms. Here, the job is to change a production session control plane without losing events, overwriting an agent definition, or mixing incompatible memory headers.

Sources were checked on July 23, 2026 against Anthropic's release notes and current Managed Agents documentation. AgentPedia did not execute authenticated Managed Agents calls, so the request shapes below are documentation-derived examples and the regression suite is part of the required rollout gate.

What changed on July 22

The release does not require every team to rewrite its client. It provides narrower ways to start work, observe resource lifecycles, control model effort, coordinate updates, and preview child-agent output.

Anthropic still describes Claude Managed Agents as a beta product, enabled by default for API accounts, under managed-agents-2026-04-01. The overview distinguishes Anthropic-managed cloud sandboxes from self-hosted environments and says stateful Managed Agents are not currently eligible for Zero Data Retention or HIPAA BAA coverage. Product availability, API availability, deployment fit, and compliance eligibility are therefore separate decisions.

The July 22 release entry does not announce a Managed Agents pricing change. That wording is deliberately narrow: absence from one release note is not a pricing guarantee, and teams should continue using current contract and pricing material for cost forecasts.

Production architecture after the update

The cleaner design separates command, event, and reconciliation paths:

API client
  ├─ POST /v1/sessions + initial_events ───────> session starts running
  ├─ SSE session stream ──────────────────────> authoritative persisted events
  ├─ SSE child-thread stream + event_deltas[] ─> best-effort live preview
  └─ signed webhook receiver ─────────────────> lifecycle wake-up signal
                                                   │
                                                   v
reconciliation worker <──── GET resource by ID / list history / rebuild state
        │
        ├─ idempotency by webhook event.id
        ├─ current agent version in the write path
        └─ separate beta header policy for memory-store endpoints

This layout follows Anthropic's current contracts:

• The session guide says seeded events are validated and persisted before the create response returns.
• The streaming guide treats buffered agent.message events as authoritative and deltas as best-effort previews.
• The webhook guide sends an event type and resource ID rather than the full resource, so the handler must fetch current state.
• The same webhook guide warns that duplicates can occur, ordering is not guaranteed, delivery is attempted at most three times, and exhausted events are dropped. Webhooks wake the reconciler; they are not the reconciler's database.

The practical reduction is bounded. initial_events can remove one request when starting a session. Webhooks can remove continuous lifecycle polling while the endpoint is healthy. Deltas can remove the need to wait for a full subagent message before showing progress. Every path still needs a fetch, persisted event, or periodic repair process as its source of truth.

Start sessions with initial events

Previously, the ordinary flow was create the session, receive its ID, then send the first user event. initial_events folds those operations into the create request:

curl --fail-with-body -sS https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --json "$(jq -n \
    --arg agent "$AGENT_ID" \
    --arg env "$ENVIRONMENT_ID" \
    '{
      agent: $agent,
      environment_id: $env,
      initial_events: [{
        type: "user.message",
        content: [{type: "text", text: "Inspect the repository and report test failures."}]
      }]
    }')"

According to the session documentation, a non-empty list creates the session directly in running; an empty list behaves like omission. Events are processed and persisted in list order with server-assigned IDs, but they are not echoed in the create response. Read the session event list when the client needs those IDs or must verify the stored content.

The validation boundary matters more than the round-trip saving:

• Only user.message and user.define_outcome are accepted, with at most 50 total events.
• A session's list does not accept system.message, user.interrupt, tool confirmations, tool results, or custom-tool results.
• Validation is all-or-nothing: if one event is invalid, no session is created.
• More than one user.define_outcome, an outcome without a rubric, more than 100 file-sourced document blocks across the list, or an oversized request can fail the create call under the documented limits.

Use a request-level idempotency record in your application before retrying an ambiguous timeout. The documentation establishes atomic validation, but it does not say that retrying an unknown-outcome create request with the same body deduplicates session creation. Store the attempted operation, inspect your own response log, and reconcile created sessions before issuing a blind retry.

Set model effort on the agent

The agent setup documentation accepts the string levels low, medium, high, xhigh, and max, or equivalent typed objects, inside the agent's model configuration. Availability depends on the selected model—Anthropic's API reference notes that some models do not support xhigh—so validate the level against the model used by the agent:

{
  "name": "Repository reviewer",
  "model": {
    "id": "claude-opus-4-8",
    "effort": "high"
  }
}

Effort belongs to the persisted agent, not a per-session model override. If one service needs a high-effort reviewer and another needs a lower-effort triage agent, publish and pin intentional agent versions rather than assuming a session override will change effort.

The update semantics also have an edge case. When an update keeps the model ID and omits effort, the stored effort remains. When the model ID changes and the update omits effort, the new model's default is used. Regression tests should therefore inspect the returned model object after both same-model and model-switch updates instead of assuming omission means the same thing in each case.

Effort is a model-control setting, not a performance promise. Anthropic documents available levels and defaults; it does not attach a July 22 latency, quality, token, or cost improvement claim to Managed Agents effort. Measure task success, token usage, wall time, and failure rate on your own workload before changing the default.

Replace lifecycle polling with webhooks

The July 22 additions cover these resource events in the webhook reference:

A safe receiver does five things:

1. Preserve the raw request body and verify webhook-id, webhook-timestamp, and webhook-signature with Anthropic's SDK helper before parsing business data.
2. Reject stale or invalid signatures and return a 2xx quickly for valid deliveries.
3. Deduplicate on the top-level webhook event.id, which remains the same across retries.
4. Enqueue the resource type and ID, then fetch current state. Do not rebuild state by applying webhook arrival order.
5. Run a periodic list/fetch reconciliation because subscriptions are not retroactive, disabled endpoints receive no replay, and exhausted delivery attempts are dropped.

The webhook endpoint must be public HTTPS on port 443. Anthropic says a 3xx response disables it immediately, redirects are not followed, and a URL resolving to a non-public address is also auto-disabled. Put URL moves behind an explicit endpoint update rather than an HTTP redirect.

Deleting a resource is the exception to “fetch after every signal”: environment.deleted and memory_store.deleted have no remaining object to retrieve. Treat the verified event as final, while preserving your own deletion tombstone so a late archive or update signal cannot recreate stale local state.

Choose safe update semantics

The new optional version field supports two distinct ownership models:

Interactive or multi-writer update
GET agent -> edit version N -> POST update with version N
                         -> 409 means re-read, merge, and retry

Declarative single-owner apply loop
render checked-in desired state -> POST update without version
                                -> last write wins

Anthropic's update semantics recommend supplying version for interactive callers and describe omission as suitable for a declarative loop that owns the agent. A supplied mismatch returns 409 even when the requested fields already equal current storage. Omission applies unconditionally and can silently replace another writer's change.

Keep version when any of these are true:

• an operator edits agents in the Console while automation also updates them;
• several services publish tool, system, skill, or roster changes;
• a migration script reads, modifies, and writes a subset of fields;
• losing another actor's update would be difficult to detect.

Omit it only when one reconciler has explicit ownership and can prove that every field it manages comes from the desired-state source. Remember that array fields such as tools, MCP servers, and skills are replaced in full, while metadata is merged by key. A last-write-wins apply loop with a partial array is still destructive.

Also test coordinator rosters. The agent docs say referenced subagents stay pinned to the versions resolved when the coordinator was created or updated. Publishing a new child version does not silently move existing coordinators to it; update the coordinator deliberately and verify the resolved roster.

Stream subagent output correctly

The multiagent documentation describes each child as a context-isolated thread with its own history. The primary session stream contains a condensed view of child lifecycle and cross-thread messages. To watch a child's generated text, connect to that thread's stream:

GET /v1/sessions/{session_id}/threads/{thread_id}/stream
  ?beta=true
  &event_deltas[]=agent.message

A connection previews only the thread it reads. Child deltas do not appear on the primary stream, so a UI that shows several subagents needs one selected-thread connection or a bounded connection manager. Do not open an unbounded stream per historical thread.

Treat the delta sequence as a scratch buffer:

1. On event_start, create a preview keyed by the announced event ID.
2. On each event_delta, append text by (event_id, delta.index).
3. When the persisted agent.message arrives, replace the preview with its complete content.
4. On span.model_request_end, close any preview that never received a buffered event.
5. After a disconnect, reopen the stream and list thread history; missed deltas cannot be replayed.

Anthropic explicitly calls deltas best effort. The server may shed them under load, they are never persisted, and the buffered message remains the record. Messages API streaming accumulators also do not transfer unchanged because Managed Agents uses event_start and event_delta without the Messages API's content-block start/stop sequence.

There is a live documentation inconsistency worth making a rollout test. As checked July 23, the release notes, current Managed Agents reference, and multiagent page say per-thread streams accept event_deltas[], while the general session event stream page still contains an older sentence saying thread streams reject it. The endpoint-specific multiagent page and July 22 release entry describe the new behavior, but do not promote it to a required UI path until an authenticated contract test confirms the deployed endpoint and your SDK version.

Migrate the memory beta header

Memory-store requests are the highest-risk compatibility change because a common “add the new beta next to the old one” strategy is invalid. The current memory guide says:

• memory-store endpoints use agent-memory-2026-07-22;
• sending that header together with managed-agents-2026-04-01 on a memory-store request returns HTTP 400;
• session endpoints, including a session that attaches a memory store, still use managed-agents-2026-04-01;
• current SDKs choose the appropriate beta automatically, but explicitly supplied betas must replace the old value rather than append the new one.

Current first-party documentation verifies this behavior. Centralize the mapping by endpoint family:

The list contract changes at the same boundary. GET /v1/memory_stores/{memory_store_id}/memories returns a stable server-defined order; order_by and order are ignored. path_prefix must end in / and matches whole path segments. depth accepts only omission, 0, or 1; other values return 400. Cursors created under the prior behavior are incompatible, so discard stored cursors and restart pagination from page one.

Do not replace a deterministic client sort with “whatever the API returns” if user-facing order matters. Fetch pages in the server-defined order, then apply an explicit stable sort in your application using a documented key. Record the key in tests so a future SDK or API change cannot silently alter presentation.

Sequence the migration

Use a staged rollout that keeps one likely cause per failure.

1. Inventory headers, cursors, writers, and pollers

Search every raw HTTP wrapper, SDK call that passes betas, persisted memory cursor, agent update path, lifecycle poller, and SSE accumulator. Record which service owns each agent definition and whether Console edits are allowed.

2. Upgrade and lock the memory request policy

Move memory-store calls to agent-memory-2026-07-22, keep session calls on managed-agents-2026-04-01, clear old cursors, and add explicit 400 tests for mixed headers and unsupported depth. Do this before combining other transport changes.

3. Preserve optimistic concurrency

Continue sending the read version from interactive and multi-writer paths. Add a deliberate stale-version test that expects 409. Only a reviewed single-owner reconciler should test and adopt unconditional updates.

4. Add initial_events behind a feature flag

Start with one user.message, read it back from history, and compare the resulting status/event sequence with the old create-then-send flow. Expand to outcomes or larger ordered batches only after the single-event path is stable.

5. Add webhooks without deleting reconciliation

Subscribe before depending on an event type, verify signatures and duplicates, and run the webhook path beside existing polling. Once delivery and repair metrics are understood, reduce polling to a slower reconciliation interval rather than removing it.

6. Add thread previews last

First keep buffered thread events working. Then add event_deltas[]=agent.message as a progressive enhancement. If the endpoint, SDK, or accumulator fails, the UI must fall back to buffered messages without losing the task result.

7. Tune effort as a separate experiment

Create a frozen task set, pin the agent/model version, and compare effort levels on outcome quality, tool behavior, latency, token usage, and failure rate. Do not mix this experiment with transport rollout data.

Run the regression test plan

A production gate should cover contracts, failure handling, and observability rather than only a happy-path session.

Record request IDs, status codes, event IDs, thread IDs, agent versions, selected beta headers, retry counts, webhook lag, reconciliation lag, and stream reconnects. Never log API keys, webhook signing secrets, vault credentials, or unredacted sensitive event content.

Use, delay or skip each feature

Use initial_events when most sessions start immediately with a known message or outcome and your client can reconcile ambiguous create timeouts. Skip it for sessions intentionally created idle or workflows that need a server-generated session ID before constructing the first event.

Use effort on the agent when the reasoning/cost/latency tradeoff belongs to a reusable versioned configuration. Delay it when per-request effort selection is required; session overrides do not apply it.

Use lifecycle webhooks to wake automation and reduce frequent resource polling. Do not use them as the only record when every transition matters, because delivery is unordered, retried only a limited number of times, and not replayed after gaps.

Keep optimistic versions for humans, Console/API coexistence, and multiple writers. Omit versions only for a reviewed declarative owner that intentionally applies complete desired state.

Use thread deltas for responsive subagent UX after the authenticated endpoint test passes. Skip them for batch jobs, audit pipelines, or any consumer that only needs final persisted output.

Adopt the memory header migration now if your integration calls memory-store endpoints. It is a compatibility requirement, not a cosmetic optimization. For broader persistent-memory design choices outside Managed Agents, compare the separate Claude-Mem guide and Agentmemory deep dive; those products have different trust and deployment boundaries.

Teams exposing private MCP servers to a managed session should also review the secure MCP tunnels guide. It covers network-boundary questions adjacent to this migration, not the Managed Agents event contracts themselves.

Production adoption checklist

• [ ] Confirm Managed Agents beta access and compliance/retention fit for the workload.
• [ ] Pin and record the SDK or raw API contract used in staging.
• [ ] Centralize beta headers by endpoint family; never append both memory identifiers.
• [ ] Delete or invalidate pre-migration memory-list cursors.
• [ ] Define an application sort key if memory presentation order matters.
• [ ] Keep version on every interactive or multi-writer agent update.
• [ ] Restrict unconditional updates to one named desired-state owner.
• [ ] Verify effort on the persisted agent and after model changes.
• [ ] Feature-flag initial_events and reconcile ambiguous create outcomes.
• [ ] Read seeded events back from history when their IDs matter.
• [ ] Verify webhook signatures against raw request bytes and deduplicate event IDs.
• [ ] Fetch current resource state instead of applying webhook arrival order.
• [ ] Preserve periodic reconciliation and deletion tombstones.
• [ ] Treat deltas as previews and buffered messages as authoritative.
• [ ] Test the child-thread delta endpoint with the production SDK/account before requiring it.
• [ ] Bound concurrent thread streams and provide a buffered-output fallback.
• [ ] Run the full compatibility matrix with captured status/event evidence.
• [ ] Roll out memory headers, concurrency, initial events, webhooks, deltas, and effort in separate stages.

The migration is complete when the client survives stale versions, duplicate and missing webhooks, incompatible cursors, mixed-header mistakes, stream disconnects, and delta loss without losing authoritative session state. Fewer requests are useful; a recoverable control plane is the real production outcome.

Official sources

Release, access, and migration

• Claude Platform release notes — July 22 feature list, July 2 memory-header and cursor behavior, SDK header migration, and earlier Managed Agents changes
• Claude Managed Agents overview — product boundary, cloud and self-hosted environments, beta access, retention and compliance caveats
• Migration from Messages API or Agent SDK — ownership changes between custom loops, Agent SDK, and Managed Agents

Agent and session contracts

• Define your agent — effort levels, per-session override limitation, optional versions, 409 behavior, field replacement/merge semantics, and roster pinning
• Start a session — initial_events, accepted event types, limits, atomic validation, running/idle behavior, and read-back behavior
• Session event stream — stream ordering, reconnection, delta accumulation, best-effort constraints, and buffered-event authority
• Multiagent orchestration — thread isolation, primary-stream scope, per-thread streams, and July 22 delta support
• Managed Agents reference — event types, stream-only delta contract, rate limits, and current per-thread wording

Lifecycle and memory

• Subscribe to webhooks — environment and memory-store events, signature verification, duplicates, ordering, retries, drops, and auto-disable behavior
• Using agent memory — endpoint-specific beta headers, mixed-header 400, cursor invalidation, server-defined ordering, path_prefix, and depth