Cortex Agents REST API¶
Cortex Agent REST API를 사용하여 Snowflake 계정에서 Cortex Agent 오브젝트를 생성, 관리 및 상호 작용할 수 있습니다.
Cortex Agent 만들기¶
POST /api/v2/databases/{database}/schemas/{schema}/agents
지정된 특성과 사양을 사용하여 새 Cortex Agent 오브젝트를 만듭니다.
요청¶
경로 매개 변수¶
매개 변수 |
설명 |
|---|---|
|
(필수) Snowflake 계정 URL입니다. |
|
(필수) 스키마 식별자입니다. |
쿼리 매개 변수¶
매개 변수 |
설명 |
|---|---|
|
(선택 사항) 리소스 생성 모드입니다. 유효한 값:
|
헤더 요청¶
헤더 |
설명 |
|---|---|
|
(필수) 승인 토큰. 자세한 내용은 인증 섹션을 참조하십시오. |
|
(필수) 애플리케이션/json |
요청 본문¶
필드 |
타입 |
설명 |
|---|---|---|
|
문자열 |
에이전트의 이름입니다. |
|
문자열 |
에이전트에 대한 설명(선택 사항)입니다. |
|
에이전트 프로필 정보(표시 이름, 아바타, 색상 등)입니다. |
|
|
에이전트의 모델 구성입니다. 오케스트레이션 모델을 포함합니다(예: clade-4-sonnet). 입력하지 않으면 모델이 자동으로 선택됩니다. 현재 |
|
|
응답, 오케스트레이션, 시스템, 샘플 질문 등 에이전트의 동작에 대한 지침입니다. |
|
|
예산 제약 조건(예: 초, 토큰)을 포함한 오케스트레이션 구성입니다. |
|
|
:ref:`label_snowflake_agent_object_Tool`의 배열 |
에이전트가 사용할 수 있는 도구 목록입니다. 각 도구에는 유형, 이름, 설명, 입력 스키마가 있는 tool_spec이 포함됩니다. 도구의 tool_resources에 해당 구성이 있을 수 있습니다. |
|
:ref:`label_snowflake_agent_object_ToolResource`의 맵 |
도구 배열에서 참조되는 각 도구에 대한 구성입니다. 키는 해당 도구의 이름과 일치해야 합니다. |
예
{
"name": "MY_AGENT",
"comment": "An agent to answer questions about all my data",
"profile": {
"display_name": "My Agent"
},
"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"
}
}
}
응답¶
성공적인 응답은 Cortex Agent 생성 상태에 대한 세부 정보가 있는 JSON 오브젝트를 반환합니다.
응답 본문¶
{"status": "Agent xxxx successfully created."}
Cortex Agent 설명¶
GET /api/v2/databases/{database}/schemas/{schema}/agents/{name}
Cortex Agent를 설명합니다.
요청¶
경로 매개 변수¶
매개 변수 |
설명 |
|---|---|
|
(필수) 리소스가 속한 데이터베이스의 식별자입니다. /api/v2/databases GET 요청을 사용하여 사용 가능한 데이터베이스 목록을 가져올 수 있습니다. |
|
(필수) 리소스가 속한 스키마의 식별자입니다. /api/v2/databases/{database}/schemas GET 요청을 사용하여 지정된 데이터베이스에 대해 사용 가능한 스키마 목록을 가져올 수 있습니다. |
|
(필수) 에이전트의 식별자입니다. |
헤더 요청¶
헤더 |
설명 |
|---|---|
|
(필수) 승인 토큰. 자세한 내용은 인증 섹션을 참조하십시오. |
|
(필수) 애플리케이션/json |
응답¶
성공적인 응답은 Cortex Agent를 설명하는 JSON 오브젝트를 반환합니다.
응답 헤더¶
헤더 |
설명 |
|---|---|
|
API 요청의 고유 ID입니다. |
|
결과 페이지(예: 첫 번째 페이지, 마지막 페이지 등)에 대한 링크입니다. 헤더에는 반환할 페이지(첫 번째, 다음, 이전, 마지막)를 지정하는 서로 다른 rel 특성 값을 가진 여러 URL 항목이 포함될 수 있습니다. |
응답 본문¶
응답 본문에는 Cortex Agent의 세부 정보가 포함됩니다.
{
"agent_spec": "{\"models\":{\"orchestration\":\"llama3.1-70B\"},\"experimental\":{\"foo\":\"bar\",\"nested\":{\"key\":\"value\"}},\"orchestration\":{\"budget\":{\"seconds\":30,\"tokens\":16000}},\"instructions\":{\"response\":\"You will respond in a friendly but concise manner\",\"orchestration\":\"For any revenue question use Analyst; for policy use Search\",\"system\":\"You are a friendly agent.\",\"sample_questions\":[{\"question\":\"question 1\"},{\"question\":\"question 2\"},{\"question\":\"question 3\"}]},\"tools\":[{\"tool_spec\":{\"type\":\"cortex_analyst_text_to_sql\",\"name\":\"Analyst1\",\"description\":\"test\"}},{\"tool_spec\":{\"type\":\"cortex_analyst_sql_exec\",\"name\":\"SQL_exec1\"}},{\"tool_spec\":{\"type\":\"cortex_search\",\"name\":\"Search1\"}},{\"tool_spec\":{\"type\":\"web_search\",\"name\":\"web_search_1\"}},{\"tool_spec\":{\"type\":\"generic\",\"name\":\"get_weather\",\"input_schema\":{\"type\":\"object\",\"properties\":{\"location\":{\"type\":\"string\",\"description\":\"The city and state\"}},\"required\":[\"Location\"]}}}],\"tool_unable_to_answer\":\"I don't know the answer to that\",\"tool_resources\":{\"Analyst1\":{\"semantic_model_file\":\"stage1\"},\"Analyst2\":{\"semantic_view\":\"db.schema.semantic_view\"},\"Search1\":{\"name\":\"db.schema.service_name\",\"Max_results\":\"5\",\"filter\":{\"@eq\":{\"region\":\"North America\"}},\"Title_column\":\"<title_name>\",\"ID_column\":\"<column_name>\"},\"SQL_exec1\":{\"Name\":\"my_warehouse\",\"Timeout\":\"30\",\"AutoExecute\":\"true\"},\"web_search\":{\"name\":\"web_search_1\",\"Function\":\"db/schema/search_web\"}}}",
"name": "MY_AGENT1",
"database_name": "TEST_DATABASE",
"schema_name": "TEST_SCHEMA",
"owner": "ACCOUNTADMIN",
"created_on": "1967-06-23T07:00:00.123+00:00"
}
Cortex Agent 업데이트¶
PUT /api/v2/databases/{database}/schemas/{schema}/agents/{name}
지정된 특성 및 사양으로 기존 Cortex Agent를 업데이트합니다.
요청¶
경로 매개 변수¶
매개 변수 |
설명 |
|---|---|
|
(필수) Snowflake 계정 URL입니다. |
|
(필수) 스키마 식별자입니다. |
|
(필수) 에이전트의 이름입니다. |
헤더 요청¶
헤더 |
설명 |
|---|---|
|
(필수) 승인 토큰. 자세한 내용은 인증 섹션을 참조하십시오. |
|
(필수) 애플리케이션/json |
요청 본문¶
필드 |
타입 |
설명 |
|---|---|---|
|
문자열 |
에이전트에 대한 설명(선택 사항)입니다. |
|
에이전트 프로필 정보(표시 이름, 아바타, 색상 등)입니다. |
|
|
에이전트의 모델 구성입니다. 오케스트레이션 모델을 포함합니다(예: clade-4-sonnet). 입력하지 않으면 모델이 자동으로 선택됩니다. 현재 |
|
|
응답, 오케스트레이션, 시스템, 샘플 질문 등 에이전트의 동작에 대한 지침입니다. |
|
|
예산 제약 조건(예: 초, 토큰)을 포함한 오케스트레이션 구성입니다. |
|
|
:ref:`label_snowflake_agent_object_Tool`의 배열 |
에이전트가 사용할 수 있는 도구 목록입니다. 각 도구에는 유형, 이름, 설명, 입력 스키마가 있는 tool_spec이 포함됩니다. 도구의 tool_resources에 해당 구성이 있을 수 있습니다. |
|
:ref:`label_snowflake_agent_object_ToolResource`의 맵 |
도구 배열에서 참조되는 각 도구에 대한 구성입니다. 키는 해당 도구의 이름과 일치해야 합니다. |
예
{
"comment": "An agent to answer questions about all my data",
"profile": {
"display_name": "My Agent"
},
"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"
}
}
}
응답¶
성공적인 응답은 Cortex Agent 업데이트 상태에 대한 세부 정보가 있는 JSON 오브젝트를 반환합니다.
응답 본문¶
{"status": "Agent xxxx successfully updated."}
Cortex Agent 나열¶
GET /api/v2/databases/{database}/schemas/{schema}/agents
지정된 데이터베이스 및 스키마 아래에 Cortex Agent를 나열합니다.
요청¶
경로 매개 변수¶
매개 변수 |
설명 |
|---|---|
|
(필수) 리소스가 속한 데이터베이스의 식별자입니다. /api/v2/databases GET 요청을 사용하여 사용 가능한 데이터베이스 목록을 가져올 수 있습니다. |
|
(필수) 리소스가 속한 스키마의 식별자입니다. /api/v2/databases/{database}/schemas GET 요청을 사용하여 지정된 데이터베이스에 대해 사용 가능한 스키마 목록을 가져올 수 있습니다. |
쿼리 매개 변수¶
매개 변수 |
설명 |
|---|---|
|
(선택 사항) 리소스 이름을 기준으로 출력을 필터링합니다. SQL 와일드카드 문자를 지원하며 대소문자를 구분하지 않는 패턴 일치를 사용합니다. |
|
(선택 사항) 지정된 문자열과 일치하는 오브젝트 이름의 첫 번째 행 이후의 행만 가져옵니다. 대소문자를 구분하며 전체 이름일 필요는 없습니다. |
|
(선택 사항) 명령에서 반환되는 최대 행 수를 제한합니다. 최소: 1. 최대: 10,000. |
헤더 요청¶
헤더 |
설명 |
|---|---|
|
(필수) 승인 토큰. 자세한 내용은 인증 섹션을 참조하십시오. |
|
(필수) 애플리케이션/json |
응답¶
성공적인 응답은 Cortex Agent 리소스의 JSON 배열을 반환합니다.
응답 헤더¶
헤더 |
설명 |
|---|---|
|
API 요청의 고유 ID입니다. |
|
결과 페이지(예: 첫 번째 페이지, 마지막 페이지 등)에 대한 링크입니다. 헤더에는 반환할 페이지(첫 번째, 다음, 이전, 마지막)를 지정하는 서로 다른 rel 특성 값을 가진 여러 URL 항목이 포함될 수 있습니다. |
응답 본문¶
[
{
"name": "my_agent",
"database": "TEST_DB",
"schema": "TEST_SCHEMA",
"created_on": "2024-06-01T12:00:00Z",
"owner": "ACCOUNTADMIN",
"comment": "Sample agent"
},
{
"name": "another_agent",
"database": "TEST_DB",
"schema": "TEST_SCHEMA",
"created_on": "2024-06-02T08:30:00Z",
"owner": "SYSADMIN",
"comment": ""
}
]
Cortex Agent 삭제¶
DELETE /api/v2/databases/{database}/schemas/{schema}/agents/{name}
지정된 이름을 가진 Cortex Agent를 삭제합니다. ifExists 매개 변수가 :code:`true`로 설정되면 에이전트가 존재하지 않더라도 작업이 성공합니다. 그렇지 않은 경우 에이전트를 삭제할 수 없으면 작업이 실패합니다.
요청¶
경로 매개 변수¶
매개 변수 |
설명 |
|---|---|
|
(필수) 리소스가 속한 데이터베이스의 식별자입니다. /api/v2/databases GET 요청을 사용하여 사용 가능한 데이터베이스 목록을 가져올 수 있습니다. |
|
(필수) 리소스가 속한 스키마의 식별자입니다. /api/v2/databases/{database}/schemas GET 요청을 사용하여 지정된 데이터베이스에 대해 사용 가능한 스키마 목록을 가져올 수 있습니다. |
|
(필수) 에이전트의 식별자입니다. |
쿼리 매개 변수¶
매개 변수 |
설명 |
|---|---|
|
(선택 사항) 에이전트가 없는 경우 요청을 처리하는 방법을 지정합니다.
|
헤더 요청¶
헤더 |
설명 |
|---|---|
|
(필수) 승인 토큰. 자세한 내용은 인증 섹션을 참조하십시오. |
|
(필수) 애플리케이션/json |
응답¶
성공적인 응답은 확인 메시지를 반환합니다.
응답 본문¶
{
"status": "Request successfully completed"
}
스키마¶
AgentInstructions¶
필드 |
타입 |
설명 |
|---|---|---|
|
문자열 |
응답 생성 지침입니다. |
|
문자열 |
이러한 사용자 지정 지침은 에이전트가 사용할 도구를 계획할 때 사용됩니다. |
|
문자열 |
에이전트에 대한 시스템 지침입니다. |
예
{
"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 ..."
}
AgentProfile¶
Data Cortex 에이전트에 대한 프로필 정보입니다.
필드 |
타입 |
설명 |
|---|---|---|
|
문자열 |
에이전트의 표시 이름입니다. |
예
{
"display_name": "My Agent"
}
BudgetConfig¶
필드 |
타입 |
설명 |
|---|---|---|
|
정수 |
시간 예산(초)입니다. |
|
정수 |
토큰 예산입니다. |
예
{
"seconds": 30,
"tokens": 16000
}
ExecutionEnvironment¶
서버 실행 도구에 대한 구성입니다.
필드 |
타입 |
설명 |
|---|---|---|
|
문자열 |
실행 환경의 유형으로, 현재 `웨어하우스`만 지원됩니다. |
|
문자열 |
웨어하우스의 이름입니다. 대소문자를 구분하며, 따옴표가 없는 식별자인 경우 이름을 모두 대문자로 입력합니다. |
|
정수 |
쿼리 시간 제한(초)입니다. |
예
{
"type": "warehouse",
"warehouse": "MY_WAREHOUSE",
"query_timeout": 60
}
ModelConfig¶
필드 |
타입 |
설명 |
|---|---|---|
|
문자열 |
오케스트레이션에 사용할 모델입니다. 입력하지 않으면 모델이 자동으로 선택됩니다. |
예
{
"orchestration": "claude-4-sonnet"
}
OrchestrationConfig¶
필드 |
타입 |
설명 |
|---|---|---|
|
에이전트에 대한 예산 제약 조건입니다. 둘 이상의 제약 조건이 지정된 경우, 먼저 충족되는 제약 조건에 따라 요청이 종료됩니다. |
예
{
"budget": {
"seconds": 30,
"tokens": 16000
}
}
Tool¶
에이전트가 사용할 수 있는 도구를 정의합니다. 도구는 데이터 분석, 검색 또는 일반 함수와 같은 특정 기능을 제공합니다.
필드 |
타입 |
설명 |
|---|---|---|
|
도구의 유형, 구성 및 입력 요구 사항에 대한 사양입니다. |
예
{
"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"
]
}
}
ToolInputSchema¶
필드 |
타입 |
설명 |
|---|---|---|
|
문자열 |
입력 스키마 오브젝트의 유형입니다. |
|
문자열 |
입력에 대한 설명입니다. |
|
:ref:`label_snowflake_agent_object_ToolInputSchema`의 맵 |
유형이 `오브젝트`인 경우 각 입력 매개 변수의 정의입니다. |
|
유형이 `배열`인 경우 배열의 요소에 대한 스키마입니다. |
|
|
문자열 배열 |
유형이 `오브젝트`인 경우 필수 입력 매개 변수 이름의 목록입니다. |
예
{
"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¶
텍스트-SQL 분석 도구의 구성입니다. SQL 쿼리 생성 및 실행에 대한 매개 변수를 제공합니다. semantic_model_file 또는 semantic_view 중 정확히 하나를 입력해야 합니다.
필드
타입
설명
semantic_model_file문자열
의미 체계 모델 yaml을 보유하는 Snowflake 스테이지에 저장된 파일의 경로입니다.
semantic_view문자열
Snowflake 네이티브 의미 체계 모델 오브젝트의 이름입니다.
execution_environment생성된 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 } }검색 기능에 대한 구성입니다. 문서 검색 및 가져오기를 수행하는 방법을 정의합니다.
필드
타입
설명
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>" } } }
필드
타입
설명
type문자열
도구가 서버 측에서 실행되는 경우 저장 프로시저 또는 UDF입니다.
execution_environment
identifier문자열
저장 프로시저의 정규화된 이름 또는 UDF입니다.
예
{ "type": "function", "execution_environment": { "type": "warehouse", "warehouse": "MY_WAREHOUSE", "query_timeout": 60 }, "identifier": "MY_DB.MY_SCHEMA.MY_UDF" }
ToolSpec¶
도구의 유형, 구성 및 입력 요구 사항에 대한 사양입니다.
필드 |
타입 |
설명 |
|---|---|---|
|
문자열 |
도구 기능의 유형입니다. 범용 도구의 경우 ‘cortex_analyst_text_to_sql’ 또는 ‘generic’과 같은 특수 유형일 수 있습니다. |
|
문자열 |
이 도구 인스턴스를 참조하기 위한 고유 식별자입니다. tool_resources의 구성과 일치시키는 데 사용됩니다. |
|
문자열 |
도구 사용을 고려할 때 검토할 도구에 대한 설명입니다. |
|
이 도구에 예상되는 입력 매개 변수의 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"
]
}
}