> ## 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.

# Invoke Agent

> Agent mode invocation — supports tool calling, automatic planning, and SSE streaming response

The core entry point for Zeus. Starts an Agent conversation with full capabilities including MCP/OAuth tools, knowledge base RAG, memory, sandbox code execution, Skills, HITL approval, and more.

Returns an **SSE streaming response**. See [Streaming](/en/ai-backend/messages/Streaming) for message format details.

<ParamField header="Authorization" type="string" required>
  Bearer JWT Token (`user_id` is automatically extracted for store isolation)
</ParamField>

### Core Parameters

<ParamField body="message" type="string" required>
  User message content
</ParamField>

<ParamField body="llm_config" type="object" required>
  LLM model configuration (sourced from the frontend localStorage)

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

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

    <ParamField body="modelName" type="string" required>
      Model name (e.g. `gpt-4o`, `claude-sonnet-4-20250514`)
    </ParamField>

    <ParamField body="temperature" type="number" default="0.7">
      Temperature parameter
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="session_id" type="string">
  Session ID for Checkpointer persistence. Auto-generated if not provided
</ParamField>

<ParamField body="mode" type="string" default="agent">
  Conversation mode:

  * `agent` — Full capability mode (default)
  * `ask` — Read-only Q\&A mode, write tools disabled
  * `plan` — Interactive planning mode
</ParamField>

### Tool Configuration

<ParamField body="tools" type="array" default="[]">
  Unified tool list. Each tool is distinguished by its `type` field

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

    <ParamField body="name" type="string" required>
      MCP server name
    </ParamField>

    <ParamField body="base_url" type="string" required>
      MCP server URL
    </ParamField>

    <ParamField body="transport_type" type="string" default="streamable_http">
      Transport type
    </ParamField>

    <ParamField body="api_key" type="string">
      API key (optional)
    </ParamField>

    <ParamField body="headers" type="object">
      Custom HTTP headers (optional)
    </ParamField>
  </Expandable>

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

    <ParamField body="name" type="string" required>
      Tool name: `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 (optional)
    </ParamField>

    <ParamField body="expires_at" type="number">
      Token expiration timestamp (optional)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="sandbox_mode" type="string" default="cloud">
  Code execution environment mode:

  * `"cloud"` — Use cloud sandbox (E2B / OpenSandbox / Daytona)
  * `"local"` — Use local container (Docker / Apple Containerization), requires `working_directory`
  * `"none"` — No code execution environment
</ParamField>

<ParamField body="enable_web_search" type="boolean" default="false">
  Whether to enable the Web Search Tool (Tavily + DuckDuckGo)
</ParamField>

### RAG & Memory

<ParamField body="knowledge_base_ids" type="array" default="[]">
  List of knowledge base IDs. When provided, the `search_knowledge_base` tool is automatically registered
</ParamField>

<ParamField body="enable_memory" type="boolean" default="false">
  Whether to enable the Memory Tool (long-term memory read/write)
</ParamField>

### Skills

<ParamField body="skills" type="object">
  Skills activation configuration

  <Expandable title="skills">
    <ParamField body="skill_names" type="array">
      List of explicitly activated Skill names. If empty, automatic matching is used
    </ParamField>

    <ParamField body="auto_match" type="boolean" default="true">
      Whether to automatically match Skills based on message content
    </ParamField>

    <ParamField body="max_skills" type="number" default="3">
      Maximum number of Skills to activate simultaneously
    </ParamField>
  </Expandable>
</ParamField>

### Context

<ParamField body="chat_history" type="array" default="[]">
  List of historical conversation messages `[{ role, content, timestamp? }]`
</ParamField>

<ParamField body="resource_files" type="array" default="[]">
  List of resource files `[{ name, content, type }]` (e.g. Markdown prompts)
</ParamField>

<ParamField body="sandbox_files" type="array" default="[]">
  Files uploaded to the sandbox `[{ name, path, type, size? }]`
</ParamField>

<ParamField body="chat_attachments" type="array" default="[]">
  User-added chat attachments `[{ id, name, size, type, content }]`
</ParamField>

### HITL Approval

<ParamField body="hitl_config" type="object">
  Tool interrupt configuration (Human-in-the-Loop)

  <Expandable title="hitl_config">
    <ParamField body="tools" type="object" default="{}">
      Tool name to interrupt config mapping `{ enabled, requires_interrupt, allowed_decisions, timeout }`
    </ParamField>

    <ParamField body="default_requires_interrupt" type="boolean" default="true">
      Whether tools not listed in the config require interrupt by default
    </ParamField>

    <ParamField body="allowlist" type="array" default="[]">
      Allowlisted tools — tools in this list execute automatically without interruption
    </ParamField>

    <ParamField body="default_timeout" type="number" default="60">
      Default timeout in seconds
    </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": "Analyze the data trends in 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": "Let me help you analyze"}
  data: {"type": "message_chunk", "content": " the data trends in 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": "Based on the analysis..."}
  data: {"type": "done", "session_id": "sess_456"}
  ```
</ResponseExample>