快速入門

建構第一步

開始使用 Claude Managed Agents

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

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

核心概念

Concept	Description
Agent	The model, system prompt, tools, MCP servers, and skills
Environment	Configuration for where sessions run: an Anthropic-managed cloud container, or a self-hosted sandbox on your own infrastructure
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)

先決條件

一個 Anthropic Console 帳戶
一個 API 金鑰

安裝 CLI

確認安裝：

ant --version

安裝 SDK

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

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

建立您的第一個工作階段

所有 Managed Agents API 請求都需要 managed-agents-2026-04-01 beta 標頭。SDK 會自動設定 beta 標頭。

建立代理程式
建立一個定義模型、系統提示和可用工具的代理程式。
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}'
agent_toolset_20260401 工具類型可啟用完整的預建代理程式工具集（bash、檔案操作、網路搜尋等）。請參閱工具以取得完整清單和每個工具的設定選項。
儲存返回的 agent.id。您將在每個建立的工作階段中參照它。
建立環境
環境定義了代理程式執行所在的容器。
ant beta:environments create \ --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:
    # 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:
                    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.

運作原理

當您傳送使用者事件時，Claude Managed Agents 會：

佈建容器： 您的環境設定決定了容器的建置方式。
執行代理程式迴圈： Claude 根據您的訊息決定使用哪些工具
執行工具： 檔案寫入、bash 命令和其他工具呼叫在容器內執行
串流事件： 您會在代理程式工作時收到即時更新
進入閒置： 當代理程式沒有更多事情要做時，會發出 session.status_idle 事件

後續步驟

建立可重複使用的版本化代理程式設定

自訂網路和容器設定

為您的代理程式啟用特定工具

處理事件並在執行過程中引導代理程式

Was this page helpful?

建構第一步

開始使用 Claude Managed Agents

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

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

核心概念

Concept	Description
Agent	The model, system prompt, tools, MCP servers, and skills
Environment	Configuration for where sessions run: an Anthropic-managed cloud container, or a self-hosted sandbox on your own infrastructure
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)

先決條件

一個 Anthropic Console 帳戶
一個 API 金鑰

安裝 CLI

確認安裝：

ant --version

安裝 SDK

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

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

建立您的第一個工作階段

所有 Managed Agents API 請求都需要 managed-agents-2026-04-01 beta 標頭。SDK 會自動設定 beta 標頭。

建立代理程式
建立一個定義模型、系統提示和可用工具的代理程式。
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}'
agent_toolset_20260401 工具類型可啟用完整的預建代理程式工具集（bash、檔案操作、網路搜尋等）。請參閱工具以取得完整清單和每個工具的設定選項。
儲存返回的 agent.id。您將在每個建立的工作階段中參照它。
建立環境
環境定義了代理程式執行所在的容器。
ant beta:environments create \ --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:
    # 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:
                    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.

運作原理

當您傳送使用者事件時，Claude Managed Agents 會：

佈建容器： 您的環境設定決定了容器的建置方式。
執行代理程式迴圈： Claude 根據您的訊息決定使用哪些工具
執行工具： 檔案寫入、bash 命令和其他工具呼叫在容器內執行
串流事件： 您會在代理程式工作時收到即時更新
進入閒置： 當代理程式沒有更多事情要做時，會發出 session.status_idle 事件

後續步驟

建立可重複使用的版本化代理程式設定

自訂網路和容器設定

為您的代理程式啟用特定工具

處理事件並在執行過程中引導代理程式

Was this page helpful?