> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 调用 Agent

> Agent 模式调用 — 支持工具调用、自动规划，SSE 流式响应

Zeus 的核心入口。启动一次 Agent 对话，支持 MCP/OAuth 工具、知识库 RAG、记忆、沙盒代码执行、Skills、HITL 审批等完整能力。

返回 **SSE 流式响应**，消息格式参见 [Streaming](/zh/ai-backend/messages/Streaming)。

<ParamField header="Authorization" type="string" required>
  Bearer JWT Token（`user_id` 从中自动提取，用于 Store 隔离）
</ParamField>

### 核心参数

<ParamField body="message" type="string" required>
  用户消息内容
</ParamField>

<ParamField body="llm_config" type="object" required>
  LLM 模型配置（来自前端 localStorage）

  <Expandable title="llm_config">
    <ParamField body="baseUrl" type="string" required>
      API 基础 URL
    </ParamField>

    <ParamField body="apiKey" type="string" required>
      API 密钥
    </ParamField>

    <ParamField body="modelName" type="string" required>
      模型名称（如 `gpt-4o`、`claude-sonnet-4-20250514`）
    </ParamField>

    <ParamField body="temperature" type="number" default="0.7">
      温度参数
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="session_id" type="string">
  会话 ID，用于 Checkpointer 持久化。不传则自动生成
</ParamField>

<ParamField body="mode" type="string" default="agent">
  对话模式：

  * `agent` — 完整功能模式（默认）
  * `ask` — 只读问答模式，禁用写入工具
  * `plan` — 交互式规划模式
</ParamField>

### 工具配置

<ParamField body="tools" type="array" default="[]">
  统一的工具列表。每个工具通过 `type` 字段区分类型

  <Expandable title="MCP 工具 (type: mcp)">
    <ParamField body="type" type="string" required>
      `mcp`
    </ParamField>

    <ParamField body="name" type="string" required>
      MCP 服务器名称
    </ParamField>

    <ParamField body="base_url" type="string" required>
      MCP 服务器 URL
    </ParamField>

    <ParamField body="transport_type" type="string" default="streamable_http">
      传输类型
    </ParamField>

    <ParamField body="api_key" type="string">
      API 密钥（可选）
    </ParamField>

    <ParamField body="headers" type="object">
      自定义 HTTP headers（可选）
    </ParamField>
  </Expandable>

  <Expandable title="OAuth 工具 (type: oauth)">
    <ParamField body="type" type="string" required>
      `oauth`
    </ParamField>

    <ParamField body="name" type="string" required>
      工具名称：`github`、`gmail`、`google_drive`、`slack`、`notion`
    </ParamField>

    <ParamField body="access_token" type="string" required>
      OAuth access token
    </ParamField>

    <ParamField body="refresh_token" type="string">
      OAuth refresh token（可选）
    </ParamField>

    <ParamField body="expires_at" type="number">
      Token 过期时间戳（可选）
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="sandbox_mode" type="string" default="cloud">
  代码执行环境模式：

  * `"cloud"` — 使用云沙盒（E2B / OpenSandbox / Daytona）
  * `"local"` — 使用本地容器（Docker / Apple Containerization），需配合 `working_directory`
  * `"none"` — 不启用代码执行环境
</ParamField>

<ParamField body="enable_web_search" type="boolean" default="false">
  是否启用 Web Search Tool（Tavily + DuckDuckGo）
</ParamField>

### RAG & Memory

<ParamField body="knowledge_base_ids" type="array" default="[]">
  知识库 ID 列表。传入后自动注册 `search_knowledge_base` 工具
</ParamField>

<ParamField body="enable_memory" type="boolean" default="false">
  是否启用 Memory Tool（长期记忆读写）
</ParamField>

### Skills

<ParamField body="skills" type="object">
  Skills 激活配置

  <Expandable title="skills">
    <ParamField body="skill_names" type="array">
      显式激活的 Skill 名称列表。为空则使用自动匹配
    </ParamField>

    <ParamField body="auto_match" type="boolean" default="true">
      是否根据消息内容自动匹配 Skills
    </ParamField>

    <ParamField body="max_skills" type="number" default="3">
      最多同时激活的 Skill 数量
    </ParamField>
  </Expandable>
</ParamField>

### 上下文

<ParamField body="chat_history" type="array" default="[]">
  历史对话消息列表 `[{ role, content, timestamp? }]`
</ParamField>

<ParamField body="resource_files" type="array" default="[]">
  资源文件列表 `[{ name, content, type }]`（如 Markdown 提示词）
</ParamField>

<ParamField body="sandbox_files" type="array" default="[]">
  已上传到沙盒的文件 `[{ name, path, type, size? }]`
</ParamField>

<ParamField body="chat_attachments" type="array" default="[]">
  用户添加的聊天附件 `[{ id, name, size, type, content }]`
</ParamField>

### HITL 审批

<ParamField body="hitl_config" type="object">
  工具中断配置（Human-in-the-Loop）

  <Expandable title="hitl_config">
    <ParamField body="tools" type="object" default="{}">
      工具名 → 中断配置的映射 `{ enabled, requires_interrupt, allowed_decisions, timeout }`
    </ParamField>

    <ParamField body="default_requires_interrupt" type="boolean" default="true">
      未在配置中的工具是否默认需要中断
    </ParamField>

    <ParamField body="allowlist" type="array" default="[]">
      白名单工具列表 — 在此列表中的工具自动执行，不中断
    </ParamField>

    <ParamField body="default_timeout" type="number" default="60">
      默认超时时间（秒）
    </ParamField>
  </Expandable>
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://zeus-api.agentspro.cn/api/agent/invoke \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "message": "帮我分析 sales.csv 的数据趋势",
      "llm_config": {
        "baseUrl": "https://api.openai.com/v1",
        "apiKey": "sk-...",
        "modelName": "gpt-4o",
        "temperature": 0.7
      },
      "session_id": "sess_456",
      "mode": "agent",
      "sandbox_mode": "cloud",
      "knowledge_base_ids": ["kb_789"],
      "enable_memory": true,
      "tools": [
        {
          "type": "mcp",
          "name": "tavily",
          "base_url": "https://mcp.tavily.com/mcp",
          "api_key": "tvly-..."
        }
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```text SSE Stream theme={null}
  data: {"type": "message_chunk", "content": "我来帮你分析"}
  data: {"type": "message_chunk", "content": " sales.csv 的数据趋势"}
  data: {"type": "tool_call", "tool_name": "sandbox_exec", "tool_args": {...}}
  data: {"type": "tool_result", "tool_name": "sandbox_exec", "result": "..."}
  data: {"type": "message_chunk", "content": "根据分析结果..."}
  data: {"type": "done", "session_id": "sess_456"}
  ```
</ResponseExample>