Skip to main content

Agent Once, Session Every Run

The Managed Agents usage rule: create the agent, a versioned config, once; create a session for every run. Creating agents in the request path is the anti-pattern.

Hand-drawn ink-line illustration on terracotta: a loopy hand holds one large cream block aloft while a receding row of small identical cream blocks marches away below, a one-line profile face observing.

The object model​

Managed Agents splits an agent into two objects, per the platform docs (verify against platform.claude.com/docs; beta surfaces drift):

  • An agent is a persisted, versioned configuration: the model, the system prompt, the tools, the MCP servers, the skills. All of that lives on the agent, never on the session. Every update produces an immutable version.
  • A session is one run. It references an agent ID and an environment, streams events, and ends.

The rule follows from the split: create the agent once, store its ID, and reuse it forever. Each incoming job creates only a session.

Why request-path agent creation is the anti-pattern​

Calling agent creation inside the request path is the documented mistake, and it fails three ways at once. It orphans agents, one per request, until the account is a junkyard of unversioned configs. It spends creation latency on every run. And it defeats the versioning that is the point of the object model: with a stable agent ID, every session is traceable to an exact immutable config version, sessions can pin to a version, and a bad prompt change can be rolled back by pointing back at the previous one.

The shape the docs recommend is a control plane and a data plane: the agent config lives in version-controlled YAML applied with the ant CLI, and application code touches only session creation.

Why it earns a concept page​

This is the platform's version of a rule every infrastructure engineer already knows: configuration is not a runtime object. Teams coming from raw Messages API calls, where every request is self-contained, tend to carry that habit into Managed Agents and rebuild the agent per request because nothing stops them. The object model is the guardrail only if you use it as one.

It also compounds with the rest of the platform. Scheduled Deployments fire sessions against a stable agent ID on a clock. Memory Stores give those sessions continuity. And prompt caching rewards a frozen, versioned system prompt, since any byte of churn in the prefix invalidates the cache behind it.

Who runs this shape in production​

  • Rakuten deploys stable specialist agents and reports "We deploy each specialist agent within a week, managing long-running tasks across engineering, product, sales, marketing, and finance." (source)
  • Notion's task board fires sessions against its agents at volume: "30+ concurrent agent tasks from a single task board." (source)

Further Reading​