開始使用 Claude Managed Agents

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

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

核心概念

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

先決條件

一個 Claude Console 帳戶
一組 API 金鑰

安裝 CLI

brew install anthropics/tap/ant

對於 Linux 環境，請直接下載發行版二進位檔。

VERSION=1.39.0
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
case $(uname -m) in
  x86_64) ARCH=amd64 ;;
  aarch64) ARCH=arm64 ;;
esac
curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${VERSION}/ant_${VERSION}_${OS}_${ARCH}.tar.gz" \
  | sudo tar -xz -C /usr/local/bin ant

您可以在 GitHub 發行頁面找到所有發行版本。

您也可以使用 go install 從原始碼安裝 CLI。需要 Go 1.25 或更新版本。

go install github.com/anthropics/anthropic-cli/cmd/ant@latest

二進位檔會放置於 $(go env GOPATH)/bin。如果尚未加入，請將其加入您的 PATH：

export PATH="$PATH:$(go env GOPATH)/bin"

檢查安裝：

ant --version

安裝 SDK

pip install anthropic

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

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

建立您的第一個工作階段

1
建立代理
建立一個定義模型、「system prompt」（系統提示）與可用工具的代理。
ant apply coding-assistant.md
coding-assistant.md
--- name: Coding Assistant model: claude-opus-5-5 tools: - type: agent_toolset_20260401 --- You are a helpful coding assistant. Write clean, well-documented code.
ant apply 會印出代理的 ID，並將其記錄在 claude-lock.json 中。您建立的每個工作階段都會參照它。
agent_toolset_20260401 工具類型會啟用完整的預建代理工具集（bash、檔案操作、網頁搜尋等）。如需完整清單與各工具的設定選項，請參閱工具。
2
建立環境
環境定義了您的代理執行所在的「sandbox」（沙箱）。
ant apply environment.yaml
environment.yaml
# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json name: quickstart-env config: type: cloud networking: type: limited allow_package_managers: true
ant apply 也會將環境的 ID 記錄在 claude-lock.json 中。若要以單一指令同時建立代理與環境，請傳入兩個檔案：ant apply coding-assistant.md environment.yaml。
若要在您自己的基礎架構上執行沙箱，而非使用雲端沙箱，請參閱自行託管的沙箱。

啟動工作階段

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

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:
    # 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

代理會撰寫一個 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.