Chapter 2: The 4 Building Blocks — Agent, Environment, Session, Events

By the end of this chapter, you will be able to explain the four core primitives of Claude Managed Agents and describe how they fit together to run a task from start to finish.

The Big Idea

Every Managed Agents workflow is built from exactly four concepts. Anthropic didn't create a dozen abstractions — just four, each with a precise job.

These four concepts are: Agent, Environment, Session, and Events.

Understanding these isn't just academic. Every API call you make, every CLI command you run, and every piece of code you write maps directly onto one of these four things. When something breaks, you'll diagnose it faster because you know which primitive is involved. When you're designing a new workflow, you'll sketch it out in terms of these four objects before writing a single line.

The official overview docs define them this way:

Concept	Description
Agent	The model, system prompt, tools, MCP servers, and skills
Environment	A configured container template (packages, network access)
Session	A running agent instance within an environment, performing a specific task and generating outputs
Events	Messages exchanged between your application and the agent (user turns, tool results, status updates)

Let's make each one concrete.

DiagramFour-block diagram, each block a different color. Block 1 (Agent): brain icon — "model + persona + tools." Block 2 (Environment): server/container icon — "cloud container + packages." Block 3 (Session): gear/running icon — "agent + environment in motion." Block 4 (Events): two-way arrow icon — "messages in and out." Arranged left to right showing that Agent and Environment feed into Session, which communicates via Events.

The Analogy

Think of a staffing agency placing a specialist in a client's office.

The Agent is the worker's profile on file at the agency: their skills, their specialty, their working style. It's a reusable document — you reference it every time you need that type of work done, without recreating it from scratch.

The Environment is the office setup: the computer, the software installed, the network permissions, whether they can access the internet. Different clients might give the same worker different office setups depending on the project.

The Session is the actual placement — that specific worker, in that specific office, on that specific project. It's the event, not the profile or the office in isolation.

Events are the communication during the engagement: the morning brief from the client, the worker's progress updates, the flag when they need a decision made, and the final delivery confirmation. All of it logged, nothing lost.

One staffing profile, many placements. One office setup, many workers. Every placement produces its own log of events. That's the model.

DiagramOffice scene illustration. Left: Filing cabinet labeled "Agents" — a folder with Claude's logo. Middle: Office desk labeled "Environment" — computer, packages listed on screen. Right: Worker at desk labeled "Session — agent + environment, active." Floating messages going back and forth labeled "Events."

How It Actually Works

The Agent: Reusable Configuration

The Agent is the configuration object that defines how Claude will behave. According to the agent setup documentation, an agent bundles:

The model (which Claude version runs)
The system prompt (persona and behavioral instructions)
The tools available (the built-in toolset, MCP servers, custom tools)
The skills (domain-specific knowledge packages)

You create an agent once and reference it by its id every time you start a session. Agents are versioned — each update increments the version number, and you can pin sessions to specific versions for controlled rollouts.

A minimal agent creation via CLI looks like this:

ant beta:agents create \
  --name "Coding Assistant" \
  --model '{id: claude-opus-4-7}' \
  --system "You are a helpful coding assistant. Write clean, well-documented code." \
  --tool '{type: agent_toolset_20260401}'

(Every parameter here is part of the reusable agent definition. The session will reference this agent by its returned id.)

The Environment: Container Configuration

The Environment defines where your agent runs. Per the environments documentation, you create an environment once and reference its id each time you start a session. Multiple sessions can share the same environment, but each session gets its own isolated container instance — sessions never share file system state.

The environment configuration specifies:

Container type — currently cloud (Anthropic-managed)
Pre-installed packages — Python, Node, pip packages, npm packages, etc.
Networking — unrestricted (full internet access) or limited (allowlist-based)

A simple environment:

ant beta:environments create \
  --name "quickstart-env" \
  --config '{type: cloud, networking: {type: unrestricted}}'

(This creates a container with unrestricted internet access. The environment ID is returned and used at session creation.)

The Session: The Running Instance

The Session is where work actually happens. The sessions documentation describes it as "a running agent instance within an environment. Each session references an agent and an environment (both created separately), and maintains conversation history across multiple interactions."

Creating a session is simple:

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)

(Pass the IDs of the agent and environment you created. The session is now provisioned and waiting for events.)

Key properties of a session:

It starts in idle status, waiting for you to send it work
It can be in one of four statuses: idle, running, rescheduling, or terminated
It maintains the complete event history as a durable, append-only log
Deleting a session permanently removes its record; its referenced agent and environment are unaffected

Events: The Communication Layer

Events are how you talk to a running session and how the session talks back. The event stream documentation describes them as "messages exchanged between your application and the agent."

