Cortex Agents 실행 API¶

에이전트와 상호 작용하는 두 가지 방법은 다음과 같습니다.

에이전트 오브젝트를 만들고 agent:run API에 대한 요청에서 이 에이전트 오브젝트를 참조합니다.
에이전트 오브젝트 없이 :code:`agent:run`을 직접 호출합니다. :code:`agent:run`의 요청 본문에 구성을 입력합니다.

두 방법 모두 :code:`Streaming Responses`에 지정된 서버 전송 이벤트로 응답하는 스트리밍 APIs를 사용합니다.

에이전트 오브젝트를 통한 에이전트 실행 요청¶

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

요청 본문¶

필드	타입	설명
`thread_id`	정수	대화의 스레드 ID입니다. thread_id가 사용되는 경우 parent_message_id도 전달해야 합니다.
`parent_message_id`	정수	스레드에 있는 상위 메시지의 ID입니다. 이것이 첫 번째 메시지인 경우 parent_message_id는 0이어야 합니다.
`messages`	:ref:`label_snowflake_agent_run_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에 대한 요청 및 응답 스키마가 이 문서에 나열된 스키마와 달랐습니다. 이전에는 오케스트레이션이 정적이었고 동일한 도구 시퀀스를 사용하여 답변을 생성했습니다. :code:`agent:run`은 이제 요청과 응답 모두에 대해 업데이트된 스키마를 제공합니다. 또한, 이 API는 이제 동적으로 오케스트레이션하고 반복하면서 최종 응답에 도달합니다. 최종 사용자 환경을 개선하려면 이 문서에 설명된 스키마를 사용하는 것이 좋습니다.

레거시 스키마와 동작을 사용하려면 다음 스키마를 사용합니다.

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

Copy

헤더 요청¶

헤더	설명
`Authorization`	(필수) 승인 토큰. 인증 섹션을 참조하십시오.
`Content-Type`	(필수) 애플리케이션/json

요청 본문¶

필드	타입	설명
`thread_id`	정수	대화의 스레드 ID입니다. thread_id가 사용되는 경우 parent_message_id도 전달해야 합니다.
`parent_message_id`	정수	스레드에 있는 상위 메시지의 ID입니다. 이것이 첫 번째 메시지인 경우 parent_message_id는 0이어야 합니다.
`messages`	:ref:`label_snowflake_agent_run_Message`의 배열	thread_id 및 parent_message_id가 요청에서 전달되는 경우 메시지의 대화에는 현재 사용자 메시지가 포함됩니다. 그렇지 않으면 메시지에는 대화 기록과 현재 메시지가 포함됩니다. 메시지에는 사용자 쿼리와 어시스턴트 응답이 모두 시간순으로 포함됩니다.
`tool_choice`	ToolChoice	에이전트가 상호 작용 중에 도구를 선택하고 사용하는 방법을 구성합니다. 도구 사용이 자동인지, 필수인지 또는 특정 도구를 사용해야 하는지를 제어합니다.
`models`	ModelConfig	에이전트의 모델 구성입니다. 오케스트레이션 모델을 포함합니다(예: clade-4-sonnet). 입력하지 않으면 모델이 자동으로 선택됩니다. 현재 `오케스트레이션` 단계에만 사용 가능합니다.
`instructions`	AgentInstructions	응답, 오케스트레이션, 시스템, 샘플 질문 등 에이전트의 동작에 대한 지침입니다.
`orchestration`	OrchestrationConfig	예산 제약 조건(예: 초, 토큰)을 포함한 오케스트레이션 구성입니다.
`tools`	:ref:`label_snowflake_agent_run_Tool`의 배열	에이전트가 사용할 수 있는 도구 목록입니다. 각 도구에는 유형, 이름, 설명, 입력 스키마가 있는 tool_spec이 포함됩니다. 도구의 tool_resources에 해당 구성이 있을 수 있습니다.
`tool_resources`	:ref:`label_snowflake_agent_run_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 이벤트를 대기하고 모든 이전 이벤트를 무시합니다.

스트리밍되는 대부분의 다른 이벤트는 두 가지 카테고리, 즉 델타 및 `콘텐츠 항목`으로 나눌 수 있습니다.

델타 이벤트는 에이전트가 생성한 단일 토큰을 나타냅니다. 이러한 이벤트를 수신하여 타자기 효과를 만들 수 있습니다. 주요 델타 이벤트는 추론 토큰을 나타내는 `response.Thinking.delta`와 응답 토큰을 나타내는 `response.text.delta`입니다.

콘텐츠 항목 이벤트는 최종 에이전트 응답의 콘텐츠 배열에 있는 요소를 나타냅니다.

참고

애플리케이션이 알 수 없는 이벤트 유형을 처리할 수 있는지 확인하세요.

