Cortex Agents Run API¶

备注

Requests to the Cortex Agent REST API time out after 15 minutes.

有两种与代理交互的方法：

构建代理对象，并在向 agent:run API 发送请求时引用此代理对象。
直接调用 agent:run，无需使用代理对象。您在 agent:run 的请求正文中提供配置。

agent:run supports streaming responses by default. To disable streaming and receive a single JSON response, set stream to false.

带有代理对象的代理运行请求¶

POST /api/v2/databases/{database}/schemas/{schema}/agents/{name}:run

Sends a user query to the agent object and returns its response.

By default, the API streams responses as server-sent events (SSE). To receive a single JSON response, set stream to false in the request body.

备注

You can't set, update, or overwrite the models, instructions, and orchestration fields using this request. To update these fields, you must use Update Cortex Agent.

路径参数¶

参数	描述
`database`	（必需）包含该代理的数据库。可使用 `/api/v2/databases` GET 请求获取可用数据库列表。
`schema`	（必需）包含该代理的架构。可使用 `/api/v2/databases/{database}/schemas` GET 请求获取指定数据库的可用架构列表。
`name`	（必需）代理的名称。

请求标头¶

标头	描述
`Authorization`	（必需）授权令牌。有关更多信息，请参阅身份验证。
`Content-Type`	（必需）应用程序/json
`Accept`	(Optional) Response content type. Use `text/event-stream` for streaming responses or `application/json` for a single non-streaming response.

请求正文¶

字段	类型	描述
`type`	整数	对话的线程 ID。如果使用了 thread_id，则还必须传递 parent_message_id。
`data.message`	整数	线程中的父消息的 ID。如果这是第一条消息，parent_message_id 应为 0。
`messages`	Message 的数组	如果在请求中传递了 thread_id 和 parent_message_id，则消息将包含对话中的当前用户消息。否则，消息包括对话历史记录和当前消息。消息包含按时间顺序排列的用户查询和助手响应。
`stream`	布尔	Whether to return a streaming response (`text/event-stream`) or a non-streaming JSON response (`application/json`). If true, the response will be streamed as Server-Sent Events. If false, the response will be returned as JSON.
`tool_choice`	ToolChoice	配置代理在交互过程中应如何选择和使用工具。控制工具的使用是自动的、必需的，还是应使用特定工具。

示例

{
  "thread_id": 0,
  "parent_message_id": 0,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is the total revenue for 2023?"
        }
      ]
    }
  ],
  "stream": false,
  "tool_choice": {
    "type": "auto",
    "name": [
      "analyst_tool",
      "search_tool"
    ]
  }
}

Copy

The request body supports an optional stream boolean field:

If stream is omitted, it defaults to true and the response is streamed as SSE events.
If stream is false, the API returns a single JSON object (see Non-streaming response (stream: false)).

代理在没有代理对象的情况下运行¶

POST /api/v2/cortex/agent:run

向请求正文中提供的 Cortex Agents 服务发送用户查询，然后返回其响应。

备注

在 2025 年 9 月 1 日之前，agent:run API 的请求和响应架构与本文档中列出的架构不同。以前，编排是静态的，使用相同的工具序列来生成答案。现在，agent:run 的请求和响应架构已经更新。此外，API 现在动态编排和迭代以达到最终响应。我们建议使用本文档中描述的架构，以改善最终用户体验。

要使用旧架构和行为，请使用以下架构：

{
  "model": "claude-4-sonnet",
  "messages": [
     {"role":"user", "content": [] }
  ]
}

Copy

请求标头¶

标头	描述
`Authorization`	（必需）授权令牌。有关更多信息，请参阅身份验证。
`Content-Type`	（必需）应用程序/json
`Accept`	(Optional) Response content type. Use `text/event-stream` for streaming responses or `application/json` for a single non-streaming response.

请求正文¶

字段	类型	描述
`type`	整数	对话的线程 ID。如果使用了 thread_id，则还必须传递 parent_message_id。
`data.message`	整数	线程中的父消息的 ID。如果这是第一条消息，parent_message_id 应为 0。
`messages`	Message 的数组	如果在请求中传递了 thread_id 和 parent_message_id，则消息将包含对话中的当前用户消息。否则，消息包括对话历史记录和当前消息。消息包含按时间顺序排列的用户查询和助手响应。
`stream`	布尔	Whether to return a streaming response (`text/event-stream`) or a non-streaming JSON response (`application/json`). If true, the response will be streamed as Server-Sent Events. If false, the response will be returned as JSON.
`tool_choice`	ToolChoice	配置代理在交互过程中应如何选择和使用工具。控制工具的使用是自动的、必需的，还是应使用特定工具。
`models`	ModelConfig	代理的模型配置。包括编排模型（例如 claude-4-sonnet）。如果未提供，则自动选择模型。目前仅适用于 `编排` 步骤。
`instructions`	AgentInstructions	代理的行为指令，包括响应、编排、系统和示例问题。
`orchestration`	OrchestrationConfig	编排配置，包括预算约束（例如，秒数、令牌）。
`tools`	Tool 的数组	代理可使用的工具列表。每个工具包含一个 tool_spec，其中包括类型、名称、描述和输入架构。工具可能在 tool_resources 中有相应的配置。
`tool_resources`	ToolResource 的地图	对工具数组中每个引用工具的配置。密钥必须与相应工具的名称匹配。

示例

