CREATE AGENT¶

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

참고 항목:: ALTER AGENT, DESCRIBE AGENT, DROP AGENT, SHOW AGENTS, DATA_AGENT_RUN(SNOWFLAKE.CORTEX)

구문¶

CREATE [ OR REPLACE ] AGENT [ IF NOT EXISTS ] <name>
  [ COMMENT = '<comment>' ]
  [ PROFILE = '<profile_object>' ]
  FROM SPECIFICATION
  $$
  <specification_object>
  $$;

필수 매개 변수¶

name

에이전트의 식별자(즉, 이름)를 지정하는 문자열로, 에이전트가 생성되는 스키마에 대해 고유해야 합니다.

또한, 식별자는 알파벳 문자로 시작해야 하며 전체 식별자 문자열을 큰따옴표(예: "My object")로 묶지 않는 한 공백이나 특수 문자를 포함할 수 없습니다. 큰따옴표로 묶인 식별자도 대/소문자를 구분합니다.

자세한 내용은 식별자 요구 사항 섹션을 참조하십시오.

선택적 매개 변수¶

COMMENT = comment

에이전트에 대한 설명입니다.

PROFILE = profile_object

표시 이름, 아바타, 색상과 같은 에이전트 프로필 정보가 포함된 OBJECT 값을 지정합니다. :code:`profile_object`를 다음과 같이 문자열로 직렬화합니다.

'{"display_name": "<display_name>", "avatar": "<avatar>", "color": "<color>"}'

다음 테이블은 이 오브젝트의 키-값 페어를 설명합니다.


키	타입	설명
`display_name`	String	에이전트의 표시 이름입니다.
`avatar`	String	아바타 이미지 파일 이름 또는 식별자입니다.
`color`	String	에이전트의 색상 테마(예: “파란색”, “녹색”, “빨간색”)입니다.

FROM SPECIFICATION $$ specification_object $$

에이전트에 대한 설정을 포함하는 VARCHAR 값을 YAML 오브젝트로 지정합니다. 사양 오브젝트의 최대 길이는 100,000바이트입니다.

YAML 오브젝트의 구조는 다음과 같아야 합니다.

models:
  orchestration: <model_name>

orchestration:
  budget:
      seconds: <number_of_seconds>
      tokens: <number_of_tokens>

instructions:
  response: '<response_instructions>'
  orchestration: '<orchestration_instructions>'
  system: '<system_instructions>'
  sample_questions:
      - question: '<sample_question>'
        answer: '<sample_answer>'
      ...

tools:
  - tool_spec:
      type: '<tool_type>'
      name: '<tool_name>'
      description: '<tool_description>'
      input_schema:
          type: 'object'
          properties:
            <property_name>:
              type: '<property_type>'
              description: '<property_description>'
          required: <required_property_names>
  ...

tool_resources:
  <tool_name>:
    <resource_key>: '<resource_value>'
    ...
  ...

다음 테이블은 이 오브젝트의 키-값 페어를 설명합니다.


키	타입	설명
`models`	ModelConfig	에이전트에 대한 선택적 모델 구성입니다. 오케스트레이션 모델을 포함합니다(예: clade-4-sonnet). 입력하지 않으면 모델이 자동으로 선택됩니다. 현재 `오케스트레이션` 단계에만 사용 가능합니다.
`orchestration`	OrchestrationConfig	예산 제약 조건(예: 초, 토큰)을 포함한 선택적 오케스트레이션 구성입니다.
`instructions`	AgentInstructions	응답, 오케스트레이션, 시스템, 샘플 질문 등 에이전트의 동작에 대한 선택적 지침입니다.
`tools`	:ref:`label_snowflake_agent_object_Tool`의 배열	에이전트가 사용할 수 있는 선택적 도구 목록입니다. 각 도구에는 유형, 이름, 설명, 입력 스키마가 있는 :code:`tool_spec`이 포함됩니다. 도구의 :code:`tool_resources`에 해당 구성이 있을 수 있습니다.
`tool_resources`	:ref:`label_snowflake_agent_object_ToolResource`의 맵	도구 배열에서 참조되는 각 도구에 대한 선택적 구성입니다. 키는 해당 도구의 이름과 일치해야 합니다.

액세스 제어 요구 사항¶

이 작업을 실행하는 데 사용되는 역할 에는 최소한 다음 권한 이 있어야 합니다.


권한	오브젝트	참고
CREATE AGENT	스키마	Cortex Agent를 생성하는 데 필요합니다.
USAGE	Cortex Search Service	Cortex Agent 요청에서 Cortex Search Service를 실행하는 데 필요합니다.
USAGE	데이터베이스, 스키마, 테이블	Cortex Agent 의미 체계 모델에서 참조되는 오브젝트에 액세스하는 데 필요합니다.

사용법 노트¶

OR REPLACE 및 IF NOT EXISTS 절은 상호 배타적입니다. 같은 문에서 둘 다 사용할 수는 없습니다.
CREATE OR REPLACE <오브젝트> 문은 원자성입니다. 즉, 오브젝트가 바뀔 때 단일 트랜잭션으로 이전 오브젝트가 삭제되고 새 오브젝트가 생성됩니다.

메타데이터 관련:

주의

고객은 Snowflake 서비스를 사용할 때 개인 데이터(사용자 오브젝트 제외), 민감한 데이터, 수출 통제 대상 데이터 또는 기타 규제 데이터가 메타데이터로 입력되지 않도록 해야 합니다. 자세한 내용은 Snowflake의 메타데이터 필드 섹션을 참조하십시오.

예¶

CREATE OR REPLACE AGENT my_agent1
  COMMENT = 'agent level comment'
  PROFILE = '{"display_name": "My Business Assistant", "avatar":  "business-icon.png", "color": "blue"}'
  FROM SPECIFICATION
  $$
  models:
    orchestration: claude-4-sonnet

  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 that helps with business questions"
    sample_questions:
      - question: "What was our revenue last quarter?"
        answer: "I'll analyze the revenue data using our financial database."

  tools:
    - tool_spec:
        type: "cortex_analyst_text_to_sql"
        name: "Analyst1"
        description: "Converts natural language to SQL queries for financial analysis"
    - tool_spec:
        type: "cortex_search"
        name: "Search1"
        description: "Searches company policy and documentation"

  tool_resources:
    Analyst1:
      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>"
  $$;