응답 예

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`	:ref:`label_snowflake_agent_run_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`	문자열	에이전트의 텍스트 결과입니다
`annotations`	:ref:`label_snowflake_agent_run_Annotation`의 배열	텍스트 결과에 첨부된 모든 주석(예: 인용)입니다
`is_elicitation`	boolean	이 텍스트 콘텐츠가 최종 사용자에게 추가 정보를 요청하는 에이전트인지 여부입니다.

예

{
  "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`	문자열	텍스트 델타입니다.
`is_elicitation`	boolean	이 텍스트 콘텐츠가 최종 사용자에게 추가 정보를 요청하는 에이전트인지 여부입니다.

예

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

Copy

`response.text.annotation`¶

텍스트 콘텐츠에 주석이 추가될 때 스트리밍되는 이벤트입니다.

필드	타입	설명
`content_index`	정수	이 이벤트가 나타내는 응답 콘텐츠 배열의 인덱스입니다
`annotation_index`	정수	이 `주석`이 속한 주석 배열의 인덱스입니다.
`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_id`	문자열	이 도구 사용에 대한 고유 식별자입니다. 연결된 도구 결과에 사용할 수 있습니다.
`type`	문자열	도구의 유형(예: cortex_search, cortex_analyst_text2sql)입니다
`name`	문자열	이 도구 인스턴스의 고유 식별자입니다
`input`	오브젝트	이 도구의 정형 입력입니다. 이 오브젝트의 스키마는 도구 사양에 따라 달라집니다.
`client_side_execute`	boolean	도구 사용이 클라이언트 측에서 실행되는지 여부입니다.

예