{
  "thread_id": 0,
  "parent_message_id": 0,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is the total revenue for 2023?"
        }
      ]
    }
  ],
  "stream": false,
  "tool_choice": {
    "type": "auto",
    "name": [
      "analyst_tool",
      "search_tool"
    ]
  },
  "models": {
    "orchestration": "claude-4-sonnet"
  },
  "instructions": {
    "response": "You will respond in a friendly but concise manner",
    "orchestration": "For any query related to revenue we should use Analyst; For all policy questions we should use Search",
    "system": "You are a friendly agent ..."
  },
  "orchestration": {
    "budget": {
      "seconds": 30,
      "tokens": 16000
    }
  },
  "tools": [
    {
      "tool_spec": {
        "type": "generic",
        "name": "get_revenue",
        "description": "Fetch the delivery revenue for a location.",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            }
          }
        },
        "required": [
          "location"
        ]
      }
    }
  ],
  "tool_resources": {
    "get_revenue": {
      "type": "function",
      "execution_environment": {
        "type": "warehouse",
        "warehouse": "MY_WH"
      },
      "identifier": "DB.SCHEMA.UDF"
    }
  }
}

Copy

The request body supports an optional stream boolean field:

If stream is omitted, it defaults to true and the response is streamed as SSE events.
If stream is false, the API returns a single JSON object (see Non-streaming response (stream: false)).

流式传输响应¶

agent:run API 提供流式传输响应。服务器流回事件。这允许您在应用程序中逐个令牌地显示由代理生成的响应。API 响应中流式传输的每个事件都有严格定义的模式。您可以在以下部分中找到所有事件的列表，并选择要订阅的事件。

API 发送的最后一个事件是 response 事件。此事件包含整个代理输出。您可以将其用作代理的最终响应。对于任何非流式传输客户端，您都可以订阅此事件，因为它是所有先前事件的逻辑聚合。如果您不想使用流式传输响应，请等待 response 事件并忽略所有先前的事件。

大多数其他流式传输事件可分为两类：Delta 和 Content Items。

Delta 事件表示代理生成的单个令牌。通过监听这些事件，您可以创建打字机效果。主要的 Delta 事件是表示推理令牌的 response.thinking.delta，以及表示答案令牌的 response.text.delta。

Content Item 事件表示最终代理响应中 content 数组中的元素。

备注

确保应用程序可以处理未知事件类型。

示例响应

event: response.status
data: {"message":"Planning the next steps","status":"planning"}

event: response.thinking.delta
data: {"content_index":0,"text":"\nThe user is asking for a"}

event: response.thinking.delta
data: {"content_index":0,"text":" chart showing the"}

...
...
...

event: response.status
data: {"message":"Reviewing the results","status":"reasoning_agent_stop"}

event: response.status
data: {"message":"Forming the answer","status":"proceeding_to_answer"}

Copy

`response`¶

最终响应可用时流式传输的事件。这是最后发出的事件，表示所有之前已流式传输事件的聚合结果。

字段	类型	描述
`role`	字符串	消息的角色。在 API 响应中始终为 `assistant`。
`content`	MessageContentItem 的数组	代理生成的内容。
`warnings`	array of Warning	Non-fatal warnings that occurred during processing. Present for non-streaming clients or as a summary.
`metadata`	ResponseMetadata

示例

{
  "role": "assistant",
  "content": [
    {
      "type": "chart",
      "chart": {
        "tool_use_id": "toolu_123",
        "chart_spec": "{\"$schema\":\"https://vega.github.io/schema/vega-lite/v5.json\",\"data\":{...},\"mark\":\"bar\"}"
      }
    }
  ],
  "warnings": [
    {
      "message": "Unable to fetch tools from MCP server 'foo'. Response quality may be degraded."
    }
  ],
  "metadata": {
    "usage": {
      "tokens_consumed": [
        {
          "model_name": "llama3.1-70b",
          "input_tokens": {
            "total": 175,
            "cache_read": 50,
            "cache_write": 25,
            "uncached": 100
          },
          "output_tokens": {
            "total": 75
          },
          "context_window": 128000
        }
      ]
    }
  }
}

Copy

`response.text`¶

当一个文本内容块完成流式传输时触发的事件，包括某个内容索引的所有聚合增量。

字段	类型	描述
`content_index`	整数	此事件所表示的内容块在响应的内容数组中的索引
`text`	字符串	来自代理的文本结果
`Authorization`	Annotation 的数组	附加到文本结果的任何注释（例如引用）
`"application/pdf"`	布尔	此文本内容是否表示代理正在向终端用户请求更多信息。

示例

{
  "content_index": 0,
  "text": "Lorem ipsum dolor...",
  "annotations": [
    {
      "type": "cortex_search_citation",
      "index": 0,
      "search_result_id": "cs_61987ff6-6d56-4695-83c0-1e7cfed818c7",
      "doc_id": "4ac085cb-82d0-4eb4-94f3-2672aa0599a2",
      "doc_title": "Earnings Report",
      "text": "The revenue for 2025 was..."
    }
  ],
  "is_elicitation": false
}

Copy

`response.text.delta`¶

生成新的输出文本增量时流式传输的事件。

字段	类型	描述
`content_index`	整数	此事件所表示的内容块在响应的内容数组中的索引
`text`	字符串	文本增量
`"application/pdf"`	布尔	此文本内容是否表示代理正在向终端用户请求更多信息。

示例

{
  "content_index": 0,
  "text": "Hello",
  "is_elicitation": false
}

Copy

`response.text.annotation`¶

向文本内容添加注释时流式传输的事件。

字段	类型	描述
`content_index`	整数	此事件所表示的内容块在响应的内容数组中的索引
`annotation_index`	整数	此 `annotation` 在注释数组中所属的索引。
`annotation`	Annotation	要添加的注释对象。

示例

{
  "content_index": 0,
  "annotation_index": 0,
  "annotation": {
    "type": "cortex_search_citation",
    "index": 0,
    "search_result_id": "cs_61987ff6-6d56-4695-83c0-1e7cfed818c7",
    "doc_id": "4ac085cb-82d0-4eb4-94f3-2672aa0599a2",
    "doc_title": "Earnings Report",
    "text": "The revenue for 2025 was..."
  }
}

