Get started with Claude Managed Agents

This guide walks you through creating an agent, setting up an environment, starting a session, and streaming agent responses.

Core concepts

Prerequisites

• A Claude Console account
• An API key

Install the CLI

brew install anthropics/tap/ant

Check the installation:

ant --version

Install the SDK

pip install anthropic

Set your API key as an environment variable:

export ANTHROPIC_API_KEY="your-api-key-here"

Create your first session

1. 1

   Create an agent

   Create an agent that defines the model, system prompt, and available tools.

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   ant apply coding-assistant.md

   coding-assistant.md

   

   ---
   name: Coding Assistant
   model: claude-opus-5
   tools:
     - type: agent_toolset_20260401
   ---
   
   You are a helpful coding assistant. Write clean, well-documented code.

   The agent_toolset_20260401 tool type enables the full set of pre-built agent tools (bash, file operations, web search, and more). See Tools for the complete list and per-tool configuration options.

   Save the returned agent.id (the CLI's ant apply prints it and records it in claude-lock.json). You'll reference it in every session you create.

2. 2

   Create an environment

   An environment defines the sandbox where your agent runs.

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   ant apply environment.yaml

   environment.yaml

   

   name: quickstart-env
   config:
     type: cloud
     networking:
       type: unrestricted

   Save the returned environment.id (also in claude-lock.json if you used ant apply). You'll reference it in every session you create.

3. 3

   Start a session

   Create a session that references your agent and environment.

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   session = client.beta.sessions.create(
       agent=agent.id,
       environment_id=environment.id,
       title="Quickstart session",
   )
   
   print(f"Session ID: {session.id}")

4. 4

   Send a message and stream the response

   Open a stream, send a user event, then process events as they arrive:

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   with client.beta.sessions.events.stream(session.id) as stream:
       # Send the user message after the stream opens
       client.beta.sessions.events.send(
           session.id,
           events=[
               {
                   "type": "user.message",
                   "content": [
                       {
                           "type": "text",
                           "text": "Create a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt",
                       },
                   ],
               },
           ],
       )
   
       # Process streaming events
       for event in stream:
           match event.type:
               case "agent.message":
                   for block in event.content:
                       if block.type == "text":
                           print(block.text, end="")
               case "agent.tool_use":
                   print(f"\n[Using tool: {event.name}]")
               case "session.status_idle":
                   print("\n\nAgent finished.")
                   break

   The agent writes a Python script, runs it in the sandbox, and verifies the output file was created. Your output looks similar to this:

   I'll create a Python script that generates the first 20 Fibonacci numbers and saves them to a file.
   [Using tool: write]
   [Using tool: bash]
   The script ran successfully. Let me verify the output file.
   [Using tool: bash]
   fibonacci.txt contains the first 20 Fibonacci numbers (0 through 4181).
   
   Agent finished.

   

What's happening

When you send a user event, Claude Managed Agents:

1. Provisions a sandbox: Your environment configuration determines how it's built.
2. Runs the agent loop: Claude determines which tools to use based on your message.
3. Runs tools: File writes, bash commands, and other tool calls run inside the sandbox.
4. Streams events: You receive real-time updates as the agent works.
5. Goes idle: The agent emits a session.status_idle event when it has nothing more to do.

Build a complete app

Each of these quickstarts pairs Claude Managed Agents with a popular chat framework to make a complete, runnable application. In each one, the framework renders the chat surface while a managed session runs the agent loop server-side: the session holds the transcript, runs tools in a sandbox, and streams events that the front end renders.

Next steps