Cortex Agents Run API | Snowflake Documentation (original) (raw)

Note

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

There are two methods to interact with an Agent:

• Build an agent object and reference this agent object in a request to the agent:run API.
• Call agent:run directly without an agent object. You provide the configuration in the request body of agent:run.

Both methods use streaming APIs that respond with the server-sent events specified under Streaming Responses.

Agent run request with agent object¶

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

Sends a user query to the agent object and returns its response as a stream of events.

Note

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.

Path parameters¶

Request body¶

Example

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

Agent run without an agent object¶

POST /api/v2/cortex/agent:run

Sends a user query to the Cortex Agents service provided in the request body and returns its response. Interacts with the agent without creating an agent object.

Note

Before September 1st, 2025, the request and response schemas for the agent:run API were different from the schema listed in this document. Previously, the orchestration was static and the same sequence of tools was used to generate an answer. agent:run now has an updated schema for both the request and response. In addition, the API now dynamically orchestrates and iterates to arrive at the final response. We recommend using the schema described in this document for an improved end-user experience.

To use the legacy schema and behavior, use the following schema:

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

Request headers¶

Request body¶

Example

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

Streaming responses¶

The agent:run API provides streaming responses. The server streams back events. This allows you to display responses in your application, token-by-token, as they are generated by the Agent. Each event streamed in the API response has a strictly typed schema. You can find a list of all of the events in the following section and select to which ones you’d like to subscribe.

The last event sent by the API is a response event. This event contains the entire agent output. You can use this as the agent’s final response. For any non-streaming clients, you can subscribe to this event because it is the logical aggregation of all prior events. If you don’t want to use streaming responses, wait for the response event and ignore all prior events.

The majority of the other events streamed can be split into two categories: Delta and Content Items.

Delta events represent a single token generated by the Agent. By listening to these events, you can create a typewriter effect. The main delta events are response.thinking.delta, which represents a reasoning token, and response.text.delta, which represent an answer token.

Content Item events represent elements from the content array in the final agent response.

Note

Make sure your application can handle unknown event types.

Example Response

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

response¶

Event streamed when the final response is available. This is the last event emitted, it represents the aggregation of all other events previously streamed.

Example

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

response.text¶

An event streamed when a text content block is done streaming, including all the aggregated deltas for a particular content index.

Example

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

response.text.delta¶

Event streamed when a new output text delta is generated.

Example

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

response.text.annotation¶

Event streamed when an annotation is added to a text content.

Example

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

response.thinking¶

An event streamed when a thinking content block is done streaming, including all the aggregated deltas for a particular content index.

Example

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

response.thinking.delta¶

Event streamed when a thinking delta is generated.

Example

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

response.tool_use¶

An event streamed when the agent requests a tool use.

Example

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

response.tool_result¶

Event streamed when a tool finishes executing, including the tool result.

Example

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

response.tool_result.status¶

Status update for a specific tool use.

Example

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

response.tool_result.analyst.delta¶

An delta event streamed for the Cortex Analyst tool execution

Example

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

response.table¶

An event streamed when a table content block is added.

Example

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

response.chart¶

An event streamed when a chart content block is added.

Example

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

response.status¶

Status update for the agent execution.

Example

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

error¶

Sent when a fatal errors is encountered.

Example

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

metadata¶

Metadata about the request. This event is sent when a message is added to the thread. It is useful for getting the parent_message_id to use in following requests to the Agents API.

Example

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

Schemas¶

AgentInstructions¶

Example

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

Annotation¶

Field	Type	Description
type	string	The citation type (always cortex_search_citation)
index	integer	The index of the citation in the search results.
search_result_id	string	The unique identifier for the search result.
doc_id	string	The unique identifier for the document.
doc_title	string	The title of the document.
text	string	The text excerpt from the document used as the citation.

Example

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

BudgetConfig¶

Example

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

ChartContent¶

Example

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

CortexAnalystSuggestionDelta¶

Example

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

CortexAnalystToolResultDelta¶

Example

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

ExecutionEnvironment¶

Configuration for server-executed tools.

Example

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

Message¶

Represents a single message in the conversation. Can be either from the user or the assistant.

Example

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

MessageContentItem¶

Field	Type	Description
type	string	The content type (always chart).
chart	ChartContent	The chart.

Example

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

ModelConfig¶

Example

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

OrchestrationConfig¶

Example

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

ResultSet¶

Example

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

ResultSetMetaData¶

Example

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

RowType¶

Example

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

TableContent¶

Example

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

ThinkingContent¶

Example

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

Tool¶

Defines a tool that can be used by the agent. Tools provide specific capabilities like data analysis, search, or generic functions.

Example

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

ToolChoice¶

Example

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

ToolInputSchema¶

Example

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

ToolResource¶

Configuration for text-to-SQL analysis tool. Provides parameters for SQL query generation and execution. Exactly one of semantic_model_file or semantic_view must be provided.

Field	Type	Description
semantic_model_file	string	The path to a file stored in a Snowflake Stage holding the semantic model yaml.
semantic_view	string	The name of the Snowflake native semantic model object.
execution_environment	ExecutionEnvironment	Configuration for how to execute the generated SQL query.

Example

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

ToolResult¶

Example

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

ToolResultContent¶

Field	Type	Description
type	string	The type of result (always json)
json	object	Structured output from a tool. The schema varies depending on the tool type.

Example

{ "type": "json", "json": { "answer": 42 } }

ToolSpec¶

Specification of the tool’s type, configuration, and input requirements.

Example

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

ToolUse¶

Example

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