Copy

`response.thinking`¶

当一个思考内容块完成流式传输时触发的事件，包括某个内容索引的所有聚合增量。

字段	类型	描述
`content_index`	整数	此事件所表示的内容块在响应的内容数组中的索引
`text`	字符串	代理的思考令牌
`signature`	字符串	The signature of the thinking token

示例

{
  "content_index": 0,
  "text": "To answer your question I must...",
  "signature": "lorem ipsum"
}

Copy

`response.thinking.delta`¶

生成思考增量时流式传输的事件。

字段	类型	描述
`content_index`	整数	此事件所表示的内容块在响应的内容数组中的索引
`text`	字符串	思考令牌
`signature`	字符串	The signature of the thinking token

示例

{
  "content_index": 0,
  "text": "lorem ipsum",
  "signature": "lorem ipsum"
}

Copy

`response.tool_use`¶

当代理请求使用工具时流式传输的事件。

字段	类型	描述
`content_index`	整数	此事件所表示的内容块在响应的内容数组中的索引
`"tool_use"`	字符串	此工具使用的唯一标识符。可用于关联工具结果。
`type`	字符串	The type of the tool (e.g. cortex_search, cortex_analyst_text_to_sql)
`name`	字符串	此工具实例的唯一标识符
`input`	对象	此工具的结构化输入。此对象的架构应根据工具规范而有所不同。
`client_side_execute`	布尔	工具使用是否在客户端执行。

示例

{
  "content_index": 0,
  "tool_use_id": "toolu_123",
  "type": "cortex_analyst_text_to_sql",
  "name": "my_cortex_analyst_semantic_view",
  "input": {
    "location": "San Francisco, CA"
  },
  "client_side_execute": "true"
}

Copy

`response.tool_result`¶

工具完成执行时流式传输的事件，包括工具结果。

字段	类型	描述
`content_index`	整数	此事件所表示的内容块在响应的内容数组中的索引
`"tool_use"`	字符串	此工具使用的唯一标识符。可用于关联工具结果。
`type`	字符串	The type of the tool (e.g. cortex_search, cortex_analyst_text_to_sql)
`name`	字符串	此工具实例的唯一标识符
`content`	ToolResultContent 的数组	工具结果的内容
`status`	字符串	工具执行的状态

示例

{
  "content_index": 0,
  "tool_use_id": "toolu_123",
  "type": "cortex_analyst_text_to_sql",
  "name": "my_cortex_analyst_semantic_view",
  "content": [
    {
      "type": "json",
      "json": {
        "answer": 42
      }
    }
  ],
  "status": "success"
}

Copy

`response.tool_result.status`¶

特定工具使用的状态更新。

字段	类型	描述
`"tool_use"`	字符串	此工具使用请求的唯一标识符。
`tool_type`	字符串	The type of the tool (e.g. cortex_search, cortex_analyst_text_to_sql)
`status`	字符串	当前状态的枚举。
`message`	字符串	扩展说明当前状态的更详细消息。
`details`	对象	Tool-specific status details.

示例

{
  "tool_use_id": "toolu_123",
  "tool_type": "cortex_analyst_text_to_sql",
  "status": "Executing SQL",
  "message": "Executing query 'SELECT * FROM my_table'",
  "details": {}
}

Copy

`response.tool_result.analyst.delta`¶

为 Cortex Analyst 工具执行流式传输的增量事件

字段	类型	描述
`content_index`	整数	此事件所表示的内容块在响应的内容数组中的索引
`"tool_use"`	字符串	此工具使用的唯一标识符。可用于关联工具结果。
`tool_type`	字符串	The type of the tool (always cortex_analyst_text_to_sql for this event)
`tool_name`	字符串	此工具实例的唯一标识符
`delta`	CortexAnalystToolResultDelta	内容增量

示例

{
  "content_index": 0,
  "tool_use_id": "toolu_123",
  "tool_type": "cortex_analyst_text_to_sql",
  "tool_name": "my_cortex_analyst_semantic_view",
  "delta": {
    "text": "The...",
    "think": "Thinking...",
    "sql": "SELECT...",
    "sql_explanation": "This...",
    "query_id": "707787a0-a684-4ead-adb0-3c3b62b043d9",
    "verified_query_used": false,
    "result_set": {
      "statementHandle": "707787a0-a684-4ead-adb0-3c3b62b043d9",
      "resultSetMetaData": {
        "partition": 0,
        "numRows": 0,
        "format": "jsonv2",
        "rowType": [
          {
            "name": "my_column",
            "type": "VARCHAR",
            "length": 0,
            "precision": 0,
            "scale": 0,
            "nullable": false
          }
        ]
      },
      "data": [
        [
          "row1 col1",
          "row1 col2"
        ],
        [
          "row2 col1",
          "row2 col2"
        ]
      ]
    },
    "suggestions": {
      "index": 0,
      "delta": "What..."
    }
  }
}

Copy

`response.table`¶

添加表内容块时流式传输的事件。

