Claude Managed Agents

https://platform.claude.com/docs/en/managed-agents/
Admin
Claude Managed Agents is a pre-built, configurable agent harness that runs in managed infrastructure...
Tokens:328,351
Snippets:1,670
Trust Score:9.9
Update:1 week ago
Show doc for...
Tokens:
Raw
### Create and run a managed agent with custom tool in Go

Source: https://platform.claude.com/docs/en/managed-agents/migration

Complete Go example for creating a managed agent with a custom tool, creating an environment, starting a session, sending a user message, and streaming events. It handles custom tool use by calling a local function and sending the result back, and exits when the session reaches an idle status with an end-turn stop reason.

```go
client := anthropic.NewClient()
ctx := context.Background()

agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
	Name: "weather-agent",
	Model: anthropic.BetaManagedAgentsModelConfigParams{
		ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5,
	},
	System: anthropic.String("You are a concise weather assistant."),
	Tools: []anthropic.BetaAgentNewParamsToolUnion{{
		OfCustom: &anthropic.BetaManagedAgentsCustomToolParams{
			Type:        anthropic.BetaManagedAgentsCustomToolParamsTypeCustom,
			Name:        "get_weather",
			Description: "Get the current weather for a city.",
			InputSchema: anthropic.BetaManagedAgentsCustomToolInputSchemaParam{
				Properties: map[string]any{
					"city": map[string]any{"type": "string"},
				},
				Required: []string{"city"},
			},
		},
	}},
})
if err != nil {
	panic(err)
}
environment, err := client.Beta.Environments.New(ctx, anthropic.BetaEnvironmentNewParams{
	Name: "weather-env",
	Config: anthropic.BetaEnvironmentNewParamsConfigUnion{
		OfCloud: &anthropic.BetaCloudConfigParams{
			Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{
				OfLimited: &anthropic.BetaLimitedNetworkParams{
					AllowPackageManagers: anthropic.Bool(true),
				},
			},
		},
	},
})
if err != nil {
	panic(err)
}

session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
	Agent: anthropic.BetaSessionNewParamsAgentUnion{
		OfBetaManagedAgentsAgents: &anthropic.BetaManagedAgentsAgentParams{
			Type:    anthropic.BetaManagedAgentsAgentParamsTypeAgent,
			ID:      agent.ID,
			Version: anthropic.Int(agent.Version),
		},
	},
	EnvironmentID: environment.ID,
})
if err != nil {
	panic(err)
}

getWeather := func(city string) string {
	return fmt.Sprintf("%s: 18°C, clear", city)
}

stream := client.Beta.Sessions.Events.StreamEvents(ctx, session.ID, anthropic.BetaSessionEventStreamParams{})
defer stream.Close()

_, err = client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
	Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
		OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
			Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
			Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
				OfText: &anthropic.BetaManagedAgentsTextBlockParam{
					Type: anthropic.BetaManagedAgentsTextBlockTypeText,
					Text: "What's the weather in Tokyo?",
				},
			}},
		},
	}},
})
if err != nil {
	panic(err)
}

loop:
for stream.Next() {
	event := stream.Current()
	switch event.Type {
	case "agent.message":
		for _, block := range event.AsAgentMessage().Content {
			if block.Type == "text" {
				fmt.Println(block.Text)
			}
		}
	case "agent.custom_tool_use":
		toolUse := event.AsAgentCustomToolUse()
		result := getWeather(toolUse.Input["city"].(string))
		if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
			Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
				OfUserCustomToolResult: &anthropic.BetaManagedAgentsUserCustomToolResultEventParams{
					Type:            anthropic.BetaManagedAgentsUserCustomToolResultEventParamsTypeUserCustomToolResult,
					CustomToolUseID: toolUse.ID,
					Content: []anthropic.BetaManagedAgentsUserCustomToolResultEventParamsContentUnion{{
						OfText: &anthropic.BetaManagedAgentsTextBlockParam{
							Type: anthropic.BetaManagedAgentsTextBlockTypeText,
							Text: result,
						},
					}},
				},
			}},
		}); err != nil {
			panic(err)
		}
	case "session.status_idle":
		idle := event.AsSessionStatusIdle()
		if _, ok := idle.StopReason.AsAny().(anthropic.BetaManagedAgentsSessionEndTurn); ok {
			break loop
		}
	}
}
if err := stream.Err(); err != nil {
	panic(err)
}
```

--------------------------------

### Scheduled deployment response example

Source: https://platform.claude.com/docs/en/managed-agents/scheduled-deployments

Example JSON response from creating a scheduled deployment, showing the schedule with upcoming run times. The response includes a populated schedule.upcoming_runs_at to confirm the schedule was set correctly.

```json
{
  "id": "depl_01xyz",
  "status": "active",
  "paused_reason": null,
  "schedule": {
    "type": "cron",
    "expression": "0 20 * * 5",
    "timezone": "America/New_York",
    "last_run_at": null,
    "upcoming_runs_at": [
      "2026-05-09T00:00:00Z",
      "2026-05-16T00:00:00Z",
      "2026-05-23T00:00:00Z"
    ]
  }
}
```

