智谱智能体 API 怎么调用？选择 agent_id、发送消息并核对对话 ID

智谱智能体 API 面向已经配置好的智能体，调用时需要指定 agent_id，它与直接向普通模型发送 Chat Completions 请求、让模型做 Function Calling 不是同一个接口。第一次接入可以先关闭流式输出，用一条用户消息跑通同步请求，再核对返回的对话 ID。

调用前准备 API Key 和 agent_id

• 先在本机设置 ZHIPU_API_KEY 环境变量，再准备真实可用的 agent_id。
• 从官方当前列出的可用智能体或你的控制台配置中复制 agent_id，不要凭空编造。
• 准备一条能明确验收的问题。第一次请求先用无敏感信息、无外部写入动作的内容。

智谱的智能体对话官方文档给出的地址是 POST https://open.bigmodel.cn/api/v1/agents。请求使用 Bearer 鉴权，agent_id 和至少一条 messages 为必填项；stream 默认是 false。不同智能体需要的 custom_variables 不同，应以该智能体的配置为准，不要照搬其他智能体的变量。

发送第一条同步消息

下面用 Python 的 requests 发送最小请求。示例里的 agent_id 是占位符，运行前必须替换。

import json
import os

import requests

api_key = os.environ["ZHIPU_API_KEY"]
agent_id = "请替换为真实可用的_agent_id"

response = requests.post(
    "https://open.bigmodel.cn/api/v1/agents",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "agent_id": agent_id,
        "messages": [
            {"role": "user", "content": "请用三点说明你的主要能力。"}
        ],
        "stream": False,
    },
    timeout=60,
)

print("HTTP", response.status_code)
response.raise_for_status()
data = response.json()
print(json.dumps(data, ensure_ascii=False, indent=2))

不要把 API Key 写进代码、截图或日志。若要保存响应用于排错，应先删除密钥、个人信息和业务数据。

核对 agent_id、回答和对话 ID

HTTP 200 只说明服务器接受并处理了请求，还要检查返回结构：

1. 确认响应能解析为 JSON。
2. 请求成功后，先核对响应里的 agent_id 与请求一致，再确认 conversation_id 为非空字符串。
3. 检查 choices 是否存在可读回答，并判断内容是否回应了刚才的问题。
4. 保存 id、conversation_id 和原始响应，方便排错。usage 可用于记录本次用量，但不能只凭该字段自行推算或承诺最终费用。

可把这几个检查写成断言；任一字段缺失时，将本次结果记为失败或待确认，不要继续显示“调用成功”。

用对话历史接口复查 conversation_id

官方的对话历史文档提供 POST https://open.bigmodel.cn/api/v1/agents/conversation。把首次响应中的同一组 agent_id 和 conversation_id 发给该接口，可进一步核对这次对话是否能被正确查询。

history = requests.post(
    "https://open.bigmodel.cn/api/v1/agents/conversation",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "agent_id": agent_id,
        "conversation_id": data["conversation_id"],
    },
    timeout=60,
)

print("history HTTP", history.status_code)
history.raise_for_status()
print(json.dumps(history.json(), ensure_ascii=False, indent=2))

历史查询通过的标准是接口返回成功，而且返回内容对应刚才的智能体与对话。不要只看“有 JSON 返回”就认定对话 ID 正确。

常见失败与处理边界

需要流式输出时再把 stream 改为 true，并按流式事件逐段处理；不能继续把整个响应当成一次普通 JSON 解析。

本示例的实测范围

本文依据 2026-10-01 可访问的智谱官方文档整理，未使用你的 API Key 发起真实智能体请求；示例中的 agent_id 和问题均为占位内容，需在你的账号与智能体配置中替换。