字段	类型	描述
`content_index`	整数	此事件所表示的内容块在响应的内容数组中的索引
`"tool_use"`	字符串	生成此表的工具使用的 ID
`query_id`	字符串	生成此数据的 sql 查询的查询 ID。
`result_set`	ResultSet	呈现表的 SQL 结果。与 Snowflake SQL API ResultSet 的架构匹配 (https://docs.snowflake.cn/en/developer-guide/sql-api/reference#resultset)
`title`	字符串	此表的标题

示例

{
  "content_index": 0,
  "tool_use_id": "toolu_123",
  "query_id": "6ac75378-6337-48a6-80ab-6de48dd680eb",
  "result_set": {
    "statementHandle": "707787a0-a684-4ead-adb0-3c3b62b043d9",
    "resultSetMetaData": {
      "partition": 0,
      "numRows": 0,
      "format": "jsonv2",
      "rowType": [
        {
          "name": "my_column",
          "type": "VARCHAR",
          "length": 0,
          "precision": 0,
          "scale": 0,
          "nullable": false
        }
      ]
    },
    "data": [
      [
        "row1 col1",
        "row1 col2"
      ],
      [
        "row2 col1",
        "row2 col2"
      ]
    ]
  },
  "title": "Revenue by Month"
}

Copy

`response.chart`¶

添加图表内容块时流式传输的事件。

字段	类型	描述
`content_index`	整数	此事件所表示的内容块在响应的内容数组中的索引
`"tool_use"`	字符串	生成此图表的工具使用的 ID
`"chart"`	字符串	以字符串序列化的 vega-lite 图表规范

示例

{
  "content_index": 0,
  "tool_use_id": "toolu_123",
  "chart_spec": "{\"$schema\":\"https://vega.github.io/schema/vega-lite/v5.json\",\"data\":{...},\"mark\":\"bar\"}"
}

Copy

`response.status`¶

代理执行的状态更新。

字段	类型	描述
`status`	字符串	当前状态的枚举。
`message`	字符串	扩展说明当前状态的更详细消息。

示例

{
  "status": "executing_tool",
  "message": "Executing tool `my_analyst_tool`"
}

Copy

`response.warning`¶

Sent when a non-fatal warning occurs. The stream continues after this event.

字段	类型	描述
`message`	字符串	The warning message to display to the user.

示例

{
  "message": "Unable to fetch tools from MCP server 'foo'. Response quality may be degraded."
}

Copy

`error`¶

Sent when a fatal error is encountered.

字段	类型	描述
`code`	字符串	Snowflake 错误代码
`message`	字符串	错误消息
`request_id`	字符串	此请求的唯一标识符

示例

{
  "code": "399504",
  "message": "Error during execution",
  "request_id": "61987ff6-6d56-4695-83c0-1e7cfed818c7"
}

Copy

`metadata`¶

有关请求的元数据。将消息添加到线程时发送此事件。它对于获取 Parent_message_id，以便在后续向 Agents API 发起请求时使用。

字段	类型	描述
`metadata`	Metadata

示例

{
  "metadata": {
    "role": "user",
    "message_id": 0
  }
}

Copy

架构¶

`AgentInstructions`¶

字段	类型	描述
`response`	字符串	响应生成的指令。
`orchestration`	字符串	当代理计划使用哪些工具时，将使用这些自定义指令。
`system`	字符串	代理的系统指令。

示例

{
  "response": "You will respond in a friendly but concise manner",
  "orchestration": "For any query related to revenue we should use Analyst; For all policy questions we should use Search",
  "system": "You are a friendly agent ..."
}

Copy

`Annotation`¶

字段

类型

描述

type

字符串

引文类型（始终为 cortex_search_citation）

text

整数

搜索结果中引用的索引。

"tool_results"

字符串

搜索结果的唯一标识符。

data.id

字符串

文档的唯一标识符。

type

字符串

文档的标题。

text

字符串

文档中作为引用使用的文本片段。

示例
{
  "type": "cortex_search_citation",
  "index": 0,
  "search_result_id": "cs_61987ff6-6d56-4695-83c0-1e7cfed818c7",
  "doc_id": "4ac085cb-82d0-4eb4-94f3-2672aa0599a2",
  "doc_title": "Earnings Report",
  "text": "The revenue for 2025 was..."
}
Copy

字段	类型	描述
`type`	字符串	引文类型（始终为 `cortex_search_citation`）
`text`	整数	搜索结果中引用的索引。
`"tool_results"`	字符串	搜索结果的唯一标识符。
`data.id`	字符串	文档的唯一标识符。
`type`	字符串	文档的标题。
`text`	字符串	文档中作为引用使用的文本片段。

`BudgetConfig`¶

字段	类型	描述
`seconds`	整数	时间预算（秒）。
`tokens`	整数	令牌预算。

示例

{
  "seconds": 30,
  "tokens": 16000
}

Copy

`ChartContent`¶

字段	类型	描述
`"tool_use"`	字符串	生成此图表的工具使用的 ID
`"chart"`	字符串	以字符串序列化的 vega-lite 图表规范

示例

{
  "tool_use_id": "toolu_123",
  "chart_spec": "{\"$schema\":\"https://vega.github.io/schema/vega-lite/v5.json\",\"data\":{...},\"mark\":\"bar\"}"
}

Copy

`CortexAnalystSuggestionDelta`¶

字段	类型	描述
`text`	整数	此增量在推荐数组中所代表的索引
`delta`	字符串	此索引推荐问题的文本增量

示例

{
  "index": 0,
  "delta": "What..."
}

Copy

`CortexAnalystToolResultDelta`¶

字段	类型	描述
`text`	字符串	来自 Cortex Analyst 最终响应的文本增量。
`think`	字符串	来自 Cortex Analyst 推理步骤的文本增量。
`sql`	字符串	来自 Cortex Analyst SQL 输出的增量。目前，整个 SQL 查询会包含于单个事件中；但未来我们或许会逐词元地流式传输该 SQL。
`sql_explanation`	字符串	来自 Cortex Analyst 对 SQL 查询作用解释的增量
`query_id`	字符串	SQL 执行开始后的查询 ID
`verified_query_used`	布尔	是否使用了已验证的查询来生成此响应
`result_set`	ResultSet	SQL 执行的结果。与 Snowflake SQL API ResultSet 的架构匹配 (https://docs.snowflake.cn/en/developer-guide/sql-api/reference#resultset)
`suggestions`	CortexAnalystSuggestionDelta	来自 Cortex Analyst 推荐问题的增量。当 Analyst 因信息缺失或其他错误无法回答问题时发送。

示例

{
  "text": "The...",
  "think": "Thinking...",
  "sql": "SELECT...",
  "sql_explanation": "This...",
  "query_id": "707787a0-a684-4ead-adb0-3c3b62b043d9",
  "verified_query_used": false,
  "result_set": {
    "statementHandle": "707787a0-a684-4ead-adb0-3c3b62b043d9",
    "resultSetMetaData": {
      "partition": 0,
      "numRows": 0,
      "format": "jsonv2",
      "rowType": [
        {
          "name": "my_column",
          "type": "VARCHAR",
          "length": 0,
          "precision": 0,
          "scale": 0,
          "nullable": false
        }
      ]
    },
    "data": [
      [
        "row1 col1",
        "row1 col2"
      ],
      [
        "row2 col1",
        "row2 col2"
      ]
    ]
  },
  "suggestions": {
    "index": 0,
    "delta": "What..."
  }
}

Copy

`ExecutionEnvironment`¶

服务器执行工具的配置。

字段	类型	描述
`type`	字符串	执行环境的类型，目前仅支持 `warehouse`。
`warehouse`	字符串	仓库的名称。区分大小写，如果是未加引号的标识符，则提供全部大写的名称。
`query_timeout`	整数	查询超时（以秒为单位）

示例

{
  "type": "warehouse",
  "warehouse": "MY_WAREHOUSE",
  "query_timeout": 60
}

Copy

`InputTokens`¶

Input token breakdown by cache usage.

字段	类型	描述
`total`	整数	Total input tokens processed (including cached tokens).
`cache_read`	整数	Input tokens read from cache.
`cache_write`	整数	Input tokens written to cache.
`uncached`	整数	Input tokens that were not cached.

示例

{
  "total": 175,
  "cache_read": 50,
  "cache_write": 25,
  "uncached": 100
}

Copy

`Message`¶

表示对话中的单条消息。可以来自用户或助手。

字段	类型	描述
`role`	字符串	确定是谁发送了消息，即用户或助手。用户消息通常包含查询，而助手消息包含响应和工具结果。
`content`	MessageContentItem 的数组	组成消息的内容元素数组。可以包含文本、工具结果或自定义内容类型。

示例

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "What is the total revenue for 2023?"
    }
  ]
}