--------------------------------

### C# Managed Agents Migration Example

Source: https://platform.claude.com/docs/en/managed-agents/migration

Complete C# example showing how to create a managed agent, environment, and session, then stream events and handle custom tool use. Uses Anthropic SDK for .NET.

```csharp
using System.Text.Json;

using Anthropic.Models.Beta.Agents;
using Anthropic.Models.Beta.Environments;
using Anthropic.Models.Beta.Sessions;
using Anthropic.Models.Beta.Sessions.Events;

AnthropicClient client = new();

var agent = await client.Beta.Agents.Create(new()
{
    Name = "weather-agent",
    Model = BetaManagedAgentsModel.ClaudeOpus5_5,
    System = "You are a concise weather assistant.",
    Tools =
    [
        new BetaManagedAgentsCustomToolParams
        {
            Type = "custom",
            Name = "get_weather",
            Description = "Get the current weather for a city.",
            InputSchema = new()
            {
                Properties = new Dictionary<string, JsonElement>
                {
                    ["city"] = JsonSerializer.SerializeToElement(new { type = "string" }),
                },
                Required = ["city"],
            },
        },
    ],
});
var environment = await client.Beta.Environments.Create(new()
{
    Name = "weather-env",
    Config = new BetaCloudConfigParams
    {
        Networking = new BetaLimitedNetworkParams { AllowPackageManagers = true },
    },
});

var session = await client.Beta.Sessions.Create(new()
{
    Agent = new BetaManagedAgentsAgentParams
    {
        Type = "agent",
        ID = agent.ID,
        Version = agent.Version,
    },
    EnvironmentID = environment.ID,
});

static string GetWeather(string city) => $"{city}: 18°C, clear";

using var stream = await client.Beta.Sessions.Events.WithRawResponse.StreamStreaming(session.ID);

await client.Beta.Sessions.Events.Send(session.ID, new()
{
    Events =
    [
        new BetaManagedAgentsUserMessageEventParams
        {
            Type = "user.message",
            Content = [new BetaManagedAgentsTextBlock { Type = "text", Text = "What's the weather in Tokyo?" }],
        },
    ],
});

await foreach (var streamEvent in stream.Enumerate())
{
    if (streamEvent.Value is BetaManagedAgentsAgentMessageEvent message)
    {
        var text = string.Concat(message.Content.Select(block =>
            block.Value is BetaManagedAgentsTextBlock textBlock ? textBlock.Text : ""));
        Console.WriteLine(text);
    }
    else if (streamEvent.Value is BetaManagedAgentsAgentCustomToolUseEvent toolUse)
    {
        var result = GetWeather(toolUse.Input["city"].GetString()!);
        await client.Beta.Sessions.Events.Send(session.ID, new()
        {
            Events =
            [
                new BetaManagedAgentsUserCustomToolResultEventParams
                {
                    Type = "user.custom_tool_result",
                    CustomToolUseID = toolUse.ID,
                    Content =
                    [
                        new BetaManagedAgentsTextBlock
                        {
                            Type = "text",
                            Text = result,
                        },
                    ],
                },
            ],
        });
    }
    else if (streamEvent.Value is BetaManagedAgentsSessionStatusIdleEvent idle
        && idle.StopReason?.Value is BetaManagedAgentsSessionEndTurn)
    {
        break;
    }
}
```

--------------------------------

### Example response for read queue depth

Source: https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-operations

Example JSON response from the `GET /v1/environments/{environment_id}/work/stats` endpoint, showing the queue state fields.

```text
{
  "type": "work_queue_stats",
  "depth": 0,
  "pending": 0,
  "oldest_queued_at": null,
  "workers_polling": 0
}
```

--------------------------------

### Go: Connect to MCP server and run EnvironmentWorker

Source: https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-custom-tools

This Go example connects to an MCP server at startup, lists tools, converts them to BetaTools, and runs an EnvironmentWorker with the tools. It requires ANTHROPIC_ENVIRONMENT_KEY and ANTHROPIC_ENVIRONMENT_ID environment variables. The worker runs until interrupted.

```go
const mcpServerURL = "http://mcp.internal.example.com:8000/mcp"

func main() {
	environmentKey := os.Getenv("ANTHROPIC_ENVIRONMENT_KEY")
	environmentID := os.Getenv("ANTHROPIC_ENVIRONMENT_ID")

	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()

	client := anthropic.NewClient(option.WithAuthToken(environmentKey))

	// Connect to the MCP server once at startup and keep the session open for
	// the life of the worker.
	mcpClient := mcpsdk.NewClient(&mcpsdk.Implementation{Name: "sandbox-worker", Version: "1.0.0"}, nil)
	session, err := mcpClient.Connect(ctx, &mcpsdk.StreamableClientTransport{Endpoint: mcpServerURL}, nil)
	if err != nil {
		log.Fatalf("connect to MCP server: %v", err)
	}
	defer session.Close()

	listed, err := session.ListTools(ctx, nil)
	if err != nil {
		log.Fatalf("list MCP tools: %v", err)
	}
	mcpTools, err := mcp.NewBetaTools(listed.Tools, session)
	if err != nil {
		log.Fatalf("convert MCP tools: %v", err)
	}

	worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{
		EnvironmentID:  environmentID,
		EnvironmentKey: environmentKey,
		Workdir:        "/workspace",
		ToolsFunc: func(env *agenttoolset.AgentToolContext) []anthropic.BetaTool {
			return append(agenttoolset.BetaAgentToolset20260401(env), mcpTools...)
		},
	})
	if err := worker.Run(ctx); err != nil {
		log.Fatalf("worker: %v", err)
	}
}
```

