開始使用 Claude Managed Agents

建立您的第一個自主代理。

本指南將引導您建立代理、設定環境、啟動工作階段，以及串流代理回應。

核心概念

概念	說明
Agent（代理）	模型、系統提示、工具、MCP 伺服器與技能
Environment（環境）	工作階段執行位置的設定：由 Anthropic 管理的雲端沙箱，或在您自己的基礎設施上自行託管的沙箱
Session（工作階段）	在環境中執行的代理實例，負責執行特定任務並產生輸出
Events（事件）	您的應用程式與代理之間交換的訊息（使用者輪次、工具結果、狀態更新）

先決條件

一個 Claude Console 帳戶
一組 API 金鑰

安裝 CLI

brew install anthropics/tap/ant

檢查安裝：

ant --version

安裝 SDK

pip install anthropic

將您的 API 金鑰設定為環境變數：

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

建立您的第一個工作階段

1
建立代理
建立一個定義模型、「system prompt」（系統提示）與可用工具的代理。
AGENT_ID=$(ant beta:agents create --transform id --raw-output < coding-assistant.agent.yaml) echo "Agent ID: $AGENT_ID"
coding-assistant.agent.yaml
name: Coding Assistant model: id: claude-opus-5 system: You are a helpful coding assistant. Write clean, well-documented code. tools: - type: agent_toolset_20260401
agent_toolset_20260401 工具類型會啟用完整的預建代理工具集（bash、檔案操作、網頁搜尋等）。請參閱工具以取得完整清單與各工具的設定選項。
儲存回傳的 agent.id。您將在建立的每個工作階段中參照它。
2
建立環境
環境定義了代理執行所在的沙箱。
ENVIRONMENT_ID=$(ant beta:environments create --transform id --raw-output < quickstart.environment.yaml) echo "Environment ID: $ENVIRONMENT_ID"
quickstart.environment.yaml
name: quickstart-env config: type: cloud networking: type: unrestricted
儲存回傳的 environment.id。您將在建立的每個工作階段中參照它。
若要在您自己的基礎設施上執行沙箱，而非使用雲端沙箱，請參閱自行託管的沙箱。

啟動工作階段

建立一個參照您的代理與環境的工作階段。

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

print(f"Session ID: {session.id}")

傳送訊息並串流回應

開啟串流、傳送使用者事件，然後在事件抵達時加以處理：

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": "Create a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt",
                    },
                ],
            },
        ],
    )

    # 處理串流事件
    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

代理會撰寫一個 Python 腳本、在沙箱中執行它，並驗證輸出檔案已建立。您的輸出會類似如下：

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.