Copy

`MessageContentItem`¶

字段	类型	描述
`type`	字符串	内容类型（始终为 `chart`）。
`chart`	ChartContent	图表。

示例

{
  "type": "chart",
  "chart": {
    "tool_use_id": "toolu_123",
    "chart_spec": "{\"$schema\":\"https://vega.github.io/schema/vega-lite/v5.json\",\"data\":{...},\"mark\":\"bar\"}"
  }
}

Copy

字段	类型	描述
`type`	字符串	内容类型（始终为 `table`）。
`table`	TableContent	表。

示例

{
  "type": "table",
  "table": {
    "tool_use_id": "toolu_123",
    "query_id": "6ac75378-6337-48a6-80ab-6de48dd680eb",
    "result_set": {
      "statementHandle": "707787a0-a684-4ead-adb0-3c3b62b043d9",
      "resultSetMetaData": {
        "partition": 0,
        "numRows": 0,
        "format": "jsonv2",
        "rowType": [
          {
            "name": "my_column",
            "type": "VARCHAR",
            "length": 0,
            "precision": 0,
            "scale": 0,
            "nullable": false
          }
        ]
      },
      "data": [
        [
          "row1 col1",
          "row1 col2"
        ],
        [
          "row2 col1",
          "row2 col2"
        ]
      ]
    },
    "title": "Revenue by Month"
  }
}

Copy

字段	类型	描述
`text`	字符串	来自代理的文本结果
`Authorization`	Annotation 的数组	附加到文本结果的任何注释（例如引用）
`"application/pdf"`	布尔	此文本内容是否表示代理正在向终端用户请求更多信息。
`type`	字符串	内容类型（始终为 `text`）。

示例

{
  "text": "Lorem ipsum dolor...",
  "annotations": [
    {
      "type": "cortex_search_citation",
      "index": 0,
      "search_result_id": "cs_61987ff6-6d56-4695-83c0-1e7cfed818c7",
      "doc_id": "4ac085cb-82d0-4eb4-94f3-2672aa0599a2",
      "doc_title": "Earnings Report",
      "text": "The revenue for 2025 was..."
    }
  ],
  "is_elicitation": false,
  "type": "text"
}

Copy

字段	类型	描述
`type`	字符串	内容类型（始终为 `thinking`）。
`Authorization`	ThinkingContent	思考内容。

示例

{
  "type": "thinking",
  "thinking": {
    "text": "To answer your question I must...",
    "signature": "lorem ipsum"
  }
}

Copy

字段	类型	描述
`type`	字符串	内容类型（始终为 `tool_result`）。
`tool_result`	ToolResult	工具结果。

示例

{
  "type": "tool_result",
  "tool_result": {
    "tool_use_id": "toolu_123",
    "type": "cortex_analyst_text_to_sql",
    "name": "my_cortex_analyst_semantic_view",
    "content": [
      {
        "type": "json",
        "json": {
          "answer": 42
        }
      }
    ],
    "status": "success"
  }
}

Copy

字段	类型	描述
`type`	字符串	内容类型（始终为 `tool_use`）。
`tool_use`	ToolUse	工具使用。

示例

{
  "type": "tool_use",
  "tool_use": {
    "tool_use_id": "toolu_123",
    "type": "cortex_analyst_text_to_sql",
    "name": "my_cortex_analyst_semantic_view",
    "input": {
      "location": "San Francisco, CA"
    },
    "client_side_execute": "true"
  }
}

Copy

`Metadata`¶

