Skip to main content

Managed Agents

Advanced
What you'll learn
  • Understand what a managed (Anthropic-hosted) agent loop hands off for you
  • Separate the two core objects: a versioned Agent vs a per-run Session
  • Inject secrets safely with Vaults — without the model ever seeing them
  • Put an agent on a cron schedule with Scheduled Deployments — no scheduler to host
  • Know when managed beats a custom loop, and the guardrails that still apply

If building your own agent loop is more infrastructure than you want to own, a managed (Anthropic-hosted) agent runs the loop for you — so you focus on the agent's job, not on session plumbing, retries, state, and scheduling.

The two objects: Agent vs Session​

This is the mental model everything else hangs off. They are separate on purpose.

  • An Agent is a persisted, versioned configuration — model, system prompt, tools, MCP servers, and skills. You create it once. Every update creates a new immutable version.
  • A Session is a runtime instance — one execution that points at an agent by ID. Configuration lives on the agent, never the session.
Pro tip

Sessions pin to the agent version they were created with: running sessions keep their version, new sessions get the latest. That's how you ship config changes without breaking in-flight work.

What "managed" buys you​

Rather than hand-rolling and hosting the loop, you get hosted building blocks:

  • Sessions — persistent runs you create per execution and resume; stream events over SSE.
  • Environments — container infrastructure, either cloud (Anthropic-hosted) or self_hosted (tools execute in your own VPC). One container per session is the agent's workspace.
  • Memory stores — persistent state across sessions, mounted as a directory in the sandbox, with immutable versioning and a redact endpoint. No database on your side.
  • Vaults — secrets for MCP auth and other services.
  • Scheduled deployments — agents that run on a cron schedule, unattended.

Create an agent (versioned config), then run a session against it

# 1. Create the agent once
POST /v1/agents        -> returns $AGENT_ID
# 2. Each execution is a session pinned to that agent
POST /v1/sessions      { "agent": "$AGENT_ID" }

Vaults: secrets the model never sees​

An autonomous agent often needs an API key — but the model should never read it. Vault credentials (mcp_oauth, static_bearer, environment_variable) are substituted at egress: an environment_variable credential is injected into the sandbox at execution time and is never visible to the model.

Watch out

This is the safe pattern for giving an agent powerful access. Don't paste keys into the system prompt or a message — they become part of the context the model (and your logs) can see. Put them in a vault.

Scheduled deployments: an agent on a cron​

A deployment attaches a cron schedule to an agent. When the schedule fires, it starts a fresh session and completes its task — no scheduler for you to build or host. Good for a nightly data sync, a weekly compliance scan, or a daily digest.

Guided walkthrough1 of 4
  1. POST /v1/deployments with agent, environment_id, initial_events (must include a user.message), and a schedule: a POSIX cron expression plus an IANA timezone.

A weekly compliance scan, Fridays at 20:00 New York time

POST /v1/deployments
{
"name": "Weekly compliance scan",
"agent": "$AGENT_ID",
"environment_id": "$ENVIRONMENT_ID",
"initial_events": [
  {"type": "user.message", "content": [{"type": "text", "text": "Run the compliance scan and summarize findings."}]}
],
"schedule": {"type": "cron", "expression": "0 20 * * 5", "timezone": "America/New_York"}
}
Pro tip

Cron is minute hour day-of-month month day-of-week, minute-level granularity. DST uses wall-clock semantics: a time that doesn't exist on spring-forward is skipped; a time that occurs twice on fall-back fires twice. Pick a timezone and an hour that avoids those edges for anything sensitive.

When to choose managed vs custom​

Choose managed when…Choose a custom loop / SDK when…
You want hosting, state, scheduling, and secrets handledYou need full control over the loop and tools
You're prototyping quicklyYou have strict custom infra/compliance needs
Ops simplicity matters more than controlYou're embedding deeply in your own stack

It's a spectrum — single call → workflow → custom agent (SDK) → managed. Start as simple as the task allows; move up only when you need to.

Same guardrails apply​

Hosted or not, an autonomous agent still takes actions. Keep least privilege, bounded cost/iterations, and human approval for risky steps — see Securing Agents and Hardening Autonomous Runs.

Key takeaways
  • Managed agents hand off the loop, sessions, environments, memory, vaults, and scheduling so you focus on the job
  • An Agent is versioned config; a Session is one run that pins to a version — config lives on the agent, not the session
  • Vault environment_variable credentials are injected at execution and never visible to the model — the safe way to give an agent secrets
  • A scheduled deployment is a cron expression + IANA timezone; each fire creates a run, and unpause does not backfill missed triggers
  • Managed sits at the hosted end of single call -> workflow -> custom -> managed; the autonomy guardrails still apply

Check yourself​

Check yourself

0/3
  1. What is the difference between an Agent and a Session?
  2. How should you give a managed agent an API key it needs?
  3. A scheduled deployment was paused for two days and then unpaused. What happens to the triggers that would have fired while paused?

Next​