에이전트 수정하기

에이전트 수정하기 (ALTER AGENT)

이 기능은 중화인민공화국에서는 사용할 수 없어요.

기존 Cortex Agent의 속성 또는 사양을 수정해요.

참고:

CREATE AGENT, DESCRIBE AGENT, DROP AGENT, SHOW AGENTS

출처: 문서

본문

구문

ALTER AGENT  SET
  [ COMMENT = '' ]
  [ PROFILE = '' ]
  [ SECURE = { TRUE | FALSE } ]

ALTER AGENT  MODIFY LIVE VERSION SET SPECIFICATION = 

ALTER AGENT  SET TAG  = '' [ ,  = '' ... ]

ALTER AGENT  UNSET TAG  [ ,  ... ]

필수 매개변수

name

변경할 에이전트의 식별자(즉, 이름)를 지정하는 String이에요.

식별자에 공백이나 특수 문자가 포함된 경우 전체 문자열을 큰따옴표로 묶어야 해요. 큰따옴표로 묶인 식별자는 대소문자를 구분해요.

자세한 내용은 Identifier requirements를 참조하세요.

선택적 매개변수

SET ...

에이전트에 대해 하나 이상의 지정된 속성 또는 매개변수를 설정해요:

COMMENT = comment

에이전트의 설명을 지정해요.

PROFILE = string

에이전트 프로필 정보(표시 이름, 아바타, 색상 등)를 지정해요. 문자열은 다음과 같이 형식화해요:

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

다음 표는 문자열의 키-값 쌍을 설명해요:

Key	Type	Description
`display_name`	String	에이전트의 표시 이름.
`avatar`	String	아바타 이미지 파일 이름 또는 식별자.
`color`	String	에이전트의 색상 테마(예: "blue", "green", "red")

SECURE = { TRUE | FALSE }

에이전트의 보안 여부를 설정해요:

TRUE는 에이전트를 보안 상태로 표시해요. 전체 사양은 소유자 역할이 활성화된 경우에만 볼 수 있어요.
FALSE는 보안 지정을 제거해요. 공유 또는 Native App 내보내기의 에이전트를 보안 상태로 유지해야 하는 공유 제어가 있는 경우 Snowflake는 오류 093932(SHARED_AGENT_CANT_BE_UNSECURE)를 반환해요. 이 속성을 FALSE로 설정하기 전에 에이전트의 공유 및 애플리케이션 역할에 대한 권한을 취소하세요.

자세한 내용은 Secure agents를 참조하세요.

MODIFY LIVE VERSION SET SPECIFICATION specification

에이전트의 대체 설정을 YAML 또는 JSON 객체로 포함하는 VARCHAR 값을 지정해요:

Dollar-quoted literal: $$ ... $$
Single-quoted string: '...'

사양 객체의 최대 길이는 100,000바이트예요.

새 사양은 기존 사양을 완전히 대체해요. 새 사양에 포함되지 않은 필드는 제거돼요.

YAML 객체는 다음 구조여야 해요:

models:
  orchestration: 

orchestration:
  capabilities:
    analytical_search: true
  tool_not_accessible: 
  budget:
      seconds: 
      tokens: 

instructions:
  response: ''
  orchestration: ''
  sample_questions:
      - question: ''
      ...

tools:
  - tool_spec:
      type: ''
      name: ''
      description: ''
      input_schema:
          type: 'object'
          properties:
            :
              type: ''
              description: ''
          required: 
  ...

tool_resources:
  :
    : ''
    ...
  ...

JSON 객체는 다음 구조여야 해요:

{
  "models": {
    "orchestration": ""
  },
  "orchestration": {
    "capabilities": {
      "analytical_search": true
    },
    "tool_not_accessible": "",
    "budget": {
      "seconds": ,
      "tokens": 
    }
  },
  "instructions": {
    "response": "",
    "orchestration": "",
    "sample_questions": [
      {
        "question": ""
      }
    ]
  },
  "tools": [
    {
      "tool_spec": {
        "type": "",
        "name": "",
        "description": "",
        "input_schema": {
          "type": "object",
          "properties": {
            "": {
              "type": "",
              "description": ""
            }
          },
          "required": [""]
        }
      }
    }
  ],
  "tool_resources": {
    "": {
      "": ""
    }
  }
}