字段	类型	描述
`role`	字符串	确定是谁发送了消息，即用户或助手。
`message_id`	整数	线程消息 ID。使用此 ID （当角色是 `assistant` 时），提出有关线程的跟进问题。

示例

{
  "role": "user",
  "message_id": 0
}

Copy

`ModelConfig`¶

字段	类型	描述
`orchestration`	字符串	用于编排的模型。如果未提供，则自动选择模型。

示例

{
  "orchestration": "claude-4-sonnet"
}

Copy

`OrchestrationConfig`¶

字段	类型	描述
`budget`	BudgetConfig	代理的预算约束。如果指定了多个约束则最先命中的约束将结束请求。

示例

{
  "budget": {
    "seconds": 30,
    "tokens": 16000
  }
}

Copy

`OutputTokens`¶

Output token details.

字段	类型	描述
`total`	整数	Total output tokens generated.

示例

{
  "total": 75
}

Copy

`ResponseMetadata`¶

Metadata about the response, including usage information.

字段	类型	描述
`usage`	UsageMetadata

示例

{
  "usage": {
    "tokens_consumed": [
      {
        "model_name": "llama3.1-70b",
        "input_tokens": {
          "total": 175,
          "cache_read": 50,
          "cache_write": 25,
          "uncached": 100
        },
        "output_tokens": {
          "total": 75
        },
        "context_window": 128000
      }
    ]
  }
}

Copy

`ResultSet`¶

字段	类型	描述
`statementHandle`	字符串	查询 id。
`resultSetMetaData`	ResultSetMetaData	结果集上的元数据。
`data`	数组构成的数组	表示数据的二维数组

示例

{
  "statementHandle": "707787a0-a684-4ead-adb0-3c3b62b043d9",
  "resultSetMetaData": {
    "partition": 0,
    "numRows": 0,
    "format": "jsonv2",
    "rowType": [
      {
        "name": "my_column",
        "type": "VARCHAR",
        "length": 0,
        "precision": 0,
        "scale": 0,
        "nullable": false
      }
    ]
  },
  "data": [
    [
      "row1 col1",
      "row1 col2"
    ],
    [
      "row2 col1",
      "row2 col2"
    ]
  ]
}

Copy

`ResultSetMetaData`¶

字段	类型	描述
`partition`	整数	分区的索引号。
`numRows`	整数	结果的总行数。
`format`	字符串	结果集中数据的格式。
`rowType`	RowType 的数组	结果中列的描述。

示例

{
  "partition": 0,
  "numRows": 0,
  "format": "jsonv2",
  "rowType": [
    {
      "name": "my_column",
      "type": "VARCHAR",
      "length": 0,
      "precision": 0,
      "scale": 0,
      "nullable": false
    }
  ]
}

Copy

`RowType`¶

字段	类型	描述
`name`	字符串	列的名称。
`type`	字符串	列的 Snowflake 数据类型。(https://docs.snowflake.cn/en/sql-reference/intro-summary-data-types)
`length`	整数	列的长度。
`precision`	整数	列的精度。
`scale`	整数	列的标度。
`nullable`	布尔	指定列是否可为空。

示例

{
  "name": "my_column",
  "type": "VARCHAR",
  "length": 0,
  "precision": 0,
  "scale": 0,
  "nullable": false
}

Copy

`TableContent`¶

字段	类型	描述
`"tool_use"`	字符串	生成此表的工具使用的 ID
`query_id`	字符串	生成此数据的 sql 查询的查询 ID。
`result_set`	ResultSet	呈现表的 SQL 结果。与 Snowflake SQL API ResultSet 的架构匹配 (https://docs.snowflake.cn/en/developer-guide/sql-api/reference#resultset)
`title`	字符串	此表的标题

示例

{
  "tool_use_id": "toolu_123",
  "query_id": "6ac75378-6337-48a6-80ab-6de48dd680eb",
  "result_set": {
    "statementHandle": "707787a0-a684-4ead-adb0-3c3b62b043d9",
    "resultSetMetaData": {
      "partition": 0,
      "numRows": 0,
      "format": "jsonv2",
      "rowType": [
        {
          "name": "my_column",
          "type": "VARCHAR",
          "length": 0,
          "precision": 0,
          "scale": 0,
          "nullable": false
        }
      ]
    },
    "data": [
      [
        "row1 col1",
        "row1 col2"
      ],
      [
        "row2 col1",
        "row2 col2"
      ]
    ]
  },
  "title": "Revenue by Month"
}

Copy

`ThinkingContent`¶

字段	类型	描述
`text`	字符串	代理的思考令牌
`signature`	字符串	The signature of the thinking token

示例

{
  "text": "To answer your question I must...",
  "signature": "lorem ipsum"
}

Copy

`TokensConsumed`¶

Token consumption for a specific model.

字段	类型	描述
`model_name`	字符串	Name of the model used.
`input_tokens`	InputTokens
`output_tokens`	OutputTokens
`context_window`	整数	The model's context window size (in tokens).

示例

{
  "model_name": "llama3.1-70b",
  "input_tokens": {
    "total": 175,
    "cache_read": 50,
    "cache_write": 25,
    "uncached": 100
  },
  "output_tokens": {
    "total": 75
  },
  "context_window": 128000
}

Copy

`Tool`¶

定义代理可以使用的工具。工具提供特定功能，如数据分析、搜索或通用功能。

字段	类型	描述
`tool_spec`	ToolSpec	工具的类型、配置及输入要求的规范。

示例

{
  "tool_spec": {
    "type": "generic",
    "name": "get_revenue",
    "description": "Fetch the delivery revenue for a location.",
    "input_schema": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "The city and state, e.g. San Francisco, CA"
        }
      }
    },
    "required": [
      "location"
    ]
  }
}

Copy

`ToolChoice`¶