--------------------------------

### Workflow run phase started event

Source: https://platform.claude.com/docs/en/managed-agents/workflow-runs

Example of the workflow_run.phase_started event that indicates a run phase has started. It includes the run ID, phase ID, and processing timestamp.

```json
{
  "type": "workflow_run.phase_started",
  "id": "sevt_01def...",
  "workflow_run_id": "wrun_01J8XkN5uT3vHpLqRfWdY2",
  "workflow_run_phase_id": "wrph_01Kd3a1f3",
  "processed_at": "2026-10-09T14:01:46Z"
}
```

--------------------------------

### Go: Serve tools from the worker with mcp.NewBetaTools

Source: https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-custom-tools

Connects to an MCP server at startup, converts its tools with mcp.NewBetaTools, and registers them alongside agenttoolset.BetaAgentToolset20260401. Keeps one MCP session open for the life of the worker.

```go
package main

import (
	"context"
	"log"
	"os"
	"os/signal"
	"syscall"

	"github.com/anthropics/anthropic-sdk-go"
	"github.com/anthropics/anthropic-sdk-go/lib/environments"
	"github.com/anthropics/anthropic-sdk-go/mcp"
	"github.com/anthropics/anthropic-sdk-go/option"
	"github.com/anthropics/anthropic-sdk-go/tools/agenttoolset"
	mcpsdk "github.com/modelcontextprotocol/go-sdk/mcp"
)
```

--------------------------------

### Install MCP SDK alongside Anthropic SDK

Source: https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-custom-tools

Install the MCP SDK alongside the Anthropic SDK to use client-side MCP helpers. For Python, use `pip install "anthropic[mcp]" "mcp>=1.24"`. For TypeScript, use `npm install @modelcontextprotocol/sdk`. For Go, use `go get github.com/modelcontextprotocol/go-sdk`.

```shell
pip install "anthropic[mcp]" "mcp>=1.24"
```

```shell
npm install @modelcontextprotocol/sdk
```

```shell
go get github.com/modelcontextprotocol/go-sdk
```

--------------------------------

### Create environment with limited networking (Python)

Source: https://platform.claude.com/docs/en/managed-agents/environments

Use the Python SDK to create a cloud environment with limited networking, allowing api.example.com and enabling MCP servers and package managers. The `client` must be initialized with the appropriate API key and beta headers.

```python
environment = client.beta.environments.create(
    name="api-access",
    config={
        "type": "cloud",
        "networking": {
            "type": "limited",
            "allowed_hosts": ["api.example.com"],
            "allow_mcp_servers": True,
            "allow_package_managers": True,
        },
    },
)
```

--------------------------------

### GET /v1/agents/{agent_id}/versions

Source: https://platform.claude.com/docs/en/managed-agents/agent-setup

Fetches the full version history of an agent. Results are paginated, and the SDK examples fetch every page automatically.

```APIDOC
## GET /v1/agents/{agent_id}/versions

### Description
Fetches the full version history of an agent. Results are paginated, and the SDK examples fetch every page automatically.

### Method
GET

### Endpoint
https://api.anthropic.com/v1/agents/{agent_id}/versions

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The ID of the agent.

#### Headers
- **x-api-key** (string) - Required - Your Anthropic API key.
- **anthropic-version** (string) - Required - API version, e.g., 2023-06-01.
- **anthropic-beta** (string) - Required - Beta header, e.g., managed-agents-2026-04-01.

### Response
#### Success Response (200)
- **data** (array) - List of agent versions.
  - **version** (integer) - The version number.
  - **updated_at** (string) - Timestamp of when the version was created.

#### Response Example
{
  "data": [
    {
      "version": 1,
      "updated_at": "2026-04-01T12:00:00Z"
    }
  ]
}
```

--------------------------------

### Run worker with ant CLI: ant beta:worker poll

Source: https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-workers

Starts an always-on worker using the ant CLI. The worker authenticates with the environment key from the quickstart and polls for work in the /workspace directory.

```bash
ant beta:worker poll --workdir /workspace
```

--------------------------------

### Set domain lists on an agent (C#, Go, Java)

Source: https://platform.claude.com/docs/en/managed-agents/tools-web-restrictions

Creates a managed agent with a toolset that configures web search and web fetch tools, setting allowed and blocked domains, user location, and max content tokens. The example then iterates over the agent's tools and prints the toolset configs as indented JSON. Requires the Anthropic SDK for the respective language.

