快速入门

本指南将带你完成：创建一个 Agent、配置运行环境、启动会话、流式接收响应，并下载产出文件。全程只需要 curl 和一个智谱开放平台 API Key，大约 5 分钟。

核心概念

概念	说明
Agent	模型、系统提示词、工具、MCP 服务器和 Skills 的组合定义
Environment	会话运行环境的声明式配置：软件包与网络策略
Session	在环境中运行的一个 Agent 实例，执行任务并产出结果
Events	你的应用与 Agent 之间交换的消息（用户输入、Agent 回复、工具调用、状态更新）

前置条件

一个智谱开放平台账号
一个智谱开放平台 API Key

配置鉴权

Managed Agents 是标准的 HTTP + SSE 接口，任何语言都可以直接调用。先把智谱开放平台 API Key 和基础地址设置为环境变量：

export ZHIPUAI_API_KEY="your-api-key-here"
export BASE_URL="https://agent-api.bigmodel.cn/api/agent/managed"

所有 Managed Agents 请求都需要携带版本头 zai-version: 2026-05-26 和 Beta 头 zai-beta: managed-agents-2026-05-26。

创建你的第一个会话

创建 Agent

创建一个 Agent，定义模型、系统提示词和可用工具：

agent=$(
  curl -sS "$BASE_URL/v1/agents" \
    -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
    -H "zai-version: 2026-05-26" \
    -H "zai-beta: managed-agents-2026-05-26" \
    -H "content-type: application/json" \
    -d @- <<'EOF'
{
  "name": "Coding Assistant",
  "model": "glm-5.3",
  "system": "You are a helpful coding assistant. Write clean, well-documented code.",
  "tools": [
    {"type": "agent_toolset_20260601"}
  ]
}
EOF
)

AGENT_ID=$(jq -er '.id' <<<"$agent")
echo "Agent ID: $AGENT_ID"

agent_toolset_20260601 这个工具类型会启用全套内置 Agent 工具（bash、文件操作等）。完整列表与逐项配置见工具。记下返回的 agent.id，后面每次创建会话都要引用它。

省略 tools 不会自动启用内置工具。上面的示例已显式加入 agent_toolset_20260601。

创建 Environment

Environment 定义 Agent 运行所在的沙箱：

environment=$(
  curl -sS "$BASE_URL/v1/environments" \
    -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
    -H "zai-version: 2026-05-26" \
    -H "zai-beta: managed-agents-2026-05-26" \
    -H "content-type: application/json" \
    -d @- <<'EOF'
{
  "name": "quickstart-env",
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"}
  }
}
EOF
)

ENVIRONMENT_ID=$(jq -er '.id' <<<"$environment")
echo "Environment ID: $ENVIRONMENT_ID"

记下返回的 environment.id。你可以在多个会话中复用同一个 Environment；需要预装软件包或收紧网络策略时，见配置运行环境。

启动 Session

创建一个会话，引用上面的 Agent 和 Environment：

session=$(
  curl -sS "$BASE_URL/v1/sessions" \
    -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
    -H "zai-version: 2026-05-26" \
    -H "zai-beta: managed-agents-2026-05-26" \
    -H "content-type: application/json" \
    -d @- <<EOF
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "title": "Quickstart session"
}
EOF
)

SESSION_ID=$(jq -er '.id' <<<"$session")
echo "Session ID: $SESSION_ID"

订阅事件并发送消息

先订阅 SSE，再发消息。流只推送连接建立之后的事件，发消息前未打开流会错过实时进展。打开一个 SSE 流订阅实时事件（保持这个终端不退出）：

curl -N "$BASE_URL/v1/sessions/$SESSION_ID/events/stream" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26"

然后在另一个终端发送用户消息事件：

curl -sS "$BASE_URL/v1/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26" \
  -H "content-type: application/json" \
  -d @- <<'EOF'
{
  "events": [
    {
      "type": "user.message",
      "content": [
        {
          "type": "text",
          "text": "Create a Python script that generates the first 20 Fibonacci numbers and saves them to /mnt/session/outputs/fibonacci.txt"
        }
      ]
    }
  ]
}
EOF

Agent 会编写一个 Python 脚本、在沙箱里运行它、并把结果写到产出目录。终端 1 里会依次收到类似这些事件：

event: agent.message
data: {"type":"agent.message","content":[{"type":"text","text":"I'll create a Python script ..."}], ...}

event: agent.tool_use
data: {"type":"agent.tool_use","name":"write", ...}

event: agent.tool_use
data: {"type":"agent.tool_use","name":"bash", ...}

event: session.status_idle
data: {"type":"session.status_idle", ...}

在你的应用代码里，通常只需要处理三类事件：agent.message（拼接文本展示给用户）、agent.tool_use（展示 Agent 正在做什么）、session.status_idle（本轮工作完成）。完整事件类型见事件与流式输出。

下载产出文件

session.status_idle 表示本轮结束。Agent 写入 /mnt/session/outputs 的文件会被编目，可用 Files API 列出并下载：

files=$(curl -sS "$BASE_URL/v1/files?scope_id=$SESSION_ID" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26")

FILE_ID=$(jq -er '.data[0].id' <<<"$files")
echo "Output file: $FILE_ID"

curl -sS -L "$BASE_URL/v1/files/$FILE_ID/content" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26" \
  -o fibonacci.txt

输入材料与产出文件的路径约定见文件。

背后发生了什么

当你发送一个用户事件时，Managed Agents 会：

供给沙箱：按你的 Environment 配置构建并启动运行环境。
运行 Agent 循环：模型根据你的消息自主决定使用哪些工具。
执行工具：文件写入、bash 命令等都在沙箱内执行。
流式推送事件：Agent 工作过程中你实时收到进展更新。
进入空闲：Agent 完成本轮工作后发出 session.status_idle 事件，等待你的下一条消息。
取回产出：写在 /mnt/session/outputs 的文件可按会话列出并下载。

会话是有状态的：沙箱文件系统和对话历史都会保留。你可以在同一个会话里继续发送消息，Agent 会带着完整上下文继续工作。

下一步

定义 Agent

创建可复用、带版本的 Agent

配置运行环境

自定义软件包与网络策略

工具

为 Agent 启用或限制特定工具

事件与流式输出

处理事件、在执行途中引导 Agent

最佳实践

客服、数据分析等常见配法

定时任务

按 cron 计划周期性运行 Agent

开始使用

定义 Agent

配置运行环境

运行会话

上下文与记忆

自动化

参考

核心概念

前置条件

配置鉴权

创建你的第一个会话

背后发生了什么

下一步

定义 Agent

配置运行环境

工具

事件与流式输出

最佳实践

定时任务

​核心概念

​前置条件

​配置鉴权

​创建你的第一个会话

​背后发生了什么

​下一步

定义 Agent

配置运行环境

工具

事件与流式输出

最佳实践

定时任务

核心概念

前置条件

配置鉴权

创建你的第一个会话

背后发生了什么

下一步