Cortex Agents Run API¶

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

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

这两种方法均采用流式传输 APIs，其响应以 Streaming Responses 中规定的服务器发送事件形式返回。

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

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

将用户查询发送到代理对象，并以事件流的形式返回其响应。

路径参数¶

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

请求标头¶

标头	描述
`Authorization`	（必需）授权令牌。有关更多信息，请参阅身份验证。
`Content-Type`	（必需）应用程序/json

请求正文¶

字段	类型	描述
`type`	整数	对话的线程 ID。如果使用了 thread_id，则还必须传递 parent_message_id。
`data.message`	整数	线程中的父消息的 ID。如果这是第一条消息，parent_message_id 应为 0。
`messages`	Message 的数组	如果在请求中传递了 thread_id 和 parent_message_id，则消息将包含对话中的当前用户消息。否则，消息包括对话历史记录和当前消息。消息包含按时间顺序排列的用户查询和助手响应。
`tool_choice`	ToolChoice	配置代理在交互过程中应如何选择和使用工具。控制工具的使用是自动的、必需的，还是应使用特定工具。

示例

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

Copy

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

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

请求正文¶

字段	类型	描述
`type`	整数	对话的线程 ID。如果使用了 thread_id，则还必须传递 parent_message_id。
`data.message`	整数	线程中的父消息的 ID。如果这是第一条消息，parent_message_id 应为 0。
`messages`	Message 的数组	如果在请求中传递了 thread_id 和 parent_message_id，则消息将包含对话中的当前用户消息。否则，消息包括对话历史记录和当前消息。消息包含按时间顺序排列的用户查询和助手响应。
`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?"
        }
      ]
    }
  ],
  "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

流式传输响应¶

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 的数组	代理生成的内容。

示例

{
  "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\"}"
      }
    }
  ]
}

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`	字符串	代理的思考令牌

示例

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

Copy

`response.thinking.delta`¶

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

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

示例

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

Copy

`response.tool_use`¶

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

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

示例

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

Copy

`response.tool_result`¶

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

字段	类型	描述
`content_index`	整数	此事件所表示的内容块在响应的内容数组中的索引
`"tool_use"`	字符串	此工具使用的唯一标识符。可用于关联工具结果。
`type`	字符串	工具的类型（例如 cortex_search、cortex_analyst_text2sql）
`name`	字符串	此工具实例的唯一标识符
`content`	ToolResultContent 的数组	工具结果的内容
`status`	字符串	工具执行的状态

示例

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

Copy

`response.tool_result.status`¶

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

字段	类型	描述
`"tool_use"`	字符串	此工具使用请求的唯一标识符。
`tool_type`	字符串	工具的类型（例如 cortex_search、cortex_analyst_text2sql）
`status`	字符串	当前状态的枚举。
`message`	字符串	扩展说明当前状态的更详细消息。

示例

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

Copy

`response.tool_result.analyst.delta`¶

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

字段	类型	描述
`content_index`	整数	此事件所表示的内容块在响应的内容数组中的索引
`"tool_use"`	字符串	此工具使用的唯一标识符。可用于关联工具结果。
`tool_type`	字符串	工具的类型（对于此事件，始终为 cortex_analyst_text2sql）
`tool_name`	字符串	此工具实例的唯一标识符
`delta`	CortexAnalystToolResultDelta	内容增量

示例

{
  "content_index": 0,
  "tool_use_id": "toolu_123",
  "tool_type": "cortex_analyst_text2sql",
  "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

`error`¶

遇到致命错误时发送。

字段	类型	描述
`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 发起请求时使用。

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

示例

{
  "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

`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..."
  }
}

Copy

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

示例

{
  "type": "tool_result",
  "tool_result": {
    "tool_use_id": "toolu_123",
    "type": "cortex_analyst_text2sql",
    "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_text2sql",
    "name": "my_cortex_analyst_semantic_view",
    "input": {
      "location": "San Francisco, CA"
    },
    "client_side_execute": "true"
  }
}

Copy

`ModelConfig`¶

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

示例

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

Copy

`OrchestrationConfig`¶

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

示例

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

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`	字符串	代理的思考令牌

示例

{
  "text": "To answer your question I must..."
}

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

字段	类型	描述
`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 的完全限定名称。

`ToolResult`¶

字段	类型	描述
`"tool_use"`	字符串	此工具使用的唯一标识符。可用于关联工具结果。
`type`	字符串	工具的类型（例如 cortex_search、cortex_analyst_text2sql）
`name`	字符串	此工具实例的唯一标识符
`content`	ToolResultContent 的数组	工具结果的内容
`status`	字符串	工具执行的状态

示例

{
  "tool_use_id": "toolu_123",
  "type": "cortex_analyst_text2sql",
  "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

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

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

`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`	字符串	工具的类型（例如 cortex_search、cortex_analyst_text2sql）
`name`	字符串	此工具实例的唯一标识符
`input`	对象	此工具的结构化输入。此对象的架构应根据工具规范而有所不同。
`client_side_execute`	布尔	工具使用是否在客户端执行。

示例

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

Copy

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¶

error¶

metadata 事件¶

架构¶

AgentInstructions¶

Annotation¶

BudgetConfig¶

ChartContent¶

CortexAnalystSuggestionDelta¶

CortexAnalystToolResultDelta¶

ExecutionEnvironment¶

Message¶

MessageContentItem¶

ModelConfig¶

OrchestrationConfig¶

ResultSet¶

ResultSetMetaData¶

RowType¶

TableContent¶

ThinkingContent¶

Tool¶

ToolChoice¶

ToolInputSchema¶

ToolResource¶

ToolResult¶

ToolResultContent¶

ToolSpec¶

ToolUse¶

`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`¶

`error`¶

`metadata` 事件¶

`AgentInstructions`¶

`Annotation`¶

`BudgetConfig`¶

`ChartContent`¶

`CortexAnalystSuggestionDelta`¶

`CortexAnalystToolResultDelta`¶

`ExecutionEnvironment`¶

`Message`¶

`MessageContentItem`¶

`ModelConfig`¶

`OrchestrationConfig`¶

`ResultSet`¶

`ResultSetMetaData`¶

`RowType`¶

`TableContent`¶

`ThinkingContent`¶

`Tool`¶

`ToolChoice`¶

`ToolInputSchema`¶

`ToolResource`¶

`ToolResult`¶

`ToolResultContent`¶

`ToolSpec`¶

`ToolUse`¶