```csharp
using Anthropic.Models.Beta.Agents;

AnthropicClient client = new();

var agent = await client.Beta.Agents.Create(new()
{
    Name = "Research Agent",
    Model = BetaManagedAgentsModel.ClaudeOpus5_5,
    Tools =
    [
        new BetaManagedAgentsAgentToolset20260401Params
        {
            Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401,
            Configs =
            [
                new BetaManagedAgentsWebSearchToolConfigParams
                {
                    AllowedDomains = ["docs.example.com", "arxiv.org"],
                    UserLocation = new()
                    {
                        Country = "US",
                        Timezone = "America/Los_Angeles",
                    },
                },
                new BetaManagedAgentsWebFetchToolConfigParams
                {
                    BlockedDomains = ["ads.example.com"],
                    MaxContentTokens = 50_000,
                },
            ],
        },
    ],
});

JsonSerializerOptions jsonOptions = new() { WriteIndented = true };
foreach (var tool in agent.Tools)
{
    if (tool.TryPickBetaManagedAgentsAgentToolset20260401(out var toolset))
    {
        Console.WriteLine(JsonSerializer.Serialize(toolset.Configs, jsonOptions));
    }
}
```

```go
client := anthropic.NewClient()
ctx := context.Background()

agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
	Name: "Research Agent",
	Model: anthropic.BetaManagedAgentsModelConfigParams{
		ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5,
	},
	Tools: []anthropic.BetaAgentNewParamsToolUnion{{
		OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
			Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
			Configs: []anthropic.BetaManagedAgentsAgentToolConfigParamsUnion{
				{OfWebSearch: &anthropic.BetaManagedAgentsWebSearchToolConfigParams{
					AllowedDomains: []string{"docs.example.com", "arxiv.org"},
					UserLocation: anthropic.BetaManagedAgentsUserLocationParam{
						Country:  anthropic.String("US"),
						Timezone: anthropic.String("America/Los_Angeles"),
					},
				}},
				{OfWebFetch: &anthropic.BetaManagedAgentsWebFetchToolConfigParams{
					BlockedDomains:   []string{"ads.example.com"},
					MaxContentTokens: anthropic.Int(50000),
				}},
			},
		},
	}},
})
if err != nil {
	panic(err)
}

for _, tool := range agent.Tools {
	switch toolset := tool.AsAny().(type) {
	case anthropic.BetaManagedAgentsAgentToolset20260401:
		configs := make([]json.RawMessage, len(toolset.Configs))
		for i, config := range toolset.Configs {
			configs[i] = json.RawMessage(config.RawJSON())
		}
		output, err := json.MarshalIndent(configs, "", "  ")
		if err != nil {
			panic(err)
		}
		fmt.Println(string(output))
	}
}
```

```java
import com.anthropic.models.beta.agents.AgentCreateParams;
import com.anthropic.models.beta.agents.BetaManagedAgentsAgentToolset20260401Params;
import com.anthropic.models.beta.agents.BetaManagedAgentsModel;
import com.anthropic.models.beta.agents.BetaManagedAgentsUserLocation;
import com.anthropic.models.beta.agents.BetaManagedAgentsWebFetchToolConfigParams;
import com.anthropic.models.beta.agents.BetaManagedAgentsWebSearchToolConfigParams;

void main() {
    var client = AnthropicOkHttpClient.fromEnv();

    var agent = client.beta().agents().create(AgentCreateParams.builder()
        .name("Research Agent")
        .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
        .addTool(BetaManagedAgentsAgentToolset20260401Params.builder()
            .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
            .addConfig(BetaManagedAgentsWebSearchToolConfigParams.builder()
                .allowedDomains(List.of("docs.example.com", "arxiv.org"))
                .userLocation(BetaManagedAgentsUserLocation.builder()
                    .country("US")
                    .timezone("America/Los_Angeles")
                    .build())
                .build())
            .addConfig(BetaManagedAgentsWebFetchToolConfigParams.builder()
                .blockedDomains(List.of("ads.example.com"))
                .maxContentTokens(50_000)
                .build())
            .build())
        .build());

    for (var tool : agent.tools()) {
        if (tool.isAgentToolset20260401()) {
            var configs = tool.asAgentToolset20260401().configs();
            IO.println(ObjectMappers.jsonMapper().valueToTree(configs));
        }
    }
}
```

--------------------------------

### System prompt for contract-review agent

Source: https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration

Add this instruction to the agent's system prompt to guide when to start a workflow run. It tells the agent to use a run for more than a few contracts and to handle one or two contracts itself.

```text
You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.
```

--------------------------------

### Create session with budget in Go

Source: https://platform.claude.com/docs/en/managed-agents/sessions

Creates a session with a $1.25 budget using the Go SDK. The budget uses `BetaManagedAgentsBudgetLimitTypeLimit` and `BetaCurrencyUsd`. The session ID and budget amount are printed.