다음 표는 이 객체의 키-값 쌍을 설명해요:

  키
  유형
  설명




  `models`
  [](/user-guide/snowflake-cortex/cortex-agents-rest-api#label-snowflake-agent-object-modelconfig)
  에이전트의 선택적 모델 구성이에요. 오케스트레이션 모델(예: claude-4-sonnet)을 포함해요. 제공하지 않으면 모델이 자동으로 선택돼요. 현재 _orchestration_ 단계에서만 사용할 수 있어요.


  `orchestration`
  [](/user-guide/snowflake-cortex/cortex-agents-rest-api#label-snowflake-agent-object-orchestrationconfig)
  선택적 오케스트레이션 구성이에요. 예산 제약(초, 토큰), `analytical_search`와 같은 기능, `tool_not_accessible`(`accept`, `reject`, 또는 `legacy`)을 포함해요. `tool_not_accessible`을 생략하면 기본값은 `accept`예요. 자세한 내용은 [Inaccessible tool handling](/user-guide/snowflake-cortex/cortex-agents-inaccessible-tool-handling)을 참조하세요.


  `instructions`
  [](/user-guide/snowflake-cortex/cortex-agents-rest-api#label-snowflake-agent-object-agentinstructions)
  에이전트 동작에 대한 선택적 지침이에요. 응답, 오케스트레이션, 샘플 질문을 포함해요.


  `tools`
  array of [](/user-guide/snowflake-cortex/cortex-agents-rest-api#label-snowflake-agent-object-tool)
  에이전트가 사용할 수 있는 선택적 도구 목록이에요. 각 도구에는 유형, 이름, 설명, 입력 스키마가 있는 `tool_spec`이 포함돼요. 도구는 `tool_resources`에 해당 구성이 있을 수 있어요.


  `tool_resources`
  map of [](/user-guide/snowflake-cortex/cortex-agents-rest-api#label-snowflake-agent-object-toolresource)
  tools 배열에서 참조되는 각 도구에 대한 선택적 구성이에요. 키는 해당 도구의 이름과 일치해야 해요.

SET TAG tag_name = 'tag_value' [ , tag_name = 'tag_value' ... ]

TAG tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ]

tag 이름과 태그 문자열 값을 지정해요.

태그 값은 항상 문자열이며, 태그 값의 최대 문자 수는 256자예요.

문에서 태그를 지정하는 방법에 대한 자세한 내용은 를 참조하세요.

UNSET TAG tag_name [ , tag_name ... ]

에이전트에서 해제할 하나 이상의 태그를 지정해요:

tag_name [ , tag_name ... ]

단일 ALTER 문으로 여러 속성 또는 매개변수를 해제하려면 각 속성 또는 매개변수를 쉼표로 구분하세요.

속성 또는 매개변수를 해제할 때는 속성 또는 매개변수 이름만 지정하세요(위 구문에서 값을 지정해야 한다고 표시되지 않는 한). 값을 지정하면 오류가 반환돼요.

액세스 제어 요구 사항

이 작업을 실행하는 데 사용되는 role에는 최소한 다음 privileges가 있어야 해요:

  권한
  객체
  참고




  OWNERSHIP or MODIFY
  Agent

에이전트 속성 또는 사양을 수정하는 데 필요해요.

%ac-ownership%

스키마의 객체에 대해 작업하려면 상위 데이터베이스에 대한 권한이 하나 이상, 상위 스키마에 대한 권한이 하나 이상 필요해요.

지정된 권한 집합으로 사용자 지정 역할을 만드는 방법은 를 참조하세요.

보안 가능한 객체(securable objects)에 대해 SQL 작업을 수행하기 위한 역할 및 권한 부여에 대한 일반적인 정보는 Overview of Access Control을 참조하세요.

사용 참고 사항

라이브 버전의 사양을 수정하면 새 사양이 기존 사양을 완전히 대체합니다. 새 사양에 포함되지 않은 필드는 제거됩니다.
사양에는 YAML 및 JSON 형식이 모두 지원됩니다.
잘못된 사양 필드는 오류를 발생시킵니다.
임시 에이전트는 LIVE 버전 변경에 대해서만 ALTER AGENT를 지원합니다. COMMIT과 같은 버전 관리 작업은 임시 에이전트에서 지원되지 않습니다. Working with temporary agents를 참조하세요.
구성된 도구에 대한 권한이 누락된 경우 실행을 중단할지 제어하려면 사양의 최상위 orchestration 키에 tool_not_accessible을 설정하세요. models.orchestration 또는 instructions.orchestration에 설정하지 마세요. 자세한 내용은 을(를) 참조하세요.
메타데이터 관련:

고객은 Snowflake 서비스 사용 시 메타데이터에 개인 데이터(User 객체에 대한 데이터 제외), 민감한 데이터, 수출 통제 데이터 또는 기타 규제 대상 데이터를 입력하지 않도록 해야 합니다. 자세한 내용은 Metadata fields in Snowflake를 참조하세요.

예시

에이전트의 주석(comment)을 업데이트합니다:

ALTER AGENT my_support_agent SET COMMENT = 'Customer support agent for product inquiries';

에이전트의 프로필을 업데이트합니다:

ALTER AGENT my_support_agent SET PROFILE = '{"display_name": "Support Bot", "avatar": "bot-icon.png"}';

주석과 프로필을 함께 업데이트합니다:

ALTER AGENT my_support_agent
  SET COMMENT = 'Production support agent',
      PROFILE = '{"display_name": "Customer Assistant", "avatar": "assistant.png"}';

YAML 형식을 사용하여 라이브 버전 사양을 업데이트합니다:

ALTER AGENT my_support_agent
  MODIFY LIVE VERSION SET SPECIFICATION =
  $$
  models:
    orchestration: claude-sonnet-4-6

  orchestration:
    tool_not_accessible: accept
    budget:
      seconds: 30
      tokens: 50000

  instructions:
    response: "Always be concise and accurate."
    orchestration: "Use available tools to look up order details before answering."
    sample_questions:
      - question: "What is the status of my order?"
  $$;

JSON 형식을 사용하여 라이브 버전 사양을 업데이트합니다:

ALTER AGENT my_support_agent
  MODIFY LIVE VERSION SET SPECIFICATION = '{"models":{"orchestration":"claude-sonnet-4-6"},"orchestration":{"tool_not_accessible":"accept","budget":{"seconds":45,"tokens":80000}}}';

에이전트에 태그를 설정합니다:

ALTER AGENT my_support_agent SET TAG cost_center = 'engineering';

에이전트의 태그를 해제합니다:

ALTER AGENT my_support_agent UNSET TAG cost_center;

에이전트를 보안(secure)으로 표시합니다:

ALTER AGENT my_agent SET SECURE = TRUE;

보안 지정을 제거합니다:

ALTER AGENT my_agent SET SECURE = FALSE;

에이전트 수정하기