{
  "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_id`	문자열	이 도구 사용에 대한 고유 식별자입니다. 연결된 도구 결과에 사용할 수 있습니다.
`type`	문자열	도구의 유형(예: cortex_search, cortex_analyst_text2sql)입니다
`name`	문자열	이 도구 인스턴스의 고유 식별자입니다
`content`	:ref:`label_snowflake_agent_run_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_id`	문자열	이 도구 사용에 대한 고유 식별자입니다.
`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_id`	문자열	이 도구 사용에 대한 고유 식별자입니다. 연결된 도구 결과에 사용할 수 있습니다.
`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`	문자열	이 테이블을 생성한 도구 사용의 ID입니다
`query_id`	문자열	이 데이터를 생성한 SQL 쿼리의 쿼리 ID입니다
`result_set`	ResultSet	테이블을 렌더링하기 위한 SQL 결과입니다. Snowflake의 SQL API ResultSet(https://docs.snowflake.com/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`	문자열	이 차트를 생성한 도구 사용의 ID입니다
`chart_spec`	문자열	문자열로 직렬화된 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` 이벤트¶

요청에 대한 메타데이터입니다. 이 이벤트는 메시지가 스레드에 추가될 때 전송됩니다. 에이전트 API에 대한 다음 요청에서 사용할 `parent_message_id`를 가져올 때 유용합니다.

필드	타입	설명
`role`	문자열	메시지를 보낸 사람(사용자 또는 어시스턴트)을 식별합니다.
`message_id`	정수	스레드 메시지 ID입니다. 이 ID(역할이 `어시스턴트`인 경우)를 사용하여 스레드에 대한 후속 질문을 할 수 있습니다.

예

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

index

정수

검색 결과의 인용 인덱스입니다.

search_result_id

문자열

검색 결과의 고유 식별자입니다.

doc_id

문자열

문서의 고유 식별자입니다.

doc_title

문자열

문서의 제목입니다.

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`)
`index`	정수	검색 결과의 인용 인덱스입니다.
`search_result_id`	문자열	검색 결과의 고유 식별자입니다.
`doc_id`	문자열	문서의 고유 식별자입니다.
`doc_title`	문자열	문서의 제목입니다.
`text`	문자열	인용으로 사용된 문서에서 발췌한 텍스트입니다.

`BudgetConfig`¶

필드	타입	설명
`seconds`	정수	시간 예산(초)입니다.
`tokens`	정수	토큰 예산입니다.

예

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

Copy

`ChartContent`¶

필드	타입	설명
`tool_use_id`	문자열	이 차트를 생성한 도구 사용의 ID입니다
`chart_spec`	문자열	문자열로 직렬화된 vega-lite 차트 사양입니다

예

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

Copy

`CortexAnalystSuggestionDelta`¶

필드	타입	설명
`index`	정수	이 델타가 나타내는 제안 배열의 인덱스입니다
`delta`	문자열	이 인덱스의 제안에 대한 텍스트 델타입니다

예

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

Copy

`CortexAnalystToolResultDelta`¶

필드	타입	설명
`text`	문자열	Cortex Analyst의 최종 응답에서 가져온 텍스트 델타입니다.
`think`	문자열	Cortex Analyst 추론 단계의 텍스트 델타입니다.
`sql`	문자열	Cortex Analyst SQL 출력의 델타입니다. 현재는 전체 SQL 쿼리가 단일 이벤트로 발생하지만 향후에는 토큰별로 SQL을 스트리밍할 수 있습니다.
`sql_explanation`	문자열	SQL 쿼리가 수행하는 작업에 대한 Cortex Analyst 설명에서 가져온 델타입니다
`query_id`	문자열	SQL 실행이 시작된 쿼리 ID입니다
`verified_query_used`	boolean	확인된 쿼리가 이 응답을 생성하는 데 사용되었는지 여부입니다
`result_set`	ResultSet	SQL 실행의 결과입니다. Snowflake의 SQL API ResultSet(https://docs.snowflake.com/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`	문자열	웨어하우스의 이름입니다. 대소문자를 구분하며, 따옴표가 없는 식별자인 경우 이름을 모두 대문자로 입력합니다.
`query_timeout`	정수	쿼리 시간 제한(초)입니다.

예

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

Copy

`Message`¶

대화의 단일 메시지를 나타냅니다. 사용자 또는 어시스턴트의 메시지일 수 있습니다.

필드	타입	설명
`role`	문자열	메시지를 보낸 사람(사용자 또는 어시스턴트)을 식별합니다. 사용자 메시지에는 일반적으로 쿼리가 포함되며, 어시스턴트 메시지에는 응답 및 도구 결과가 포함됩니다.
`content`	:ref:`label_snowflake_agent_run_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`	문자열	에이전트의 텍스트 결과입니다
`annotations`	:ref:`label_snowflake_agent_run_Annotation`의 배열	텍스트 결과에 첨부된 모든 주석(예: 인용)입니다
`is_elicitation`	boolean	이 텍스트 콘텐츠가 최종 사용자에게 추가 정보를 요청하는 에이전트인지 여부입니다.
`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`).
`thinking`	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`	배열의 배열	데이터를 나타내는 2D 배열입니다

예

{
  "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`	:ref:`label_snowflake_agent_run_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.com/en/sql-reference/intro-summary-data-types)
`length`	정수	열의 길이입니다.
`precision`	정수	열의 정밀도입니다.
`scale`	정수	열의 스케일입니다.
`nullable`	boolean	열이 null을 허용하는지를 지정합니다.

예

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

Copy

`TableContent`¶

필드	타입	설명
`tool_use_id`	문자열	이 테이블을 생성한 도구 사용의 ID입니다
`query_id`	문자열	이 데이터를 생성한 SQL 쿼리의 쿼리 ID입니다
`result_set`	ResultSet	테이블을 렌더링하기 위한 SQL 결과입니다. Snowflake의 SQL API ResultSet(https://docs.snowflake.com/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`	문자열	도구 선택 방법을 결정합니다. - 자동 - 자동 도구 선택(기본값) - 필수 - 하나 이상의 도구를 사용해야 함 - 도구 - 명명된 특정 도구 사용
`name`	문자열 배열	유형이 ‘도구’일 때 사용할 특정 도구 이름의 목록입니다.

예

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

Copy

`ToolInputSchema`¶

필드	타입	설명
`type`	문자열	입력 스키마 오브젝트의 유형입니다.
`description`	문자열	입력에 대한 설명입니다.
`properties`	:ref:`label_snowflake_agent_run_ToolInputSchema`의 맵	유형이 `오브젝트`인 경우 각 입력 매개 변수의 정의입니다.
`items`	ToolInputSchema	유형이 `배열`인 경우 배열의 요소에 대한 스키마입니다.
`required`	문자열 배열	유형이 `오브젝트`인 경우 필수 입력 매개 변수 이름의 목록입니다.

예

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

문자열

의미 체계 모델 yaml을 보유하는 Snowflake 스테이지에 저장된 파일의 경로입니다.

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`	문자열	의미 체계 모델 yaml을 보유하는 Snowflake 스테이지에 저장된 파일의 경로입니다.
`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_id`	문자열	이 도구 사용에 대한 고유 식별자입니다. 연결된 도구 결과에 사용할 수 있습니다.
`type`	문자열	도구의 유형(예: cortex_search, cortex_analyst_text2sql)입니다
`name`	문자열	이 도구 인스턴스의 고유 식별자입니다
`content`	:ref:`label_snowflake_agent_run_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_id`	문자열	이 도구 사용에 대한 고유 식별자입니다. 연결된 도구 결과에 사용할 수 있습니다.
`type`	문자열	도구의 유형(예: cortex_search, cortex_analyst_text2sql)입니다
`name`	문자열	이 도구 인스턴스의 고유 식별자입니다
`input`	오브젝트	이 도구의 정형 입력입니다. 이 오브젝트의 스키마는 도구 사양에 따라 달라집니다.
`client_side_execute`	boolean	도구 사용이 클라이언트 측에서 실행되는지 여부입니다.

예

{
  "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 실행 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`¶