```go
session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
	Agent: anthropic.BetaSessionNewParamsAgentUnion{
		OfString: anthropic.String(agent.ID),
	},
	EnvironmentID: environment.ID,
	Budget: anthropic.BetaManagedAgentsBudgetLimitParam{
		Type: anthropic.BetaManagedAgentsBudgetLimitTypeLimit,
		MaxListCost: anthropic.BetaMonetaryAmountParam{
			Amount:   "125",
			Currency: anthropic.BetaCurrencyUsd,
		},
	},
})
if err != nil {
	panic(err)
}
fmt.Println(session.ID, session.Budget.MaxListCost.Amount) // sesn_01... 125
```

--------------------------------

### Follow a run with Python SDK

Source: https://platform.claude.com/docs/en/managed-agents/workflow-runs

Use this Python SDK example to follow a session from message to answer. It tracks each run from workflow_run.created to workflow_run.status_ended, prints phases as they start, and answers agent.custom_tool_use events. It stops when no run is open and the session goes idle with end_turn, or on session termination. On idle with other stop reasons (except requires_action), it prints the reason and stops.

```python
open_runs: dict[str, str] = {}  # workflow_run_id -> run name
phase_names: dict[tuple[str, str], str] = {}  # (run ID, phase ID) -> phase name

# Open the stream first, then send the user message
with client.beta.sessions.events.stream(session_id) as stream:
    client.beta.sessions.events.send(
        session_id,
        events=[
            {
                "type": "user.message",
                "content": [
                    {
                        "type": "text",
                        "text": "Which contracts in /contracts have a change-of-control clause?",
                    },
                ],
            },
        ],
    )

    for event in stream:
        match event.type:
            case "workflow_run.created":
                open_runs[event.workflow_run_id] = event.name
                for phase in event.phases:
                    phase_names[event.workflow_run_id, phase.id] = phase.name
                print(f"Run started: {event.name}")
            case "workflow_run.phase_started":
                phase_id = event.workflow_run_phase_id
                key = (event.workflow_run_id, phase_id)
                print(f"  Phase: {phase_names.get(key, phase_id)}")
            case "workflow_run.status_ended":
                name = open_runs.pop(event.workflow_run_id, event.workflow_run_id)
                print(f"Run ended: {name} ({event.result.type})")
            case "agent.custom_tool_use":
                # Answer when the event arrives. A run's thread can wait on your
                # client while the session stays running.
                result = call_tool(event.name, event.input)
                try:
                    client.beta.sessions.events.send(
                        session_id,
                        events=[
                            {
                                "type": "user.custom_tool_result",
                                "custom_tool_use_id": event.id,
                                "content": [{"type": "text", "text": result}],
                            },
                        ],
                    )
                except anthropic.BadRequestError as error:
                    # The server refuses a result that comes too late, after it
                    # archived the call's thread. Keep following the run.
                    print(f"  Answer to {event.name} refused: {error.message}")
            case "session.status_idle":
                # Done when every run has ended and the agent has finished its turn
                if not open_runs and event.stop_reason.type == "end_turn":
                    break
                # An idle with requires_action waits on your client, so keep reading.
                # On any other stop reason, print it and stop.
                if event.stop_reason.type not in ("end_turn", "requires_action"):
                    print(f"Session idle: {event.stop_reason.type}")
                    break
            case "session.status_terminated":
                break
```

--------------------------------

### Create session with file resource (Go)

Source: https://platform.claude.com/docs/en/managed-agents/files

Use this Go code to create a session with a file resource mounted at /data.csv. The session is created using the client.Beta.Sessions.New method with the agent, environment ID, and resources parameters. The mount_path is optional, but the file will be accessible at /mnt/session/uploads/data.csv.

```go
session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
	Agent: anthropic.BetaSessionNewParamsAgentUnion{
		OfString: anthropic.String(agent.ID),
	},
	EnvironmentID: environment.ID,
	Resources: []anthropic.BetaSessionNewParamsResourceUnion{{
		OfFile: &anthropic.BetaManagedAgentsFileResourceParams{
			Type:      anthropic.BetaManagedAgentsFileResourceParamsTypeFile,
			FileID:    file.ID,
			MountPath: anthropic.String("/data.csv"),
		},
	}},
})
if err != nil {
	panic(err)
}
```

--------------------------------

### PHP: Create agent with domain lists

Source: https://platform.claude.com/docs/en/managed-agents/tools-web-restrictions

Creates a managed agent with web_search and web_fetch tool configs. The web_search config sets allowed_domains and user_location; the web_fetch config sets blocked_domains and max_content_tokens. The example then iterates over the agent's tools and prints the configs as JSON.