字段	类型	描述
`type`	字符串	确定如何选择工具：- auto - 自动选择工具（默认）- required - 必须使用至少一个工具 - tool - 明确指定名称的工具
`name`	array of string	当类型为“tool”时，要使用的特定工具名称列表。

示例

{
  "type": "auto",
  "name": [
    "analyst_tool",
    "search_tool"
  ]
}

Copy

`ToolInputSchema`¶

字段	类型	描述
`type`	字符串	输入架构对象的类型。
`description`	字符串	输入内容的描述。
`properties`	ToolInputSchema 的地图	如果类型为 `object`，每个输入参数的定义。
`items`	ToolInputSchema	如果类型为 `array`，数组元素的架构。
`required`	array of string	如果类型为 `object`，所需输入参数名称的列表。

示例

{
  "type": "object",
  "description": "Input for my custom tool",
  "properties": {
    "location": {
      "type": "string",
      "description": "The city and state, e.g. San Francisco, CA"
    }
  },
  "items": {},
  "required": [
    "location"
  ]
}

Copy

`ToolResource`¶

文本转 SQL 分析工具的配置。提供用于 SQL 查询生成和执行的参数。必须仅提供 semantic_model_file 或 semantic_view 之一。

字段

类型

描述

semantic_model_file

字符串

存储在 Snowflake Stage 中的文件路径，该文件包含语义模型 yaml。

semantic_view

字符串

Snowflake 原生语义模型对象的名称。

execution_environment

ExecutionEnvironment

用于生成的 SQL 查询的执行方式的配置。

示例
{
  "semantic_model_file": "@db.schema.stage/semantic_model.yaml",
  "semantic_view": "db.schema.semantic_view",
  "execution_environment": {
    "type": "warehouse",
    "warehouse": "MY_WAREHOUSE",
    "query_timeout": 60
  }
}
Copy
搜索功能的配置。定义文档搜索和检索的方式。

字段

类型

描述

search_service

字符串

搜索服务的完全限定名称。

title_column

字符串

文档的标题列。

id_column

字符串

文档的 ID 列。

filter

对象

搜索结果的筛选查询。

示例
{
  "search_service": "database.schema.service_name",
  "title_column": "account_name",
  "id_column": "account_id",
  "filter": {
    "@eq": {
      "<column>": "<value>"
    }
  }
}
Copy
字段

类型

描述

type

字符串

如果该工具是在服务器端执行的，用于表示它是存储过程还是 UDF。

execution_environment

ExecutionEnvironment

identifier

字符串

存储过程或 UDF 的完全限定名称。

示例
{
  "type": "function",
  "execution_environment": {
    "type": "warehouse",
    "warehouse": "MY_WAREHOUSE",
    "query_timeout": 60
  },
  "identifier": "MY_DB.MY_SCHEMA.MY_UDF"
}
Copy

`ToolResult`¶

字段	类型	描述
`"tool_use"`	字符串	此工具使用的唯一标识符。可用于关联工具结果。
`type`	字符串	The type of the tool (e.g. cortex_search, cortex_analyst_text_to_sql)
`name`	字符串	此工具实例的唯一标识符
`content`	ToolResultContent 的数组	工具结果的内容
`status`	字符串	工具执行的状态

示例

{
  "tool_use_id": "toolu_123",
  "type": "cortex_analyst_text_to_sql",
  "name": "my_cortex_analyst_semantic_view",
  "content": [
    {
      "type": "json",
      "json": {
        "answer": 42
      }
    }
  ],
  "status": "success"
}

Copy

`ToolResultContent`¶

字段

类型

描述

type

字符串

结果的类型（始终为 json）

json

对象

来自工具的结构化输出。架构因工具类型而异。

示例
{
  "type": "json",
  "json": {
    "answer": 42
  }
}
Copy
字段

类型

描述

type

字符串

结果的类型（始终为 text）

text

字符串

结果文本

示例
{
  "type": "text",
  "text": "The answer is 42"
}
Copy

`ToolSpec`¶

工具的类型、配置及输入要求的规范。

字段	类型	描述
`type`	字符串	工具功能类型。可以是专用类型，如“cortex_analyst_text_to_sql”或用于通用工具的“generic”。
`name`	字符串	工具实例的唯一标识符。用于匹配 tool_resources 中的配置。
`description`	字符串	待考虑使用工具的描述。
`input_schema`	ToolInputSchema	此工具期望输入参数的 JSON 架构定义。这将被提供给代理，以便它在生成 ToolUses 的输入时，知道应遵循的结构。对于通用工具，此字段必填，用于指定输入参数。

示例

{
  "type": "generic",
  "name": "get_weather",
  "description": "lorem ipsum",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city and state, e.g. San Francisco, CA"
      }
    },
    "required": [
      "location"
    ]
  }
}

Copy

`ToolUse`¶

字段	类型	描述
`"tool_use"`	字符串	此工具使用的唯一标识符。可用于关联工具结果。
`type`	字符串	The type of the tool (e.g. cortex_search, cortex_analyst_text_to_sql)
`name`	字符串	此工具实例的唯一标识符
`input`	对象	此工具的结构化输入。此对象的架构应根据工具规范而有所不同。
`client_side_execute`	布尔	工具使用是否在客户端执行。

示例

{
  "tool_use_id": "toolu_123",
  "type": "cortex_analyst_text_to_sql",
  "name": "my_cortex_analyst_semantic_view",
  "input": {
    "location": "San Francisco, CA"
  },
  "client_side_execute": "true"
}

Copy

`UsageMetadata`¶

Token usage information for this request.

字段	类型	描述
`tokens_consumed`	array of TokensConsumed	Token consumption details per model used in this request.

示例

{
  "tokens_consumed": [
    {
      "model_name": "llama3.1-70b",
      "input_tokens": {
        "total": 175,
        "cache_read": 50,
        "cache_write": 25,
        "uncached": 100
      },
      "output_tokens": {
        "total": 75
      },
      "context_window": 128000
    }
  ]
}

