Cortex Agents REST API

Cortex Agent REST API를 사용하여 Snowflake 계정에서 Cortex Agent 오브젝트를 생성, 관리 및 상호 작용할 수 있습니다.

Cortex Agent 만들기

POST /api/v2/databases/{database}/schemas/{schema}/agents

지정된 특성과 사양을 사용하여 새 Cortex Agent 오브젝트를 만듭니다.

요청

경로 매개 변수

매개 변수

설명

database

(필수) Snowflake 계정 URL입니다.

schema

(필수) 스키마 식별자입니다.

쿼리 매개 변수

매개 변수

설명

createMode

(선택 사항) 리소스 생성 모드입니다. 유효한 값:

  • errorIfExists

  • orReplace

  • ifNotExists

헤더 요청

헤더

설명

Authorization

(필수) 승인 토큰. 자세한 내용은 인증 섹션을 참조하십시오.

Content-Type

(필수) 애플리케이션/json

요청 본문

필드

타입

설명

name

문자열

에이전트의 이름입니다.

comment

문자열

에이전트에 대한 설명(선택 사항)입니다.

profile

AgentProfile

에이전트 프로필 정보(표시 이름, 아바타, 색상 등)입니다.

models

ModelConfig

에이전트의 모델 구성입니다. 오케스트레이션 모델을 포함합니다(예: clade-4-sonnet). 입력하지 않으면 모델이 자동으로 선택됩니다. 현재 오케스트레이션 단계에만 사용 가능합니다.

instructions

AgentInstructions

응답, 오케스트레이션, 시스템, 샘플 질문 등 에이전트의 동작에 대한 지침입니다.

orchestration

OrchestrationConfig

예산 제약 조건(예: 초, 토큰)을 포함한 오케스트레이션 구성입니다.

tools

:ref:`label_snowflake_agent_object_Tool`의 배열

에이전트가 사용할 수 있는 도구 목록입니다. 각 도구에는 유형, 이름, 설명, 입력 스키마가 있는 tool_spec이 포함됩니다. 도구의 tool_resources에 해당 구성이 있을 수 있습니다.

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

응답

성공적인 응답은 Cortex Agent 생성 상태에 대한 세부 정보가 있는 JSON 오브젝트를 반환합니다.

응답 본문

{"status": "Agent xxxx successfully created."}
Copy

Cortex Agent 설명

GET /api/v2/databases/{database}/schemas/{schema}/agents/{name}

Cortex Agent를 설명합니다.

요청

경로 매개 변수

매개 변수

설명

database

(필수) 리소스가 속한 데이터베이스의 식별자입니다. /api/v2/databases GET 요청을 사용하여 사용 가능한 데이터베이스 목록을 가져올 수 있습니다.

schema

(필수) 리소스가 속한 스키마의 식별자입니다. /api/v2/databases/{database}/schemas GET 요청을 사용하여 지정된 데이터베이스에 대해 사용 가능한 스키마 목록을 가져올 수 있습니다.

name

(필수) 에이전트의 식별자입니다.

헤더 요청

헤더

설명

Authorization

(필수) 승인 토큰. 자세한 내용은 인증 섹션을 참조하십시오.

Content-Type

(필수) 애플리케이션/json

응답

성공적인 응답은 Cortex Agent를 설명하는 JSON 오브젝트를 반환합니다.

응답 헤더

헤더

설명

X-Snowflake-Request-ID

API 요청의 고유 ID입니다.

Link

결과 페이지(예: 첫 번째 페이지, 마지막 페이지 등)에 대한 링크입니다. 헤더에는 반환할 페이지(첫 번째, 다음, 이전, 마지막)를 지정하는 서로 다른 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"
}
Copy

Cortex Agent 업데이트

PUT /api/v2/databases/{database}/schemas/{schema}/agents/{name}

지정된 특성 및 사양으로 기존 Cortex Agent를 업데이트합니다.

요청

경로 매개 변수

매개 변수

설명

database

(필수) Snowflake 계정 URL입니다. /api/v2/databases GET 요청을 사용하여 사용 가능한 데이터베이스 목록을 가져올 수 있습니다.

schema

(필수) 스키마 식별자입니다. /api/v2/databases/{database}/schemas GET 요청을 사용하여 지정된 데이터베이스에 대해 사용 가능한 스키마 목록을 가져올 수 있습니다.

name

(필수) 에이전트의 이름입니다.

헤더 요청

헤더

설명

Authorization

(필수) 승인 토큰. 자세한 내용은 인증 섹션을 참조하십시오.

Content-Type

(필수) 애플리케이션/json

요청 본문

필드

타입

설명

comment

문자열

에이전트에 대한 설명(선택 사항)입니다.

profile

AgentProfile

에이전트 프로필 정보(표시 이름, 아바타, 색상 등)입니다.

models

ModelConfig

에이전트의 모델 구성입니다. 오케스트레이션 모델을 포함합니다(예: clade-4-sonnet). 입력하지 않으면 모델이 자동으로 선택됩니다. 현재 오케스트레이션 단계에만 사용 가능합니다.

instructions

AgentInstructions

응답, 오케스트레이션, 시스템, 샘플 질문 등 에이전트의 동작에 대한 지침입니다.

orchestration

OrchestrationConfig

예산 제약 조건(예: 초, 토큰)을 포함한 오케스트레이션 구성입니다.

tools

:ref:`label_snowflake_agent_object_Tool`의 배열

에이전트가 사용할 수 있는 도구 목록입니다. 각 도구에는 유형, 이름, 설명, 입력 스키마가 있는 tool_spec이 포함됩니다. 도구의 tool_resources에 해당 구성이 있을 수 있습니다.

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