```php
use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401;
use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params;
use Anthropic\Beta\Agents\BetaManagedAgentsUserLocation;
use Anthropic\Beta\Agents\BetaManagedAgentsWebFetchToolConfigParams;
use Anthropic\Beta\Agents\BetaManagedAgentsWebSearchToolConfigParams;
// ...

$client = new Client();

$agent = $client->beta->agents->create(
    name: 'Research Agent',
    model: 'claude-opus-5-5',
    tools: [
        BetaManagedAgentsAgentToolset20260401Params::with(
            type: 'agent_toolset_20260401',
            configs: [
                BetaManagedAgentsWebSearchToolConfigParams::with(
                    allowedDomains: ['docs.example.com', 'arxiv.org'],
                    userLocation: BetaManagedAgentsUserLocation::with(
                        country: 'US',
                        timezone: 'America/Los_Angeles',
                    ),
                ),
                BetaManagedAgentsWebFetchToolConfigParams::with(
                    blockedDomains: ['ads.example.com'],
                    maxContentTokens: 50_000,
                ),
            ],
        ),
    ],
);

foreach ($agent->tools as $tool) {
    if ($tool instanceof BetaManagedAgentsAgentToolset20260401) {
        echo json_encode($tool->configs, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES), PHP_EOL;
    }
}
```

--------------------------------

### Create environment with cURL and extract ID

Source: https://platform.claude.com/docs/en/managed-agents/quickstart

Creates a cloud environment named 'quickstart-env' with limited networking and package managers allowed. The response is parsed with jq to extract the environment ID, which is printed to stdout. Requires the ANTHROPIC_API_KEY environment variable and the managed-agents beta header.

```bash
environment=$(
  curl -sS --fail-with-body https://api.anthropic.com/v1/environments \
    -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" \
    -d @- <<'EOF'
{
  "name": "quickstart-env",
  "config": {
    "type": "cloud",
    "networking": {"type": "limited", "allow_package_managers": true}
  }
}
EOF
)

ENVIRONMENT_ID=$(jq -er '.id' <<<"$environment")

echo "Environment ID: $ENVIRONMENT_ID"

```

--------------------------------

### Install ant CLI with Homebrew (macOS)

Source: https://platform.claude.com/docs/en/managed-agents/quickstart

Installs the ant CLI on macOS using Homebrew from the anthropics tap.

```bash
brew install anthropics/tap/ant
```

--------------------------------

### Start poller with ant beta:worker poll

Source: https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-workers

Starts the poller that claims work and invokes the spawn script for each work item.

```bash
ant beta:worker poll --on-work ./spawn.sh
```

--------------------------------

### Enable toolset and disable web_fetch with Go

Source: https://platform.claude.com/docs/en/managed-agents/tools

Use the Go SDK to create an agent with the toolset enabled and web_fetch disabled. The example includes error handling with panic.

```go
agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
	Name: "Coding Assistant",
	Model: anthropic.BetaManagedAgentsModelConfigParams{
		ID: "claude-opus-5-5",
	},
	Tools: []anthropic.BetaAgentNewParamsToolUnion{{
		OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
			Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
			Configs: []anthropic.BetaManagedAgentsAgentToolConfigParamsUnion{{
				OfWebFetch: &anthropic.BetaManagedAgentsWebFetchToolConfigParams{
					Enabled: anthropic.Bool(false),
				},
			}},
		},
	}},
})
if err != nil {
	panic(err)
}
_ = agent
```

--------------------------------

### Update agent model to claude-opus-5-5

Source: https://platform.claude.com/docs/en/managed-agents/migration

Update the model field on an existing agent definition to migrate to a new Claude model. The cURL example uses the API directly, the CLI example applies an agent.md file, and the other examples use the SDKs. The change takes effect on the next session you create.

```bash
curl -sS --fail-with-body "https://api.anthropic.com/v1/agents/$AGENT_ID?beta=true" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  --json "$(jq -n --argjson version "$AGENT_VERSION" '{version: $version, model: "claude-opus-5-5"}')"
```

```bash
ant apply agent.md
```

```markdown
---
name: Task Runner
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
---

You are a task automation agent. Complete the task you are given end to end.
```

```python
client.beta.agents.update(
    agent.id,
    version=agent.version,
    model="claude-opus-5-5",
)
```

```typescript
await client.beta.agents.update(agent.id, {
  version: agent.version,
  model: "claude-opus-5-5"
});
```

```csharp
await client.Beta.Agents.Update(agent.ID, new()
{
    Version = agent.Version,
    Model = BetaManagedAgentsModel.ClaudeOpus5_5,
});
```

```go
_, err = client.Beta.Agents.Update(ctx, agent.ID, anthropic.BetaAgentUpdateParams{
	Version: agent.Version,
	Model: anthropic.BetaManagedAgentsModelConfigParams{
		ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5,
	},
})
if err != nil {
	panic(err)
}
```

```java
client.beta().agents().update(
    agent.id(),
    AgentUpdateParams.builder()
        .version(agent.version())
        .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
        .build()
);
```

```php
$client->beta->agents->update(
    $agent->id,
    version: $agent->version,
    model: 'claude-opus-5-5',
);
```

```ruby
client.beta.agents.update(
  agent.id,
  version: agent.version,
  model: "claude-opus-5-5"
)
```

--------------------------------

### Set up AgentToolContext and build tools for the session tool runner

Source: https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-reference