Copy

`Warning`¶

字段	类型	描述
`message`	字符串	The warning message to display to the user.

示例

{
  "message": "Unable to fetch tools from MCP server 'foo'. Response quality may be degraded."
}

Copy

Non-streaming response (stream: false)¶

To receive a single non-streaming JSON response, set stream to false in the request body and set the request Accept header to application/json.

The response body is the same object as the response event payload in streaming mode (that is, it corresponds to the JSON returned in the SSE response event's data field).

Example response

{
  "role": "assistant",
  "content": [
    {
      "thinking": {
        "text": "\nThe user is asking about types of products...\n"
      },
      "type": "thinking"
    },
    {
      "tool_use": {
        "client_side_execute": false,
        "input": {
          "has_time_column": false,
          "need_future_forecasting_data": false,
          "original_query": "what are some types of products?",
          "previous_related_tool_result_id": "",
          "query": "What are the different types or categories of products?"
        },
        "name": "semantic_view_a",
        "tool_use_id": "<tool_use_id>",
        "type": "cortex_analyst_text_to_sql"
      },
      "type": "tool_use"
    },
    {
      "tool_result": {
        "content": [
          {
            "json": {
              "query_id": "<query_id>",
              "result_set": {
                "data": [
                  ["Electronics", "3", "3"],
                  ["Furniture", "2", "2"]
                ],
                "resultSetMetaData": {
                  "format": "jsonv2",
                  "numRows": 2,
                  "partition": 0
                },
                "statementHandle": "<statement_handle>"
              },
              "sql": "WITH __table_a AS (...) SELECT ...",
              "text": "The question is clear and I can answer it with the following SQL."
            },
            "type": "json"
          }
        ],
        "name": "semantic_view_a",
        "status": "success",
        "tool_use_id": "<tool_use_id>",
        "type": "cortex_analyst_text_to_sql"
      },
      "type": "tool_result"
    },
    {
      "text": "Based on the data available, there are 2 main types of products...",
      "type": "text"
    }
  ]
}

Copy

字段	类型	描述
`semantic_model_file`	字符串	存储在 Snowflake Stage 中的文件路径，该文件包含语义模型 yaml。
`semantic_view`	字符串	Snowflake 原生语义模型对象的名称。
`execution_environment`	ExecutionEnvironment	用于生成的 SQL 查询的执行方式的配置。

字段	类型	描述
`search_service`	字符串	搜索服务的完全限定名称。
`title_column`	字符串	文档的标题列。
`id_column`	字符串	文档的 ID 列。
`filter`	对象	搜索结果的筛选查询。

字段	类型	描述
`type`	字符串	如果该工具是在服务器端执行的，用于表示它是存储过程还是 UDF。
`execution_environment`	ExecutionEnvironment
`identifier`	字符串	存储过程或 UDF 的完全限定名称。

字段	类型	描述
`type`	字符串	结果的类型（始终为 `json`）
`json`	对象	来自工具的结构化输出。架构因工具类型而异。

字段	类型	描述
`type`	字符串	结果的类型（始终为 `text`）
`text`	字符串	结果文本

Cortex Agents Run API¶

带有代理对象的代理运行请求¶

路径参数¶

请求标头¶

请求正文¶

代理在没有代理对象的情况下运行¶

请求标头¶

请求正文¶

流式传输响应¶

response¶

response.text¶

response.text.delta¶

response.text.annotation¶

response.thinking¶

response.thinking.delta¶

response.tool_use¶

response.tool_result¶

response.tool_result.status¶

response.tool_result.analyst.delta¶

response.table¶

response.chart¶

response.status¶

response.warning¶

error¶

metadata¶

架构¶

AgentInstructions¶

Annotation¶

BudgetConfig¶

ChartContent¶

CortexAnalystSuggestionDelta¶

CortexAnalystToolResultDelta¶

ExecutionEnvironment¶

InputTokens¶

Message¶

MessageContentItem¶

Metadata¶

ModelConfig¶

OrchestrationConfig¶

OutputTokens¶

ResponseMetadata¶

ResultSet¶

ResultSetMetaData¶

RowType¶

TableContent¶

ThinkingContent¶

TokensConsumed¶

Tool¶

ToolChoice¶

ToolInputSchema¶

ToolResource¶

ToolResult¶

ToolResultContent¶

ToolSpec¶

ToolUse¶

UsageMetadata¶

Warning¶

Non-streaming response (stream: false)¶

`response`¶

`response.text`¶

`response.text.delta`¶

`response.text.annotation`¶

`response.thinking`¶

`response.thinking.delta`¶

`response.tool_use`¶

`response.tool_result`¶

`response.tool_result.status`¶

`response.tool_result.analyst.delta`¶

`response.table`¶

`response.chart`¶

`response.status`¶

`response.warning`¶

`error`¶

`metadata`¶

`AgentInstructions`¶

`Annotation`¶

`BudgetConfig`¶

`ChartContent`¶

`CortexAnalystSuggestionDelta`¶

`CortexAnalystToolResultDelta`¶

`ExecutionEnvironment`¶

`InputTokens`¶

`Message`¶

`MessageContentItem`¶

`Metadata`¶

`ModelConfig`¶

`OrchestrationConfig`¶

`OutputTokens`¶

`ResponseMetadata`¶

`ResultSet`¶

`ResultSetMetaData`¶

`RowType`¶

`TableContent`¶

`ThinkingContent`¶

`TokensConsumed`¶

`Tool`¶

`ToolChoice`¶

`ToolInputSchema`¶

`ToolResource`¶

`ToolResult`¶

`ToolResultContent`¶

`ToolSpec`¶

`ToolUse`¶

`UsageMetadata`¶

`Warning`¶