응답

성공적인 응답은 Cortex Agent 업데이트 상태에 대한 세부 정보가 있는 JSON 오브젝트를 반환합니다.

응답 본문

{"status": "Agent xxxx successfully updated."}
Copy

Cortex Agent 나열

GET /api/v2/databases/{database}/schemas/{schema}/agents

지정된 데이터베이스 및 스키마 아래에 Cortex Agent를 나열합니다.

요청

경로 매개 변수

매개 변수

설명

database

(필수) 리소스가 속한 데이터베이스의 식별자입니다. /api/v2/databases GET 요청을 사용하여 사용 가능한 데이터베이스 목록을 가져올 수 있습니다.

schema

(필수) 리소스가 속한 스키마의 식별자입니다. /api/v2/databases/{database}/schemas GET 요청을 사용하여 지정된 데이터베이스에 대해 사용 가능한 스키마 목록을 가져올 수 있습니다.

쿼리 매개 변수

매개 변수

설명

like

(선택 사항) 리소스 이름을 기준으로 출력을 필터링합니다. SQL 와일드카드 문자를 지원하며 대소문자를 구분하지 않는 패턴 일치를 사용합니다.

fromName

(선택 사항) 지정된 문자열과 일치하는 오브젝트 이름의 첫 번째 행 이후의 행만 가져옵니다. 대소문자를 구분하며 전체 이름일 필요는 없습니다.

showLimit

(선택 사항) 명령에서 반환되는 최대 행 수를 제한합니다. 최소: 1. 최대: 10,000.

헤더 요청

헤더

설명

Authorization

(필수) 승인 토큰. 자세한 내용은 인증 섹션을 참조하십시오.

Content-Type

(필수) 애플리케이션/json

응답

성공적인 응답은 Cortex Agent 리소스의 JSON 배열을 반환합니다.

응답 헤더

헤더

설명

X-Snowflake-Request-ID

API 요청의 고유 ID입니다.

Link

결과 페이지(예: 첫 번째 페이지, 마지막 페이지 등)에 대한 링크입니다. 헤더에는 반환할 페이지(첫 번째, 다음, 이전, 마지막)를 지정하는 서로 다른 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": ""
 }
]
Copy

Cortex Agent 삭제

DELETE /api/v2/databases/{database}/schemas/{schema}/agents/{name}

지정된 이름을 가진 Cortex Agent를 삭제합니다. ifExists 매개 변수가 :code:`true`로 설정되면 에이전트가 존재하지 않더라도 작업이 성공합니다. 그렇지 않은 경우 에이전트를 삭제할 수 없으면 작업이 실패합니다.

요청

경로 매개 변수

매개 변수

설명

database

(필수) 리소스가 속한 데이터베이스의 식별자입니다. /api/v2/databases GET 요청을 사용하여 사용 가능한 데이터베이스 목록을 가져올 수 있습니다.

schema

(필수) 리소스가 속한 스키마의 식별자입니다. /api/v2/databases/{database}/schemas GET 요청을 사용하여 지정된 데이터베이스에 대해 사용 가능한 스키마 목록을 가져올 수 있습니다.

name

(필수) 에이전트의 식별자입니다.

쿼리 매개 변수

매개 변수

설명

ifExists

(선택 사항) 에이전트가 없는 경우 요청을 처리하는 방법을 지정합니다.

  • true: 에이전트가 존재하지 않으면 엔드포인트에서 오류가 발생하지 않습니다. 200 성공 응답을 반환하지만 아무런 작업도 수행하지 않습니다.

  • false: 에이전트가 존재하지 않으면 엔드포인트에서 오류가 발생합니다.

헤더 요청

헤더

설명

Authorization

(필수) 승인 토큰. 자세한 내용은 인증 섹션을 참조하십시오.

Content-Type

(필수) 애플리케이션/json

응답

성공적인 응답은 확인 메시지를 반환합니다.

응답 본문

{
 "status": "Request successfully completed"
}
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

AgentProfile

Data Cortex 에이전트에 대한 프로필 정보입니다.

필드

타입

설명

display_name

문자열

에이전트의 표시 이름입니다.

{
  "display_name": "My Agent"
}
Copy

BudgetConfig

필드

타입

설명

seconds

정수

시간 예산(초)입니다.

tokens

정수

토큰 예산입니다.

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

ExecutionEnvironment

서버 실행 도구에 대한 구성입니다.

필드

타입

설명

type

문자열

실행 환경의 유형으로, 현재 `웨어하우스`만 지원됩니다.

warehouse

문자열

웨어하우스의 이름입니다. 대소문자를 구분하며, 따옴표가 없는 식별자인 경우 이름을 모두 대문자로 입력합니다.

query_timeout

정수

쿼리 시간 제한(초)입니다.

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

ModelConfig

필드

타입

설명

orchestration

문자열

오케스트레이션에 사용할 모델입니다. 입력하지 않으면 모델이 자동으로 선택됩니다.

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

OrchestrationConfig

필드

타입

설명

budget

BudgetConfig

에이전트에 대한 예산 제약 조건입니다. 둘 이상의 제약 조건이 지정된 경우, 먼저 충족되는 제약 조건에 따라 요청이 종료됩니다.

{
  "budget": {
    "seconds": 30,
    "tokens": 16000
  }
}
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

ToolInputSchema

필드

타입

설명

type

문자열

입력 스키마 오브젝트의 유형입니다.

description

문자열

입력에 대한 설명입니다.

properties

:ref:`label_snowflake_agent_object_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

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