Build the tool list for the session tool runner by setting up AgentToolContext and calling beta_agent_toolset_20260401 (TypeScript: betaAgentToolset20260401; Go: agenttoolset.BetaAgentToolset20260401). The Python and Go examples download skills to /workspace/skills/<name>/. The C#, Java, PHP, and Ruby SDKs do not currently support AgentToolContext.

```python
from anthropic.lib.tools.agent_toolset import (
    AgentToolContext,
    beta_agent_toolset_20260401,
)

async with AgentToolContext(
    workdir="/workspace", client=client, session_id=work.data.id
) as env:
    # skills downloaded to /workspace/skills/<name>/
    tools = beta_agent_toolset_20260401(env)
```

```typescript
import {
  setupSkills,
  betaAgentToolset20260401
} from "@anthropic-ai/sdk/tools/agent-toolset/node";

const ctx = { workdir: "/workspace", client, sessionId: work.data.id };
await setupSkills(ctx);
const tools = betaAgentToolset20260401(ctx);
```

```csharp
// AgentToolContext is not currently available in the C# SDK.
```

```go
env := &agenttoolset.AgentToolContext{Workdir: "/workspace"}
if err := env.SetupSkills(ctx, client, work.Data.ID); err != nil {
	panic(err)
}
// skills downloaded to /workspace/skills/<name>/
tools := agenttoolset.BetaAgentToolset20260401(env)
```

```java
// AgentToolContext is not currently available in the Java SDK.
```

```php
// AgentToolContext is not currently available in the PHP SDK.
```

```ruby
// AgentToolContext is not currently available in the Ruby SDK.
```

--------------------------------

### Start the worker with ant beta:worker poll

Source: https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes

Creates the working directory and starts the worker. The worker reads the exported environment variables and polls until stopped.

```bash
sudo mkdir -p /workspace && sudo chown "$USER" /workspace
ant beta:worker poll --workdir /workspace
```

--------------------------------

### Create session with budget in C#

Source: https://platform.claude.com/docs/en/managed-agents/sessions

Creates a session with a $1.25 budget using the C# SDK. The budget uses `BetaManagedAgentsBudgetLimitType.Limit` and `BetaCurrency.Usd`. The session ID and budget amount are printed.

```csharp
var session = await client.Beta.Sessions.Create(new()
{
    Agent = agent.ID,
    EnvironmentID = environment.ID,
    Budget = new()
    {
        Type = BetaManagedAgentsBudgetLimitType.Limit,
        MaxListCost = new() { Amount = "125", Currency = BetaCurrency.Usd },
    },
});
Console.WriteLine($"{session.ID} {session.Budget?.MaxListCost.Amount}");  // sesn_01... 125
```

--------------------------------

### Outcome evaluation start event

Source: https://platform.claude.com/docs/en/managed-agents/define-outcomes

Emitted once the grader starts an evaluation over one iteration loop. The iteration field is a 0-indexed revision counter: 0 is the first evaluation, 1 is the re-evaluation after the first revision, and so on.

```json
{
  "type": "span.outcome_evaluation_start",
  "id": "sevt_01def...",
  "outcome_id": "outc_01a...",
  "iteration": 0,
  "processed_at": "2026-03-25T14:01:45Z"
}
```

--------------------------------

### List and download session files with Go SDK

Source: https://platform.claude.com/docs/en/managed-agents/files

Use the Go SDK to list files scoped to a session and download a file. The list call requires the `managed-agents-2026-04-01` beta header. Files written to `/mnt/session/outputs/` appear shortly after the agent finishes writing them; if missing, list again after a short delay.

```go
files, err := client.Beta.Files.List(ctx, anthropic.BetaFileListParams{
	ScopeID: anthropic.String("sesn_abc123"),
	Betas:   []anthropic.AnthropicBeta{"managed-agents-2026-04-01"},
})
if err != nil {
	panic(err)
}
```

```go
resp, err := client.Files.Download(ctx, files.Data[0].ID, anthropic.FileDownloadParams{})
if err != nil {
	panic(err)
}
defer resp.Body.Close()
out, err := os.Create("output.txt")
if err != nil {
	panic(err)
}
defer out.Close()
if _, err := io.Copy(out, resp.Body); err != nil {
	panic(err)
}
```

--------------------------------

### Create a session with a GitHub repository resource

Source: https://platform.claude.com/docs/en/managed-agents/skills

Create a session that mounts a GitHub repository so its `.claude/skills` directory is scanned and skills become available. `mount_path` is optional and defaults to `/workspace/<repo-name>`. The same request is used for accessing GitHub; the repository must be trusted because its skills are loaded without review.

```bash
session_id=$(curl -fsS 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" \
  --data @- <<JSON | jq -r '.id'
{
  "agent": "$agent_id",
  "environment_id": "$environment_id",
  "resources": [
    {
      "type": "github_repository",
      "url": "https://github.com/org/repo",
      "mount_path": "/workspace/repo",
      "authorization_token": "ghp_your_github_token"
    }
  ]
}
JSON
)
```

