---
title: "列出 Agent"
method: GET
path: "/agent/managed/v1/agents"
tags: ["Managed Agents - Agent"]
---

# 列出 Agent

`GET /agent/managed/v1/agents`

## Request

- Base URL: `https://agent-api.bigmodel.cn/api`
- URL: `https://agent-api.bigmodel.cn/api/agent/managed/v1/agents`
- Auth: HTTP bearer

分页列出当前账号可访问的 Agent。默认排除已归档资源，可通过 `include_archived` 包含。

<Accordion title="使用说明">

新协议默认排除已归档 Agent，include_archived 可显式指定。

</Accordion>

## Query parameters

- `limit` integer
- `order` 'asc' | 'desc'
- `page` string

## Headers

- `zai-version` '2026-05-26', required
- `zai-beta` string, required

## Response `200`

请求成功。

- ManagedAgentPage
  - `data` ManagedAgent[], required
    - `id` string, required: Agent ID。
    - `type` 'agent', required
    - `name` string, required
    - `description` string, nullable, required: 用途说明。
    - `model` ManagedModelResponse, required
      - `id` string, required
      - `effort` union: 新协议返回 {type:档位}，旧协议返回字符串。
        - object
          - `type` 'low' | 'high' | 'max', required
        - 'low' | 'high' | 'max'
      - `speed` 'standard', required
    - `system` string, nullable, required: 系统提示词。
    - `tools` ManagedAgentToolsetResponse[], required
      - union
        - object
          - `type` 'agent_toolset_20260601', required
          - `default_config` ManagedToolDefaultConfigResponse, required
            - `enabled` boolean, required
            - `permission_policy` ManagedPermissionPolicy, required
              - …
          - `configs` ManagedBuiltinToolConfigResponse[], required
            - union
              - …
        - object
          - `type` 'mcp_toolset', required
          - `mcp_server_name` string, required
          - `default_config` ManagedToolDefaultConfigResponse, required
            - `enabled` boolean, required
            - `permission_policy` ManagedPermissionPolicy, required
              - …
          - `configs` ManagedMcpToolConfigResponse[], required
            - `name` string, required
            - `enabled` boolean, required
            - `permission_policy` ManagedPermissionPolicy, required
              - …
        - object
          - `type` 'custom', required
          - `name` string, required
          - `description` string, required
          - `input_schema` ManagedCustomToolInputSchema, required
            - `type` 'object', required: 固定为 object。
            - `properties` object: 工具输入字段的 JSON Schema；省略时表示未声明属性。
            - `required` string[]: 必填输入字段名；省略时无必填字段。
    - `skills` ManagedSkillReference[], required
      - `type` 'custom' | 'zai', required: custom 表示当前所有者创建的 Skill；zai 表示平台内置 Skill。
      - `skill_id` string, required: Skill ID；必须存在且当前身份可访问。
      - `version` string, nullable: 可省略/null/latest。新协议在 Session 创建/Deployment 触发时固定，旧协议每次沙箱启动解析；具体 ID 固定对应版本。
    - `mcp_servers` ManagedMcpServer[], required
      - `type` 'url', required: 当前只支持 url。
      - `name` string, required: Server 名称，长度 1–255；同一 mcp_servers 数组内不得重复。
      - `url` string, uri, required: 公开 HTTPS Streamable HTTP URL；不得包含凭据、fragment、空 query 或旧式 SSE 路径。
    - `metadata` ManagedMetadata, required: 客户端自定义元数据；省略时默认为空对象。最多 16 个键，键名长度不超过 64 字符，值必须是长度不超过 512 字符的字符串。
    - `version` integer, required
    - `created_at` string, date-time, required: 创建时间。
    - `updated_at` string, date-time, required: 更新时间。
    - `multiagent` ManagedMultiagent, nullable: 可选，Multi Agent 主配置。null 清空，创建/更新时固定成员版本；Session override 不支持改 Agent 列表。
      - `type` 'coordinator', required
      - `agents` ManagedMultiagentEntry[], required: 按 Agent ID 计最多 20 个唯一成员；Advisor 至多一个；成员不得携带自己的 Agent 列表。
        - union
          - object
            - `type` 'agent', required
            - `id` string, required
            - `version` integer
          - object
            - `type` 'self', required
          - object
            - `type` 'advisor', required
            - `model` string, required
    - `archived_at` string, nullable, required: 归档时间；未归档时为 null。
  - `next_page` string, nullable, required

## Other responses

- `default`: 请求失败。

## Changes

- **2026-11-03** `7fd61aa7f811`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/bigmodel/apis/zhipu-ai-api/changes/agent/managed/v1/agents/get.md)

---

[API](https://skmtc.dev/bigmodel/apis/zhipu-ai-api.md) - [All operations](https://skmtc.dev/bigmodel/apis/zhipu-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bigmodel/apis/zhipu-ai-api/revisions/f2be7c0fcbb9?raw)