The communication is bidirectional:

Events you send to the session (user events):

user.message — Give the agent a task or follow-up instruction
user.tool_confirmation — Approve or deny a pending tool call
user.custom_tool_result — Return the result of a tool your code executed
user.interrupt — Stop the agent mid-task

Events the session sends back to you:

agent.message — Claude's text response
agent.tool_use — Claude is about to invoke a built-in tool
session.status_idle — The session has paused (work is done, or waiting for your input)
session.error — Something went wrong (e.g., an MCP server authentication failure)

Every event includes a processed_at timestamp recording when it was logged server-side. If processed_at is null, the event has been queued but not yet handled.

How the Five Steps Connect

The overview documentation describes the full workflow in five steps:

Create an agent — Define model, system prompt, tools, MCP servers, and skills. Reference by ID.
Create an environment — Configure the container: packages, network access, mounted files.
Start a session — Launch a session combining the agent and environment.
Send events and stream responses — Send user.message events. Claude executes tools and streams back results via server-sent events (SSE). History is persisted server-side.
Steer or interrupt — Send additional events to guide the agent, or interrupt to change direction.

Steps 1 and 2 happen once. Steps 3 through 5 repeat for every task you want to run.

DiagramFive-step flow diagram arranged horizontally. Each step is a labeled box with an icon: (1) Blueprint icon — "Create Agent" — one-time. (2) Server icon — "Create Environment" — one-time. (3) Play button — "Start Session" — per task. (4) Two-way arrows — "Send Events / Stream Responses" — ongoing. (5) Steering wheel — "Steer or Interrupt" — as needed. Steps 1-2 grouped with "Do once" label. Steps 3-5 grouped with "Do per task" label.

Try it yourself

Try It Yourself

This walkthrough sets up the foundational objects — no task execution yet. Just getting the scaffolding in place.

Verify your CLI is set up:
```
ant --version
export ANTHROPIC_API_KEY="your-api-key-here"
```
(Confirms the CLI is installed and your key is ready.)

Create your first agent:

ant beta:agents create \
  --name "My First Agent" \
  --model '{id: claude-haiku-4-5-20251001}' \
  --system "You are a helpful assistant." \
  --tool '{type: agent_toolset_20260401}'

(Uses Haiku to keep costs low while you're learning. Note the returned id — you'll need it.)

Create an environment:

ant beta:environments create \
  --name "learning-env" \
  --config '{type: cloud, networking: {type: unrestricted}}'

(Note the returned environment id.)

Look up the four primitives in the docs. Open platform.claude.com/docs/en/managed-agents/overview and find the table showing all four. Notice which ones are described as "created once" vs. "per task."
Sketch your agent workflow on paper. For the task you identified in Chapter 1: what is the agent configuration? What packages does the environment need? How many sessions will you need to run? What events will go back and forth?

DiagramAnnotated screenshot of the overview page's four-concept table with highlight boxes around each row and callout labels: "This is your blueprint," "This is your workspace," "This is a job run," "This is the conversation."

Common pitfalls

Common Pitfalls

Conflating the agent with the session. The agent is a specification. The session is an execution. You update the agent when you want to change future behavior; you terminate or archive a session when the work is done. These are different operations that don't affect each other.
Thinking environments are per-agent. Environments are independent objects. A single environment can be used by many different agents and many different sessions. A single agent can run in many different environments. The only constraint is that each session gets its own isolated container instance.
Forgetting to open the stream before sending. When working with events programmatically, the correct pattern is: open the event stream first, then send the user.message. If you send first, you risk missing events that fire in the gap. The Quickstart documentation makes this explicit.
Ignoring the session.status_idle event. This event is your signal that the session has paused. It includes a stop_reason field that tells you why it paused: end_turn (work is done) or requires_action (needs your confirmation or tool result). Always check this field — it determines what you do next.

Toolkit

Reference Card: The 4 Primitives — A single-page quick reference with each primitive's definition, key fields, and whether it's created once or per task.
Worksheet: Map Your First Workflow — A fill-in template for planning an agent deployment: fields for Agent name/model/tools, Environment packages/networking, Session trigger and expected events, and the definition of "done."

Chapter Recap

Managed Agents is built on four precisely defined primitives: Agent (the configuration), Environment (the container), Session (the running instance), and Events (the communication layer).
The Agent and Environment are created once and reused; Sessions are created per task and hold the complete event history.
The five-step workflow — Create Agent, Create Environment, Start Session, Send Events, Steer or Interrupt — maps directly onto these primitives. Steps 1 and 2 happen once; steps 3 through 5 repeat per task.