```bash
SESSION_ID=$(ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID" \
  --transform id --raw-output <<'EOF'
resources:
  - type: github_repository
    url: https://github.com/org/repo
    mount_path: /workspace/repo
    authorization_token: ghp_your_github_token
EOF
)
```

```python
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "github_repository",
            "url": "https://github.com/org/repo",
            "mount_path": "/workspace/repo",
            "authorization_token": "ghp_your_github_token",
        },
    ],
)
```

```typescript
const session = await client.beta.sessions.create({
  agent: agent.id,
  environment_id: environment.id,
  resources: [
    {
      type: "github_repository",
      url: "https://github.com/org/repo",
      mount_path: "/workspace/repo",
      authorization_token: "ghp_your_github_token",
    },
  ],
});
```

--------------------------------

### Create agent with always_ask policy (Go)

Source: https://platform.claude.com/docs/en/managed-agents/permission-policies

Use the Go SDK to create an agent with the agent_toolset_20260401 toolset and set the permission policy to always_ask. The example includes error handling with panic.

```go
agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
	Name: "Coding Assistant",
	Model: anthropic.BetaManagedAgentsModelConfigParams{
		ID: "claude-opus-5-5",
	},
	Tools: []anthropic.BetaAgentNewParamsToolUnion{{
		OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
			Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
			DefaultConfig: anthropic.BetaManagedAgentsAgentToolsetDefaultConfigParams{
				PermissionPolicy: anthropic.BetaManagedAgentsAgentToolsetDefaultConfigParamsPermissionPolicyUnion{
					OfAlwaysAsk: &anthropic.BetaManagedAgentsAlwaysAskPolicyParam{
						Type: anthropic.BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk,
					},
				},
			},
		},
	}},
})
if err != nil {
	panic(err)
}
_ = agent
```

--------------------------------

### Upload a file with the Files API

Source: https://platform.claude.com/docs/en/managed-agents/files

Upload a file using the Files API and print its ID. The cURL example uses the base URL and auth array variables; the CLI example uses the `ant files upload` command with `--transform id --raw-output` to extract the file ID. The SDK examples use the `files.upload` method with a file path or stream, and print the returned file ID.

```bash
file=$(curl --fail-with-body -sS "${auth[@]}" \
  "${base_url}/files" \
  -F file=@data.csv)
FILE_ID=$(jq -er '.id' <<<"${file}")
```

```bash
FILE_ID=$(ant files upload --file data.csv --transform id --raw-output)
```

```python
file = client.files.upload(file=Path("data.csv"))
print(f"File ID: {file.id}")
```

```typescript
const file = await client.files.upload({
  file: await toFile(readFile("data.csv"), "data.csv", { type: "text/csv" }),
});
console.log(`File ID: ${file.id}`);
```

```csharp
await using var stream = File.OpenRead(csvPath);
var file = await client.Files.Upload(new() { File = stream });
Console.WriteLine($"File ID: {file.ID}");
```

```go
csvFile, err := os.Open("data.csv")
if err != nil {
	panic(err)
}
defer csvFile.Close()

file, err := client.Files.Upload(ctx, anthropic.FileUploadParams{
	File: csvFile,
})
if err != nil {
	panic(err)
}
fmt.Printf("File ID: %s\n", file.ID)
```

```java
var file = client.files().upload(
    FileUploadParams.builder().file(dataCsv).build()
);
IO.println("File ID: " + file.id());
```

```php
$file = $client->files->upload(
    file: FileParam::fromResource(fopen($csvPath, 'r'), filename: 'data.csv', contentType: 'text/csv'),
);
echo "File ID: {$file->id}\n";
```

```ruby
file = client.files.upload(file: Pathname(csv_path))
puts "File ID: #{file.id}"
```

--------------------------------

### Create agent with Go SDK

Source: https://platform.claude.com/docs/en/managed-agents/agent-setup

Uses the Go SDK's `client.Beta.Agents.New` to create an agent with the agent toolset. Requires a configured client. Panics on error.

```go
agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
	Name: "Coding Assistant",
	Model: anthropic.BetaManagedAgentsModelConfigParams{
		ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5,
	},
	System: anthropic.String("You are a helpful coding agent."),
	Tools: []anthropic.BetaAgentNewParamsToolUnion{{
		OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
			Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
		},
	}},
})
if err != nil {
	panic(err)
}
```

--------------------------------

### TypeScript webhook handler setup

Source: https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-workers

TypeScript webhook handler setup that creates an Anthropic client and an AbortController for graceful shutdown. Requires the ANTHROPIC_ENVIRONMENT_KEY and ANTHROPIC_ENVIRONMENT_ID environment variables. Call shutdown.abort() on SIGTERM/SIGINT to allow in-flight work to finish.

```typescript
import Anthropic from "@anthropic-ai/sdk";

const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;
const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
const client = new Anthropic({
  authToken: environmentKey
});
// Call shutdown.abort() from the host's SIGTERM/SIGINT handler, alongside closing the server,
// then wait for in-flight handle() calls before exiting: the abort lets a running work item
// upload changed memory files and remove its store directories first.
export const shutdown = new AbortController();
```
Tokens:
Raw