ALTER AGENT¶

Modifica as propriedades ou a especificação de um Cortex Agent existente.

Consulte também:: CREATE AGENT, DESCRIBE AGENT, DROP AGENT, SHOW AGENTS

Sintaxe¶

ALTER AGENT <name> SET
  [ COMMENT = '<string>' ]
  [ PROFILE = '<string>' ]

ALTER AGENT <name> MODIFY LIVE VERSION SET SPECIFICATION = <specification>

Copy

Parâmetros obrigatórios¶

name

Cadeia de caracteres que especifica o identificador (ou seja, nome) do agente a ser alterado.

Se o identificador contiver espaços ou caracteres especiais, toda a cadeia de caracteres deverá ser delimitada por aspas duplas. Os identificadores delimitados por aspas duplas também diferenciam letras maiúsculas de minúsculas.

Para obter mais informações, consulte Requisitos para identificadores.

Parâmetros opcionais¶

SET ...

Define uma ou mais propriedades ou parâmetros especificados para o agente:

COMMENT = comment

Especifica a descrição do agente.

PROFILE = string

Especifica as informações de perfil do agente, como nome de exibição, avatar e cor. Formate a cadeia de caracteres da seguinte forma:

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

Copy

A tabela a seguir descreve os pares chave-valor na cadeia de caracteres:

Chave	Tipo	Descrição
`display_name`	Cadeia de caracteres	Nome de exibição do agente.
`avatar`	Cadeia de caracteres	Nome ou identificador do arquivo de imagem Avatar.
`color`	Cadeia de caracteres	Tema de cores do agente (como “azul”, “verde”, “vermelho”)

MODIFY LIVE VERSION SET SPECIFICATION specification

Especifica o valor VARCHAR contendo as configurações de substituição para um agente como um objeto YAML ou JSON:

Literal entre cifrões: $$ … $$
Cadeia de caracteres entre aspas simples: “…”

O comprimento máximo do objeto de especificação é de 100.000 bytes.

Importante

A nova especificação substitui completamente a existente. Os campos que não estão incluídos na nova especificação são removidos.

O YAML O objeto deve ter a seguinte estrutura:

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>'
    ...
  ...

Copy

O JSON O objeto deve ter a seguinte estrutura:

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

Copy

A tabela a seguir descreve os pares chave-valor nesse objeto:

Chave	Tipo	Descrição
`models`	ModelConfig	Uma configuração de modelo opcional para o agente. Inclui o modelo de orquestração (por exemplo, claude-4-sonnet). Se não for fornecido, um modelo será selecionado automaticamente. Atualmente disponível apenas para a etapa `orchestration`.
`orchestration`	OrchestrationConfig	Uma configuração opcional da orquestração, incluindo restrições orçamentárias (por exemplo, segundos, tokens).
`instructions`	AgentInstructions	Instruções opcionais para o comportamento do agente, incluindo resposta, orquestração, sistema e perguntas de amostra.
`tools`	Matriz de Tool	Uma lista de ferramentas opcionais disponíveis para o agente usar. Cada ferramenta inclui uma `tool_spec` com tipo, nome, descrição e esquema de entrada. As ferramentas podem ter uma configuração correspondente em `tool_resources`.
`tool_resources`	mapa de ToolResource	Uma configuração opcional de cada ferramenta referenciada na matriz de ferramentas. As chaves devem corresponder ao nome da respectiva ferramenta.

Requisitos de controle de acesso¶

A função usada para executar essa operação deve ter, no mínimo, os seguintes privilégios:

Privilégio	Objeto	Notas
OWNERSHIP ou MODIFY	Agente	Necessário para modificar as propriedades ou a especificação do agente. OWNERSHIP is a special privilege on an object that is automatically granted to the role that created the object, but can also be transferred using the GRANT OWNERSHIP command to a different role by the owning role (or any role with the MANAGE GRANTS privilege).

Privilégio

Objeto

Notas

OWNERSHIP ou MODIFY

Agente

Necessário para modificar as propriedades ou a especificação do agente.

OWNERSHIP is a special privilege on an object that is automatically granted to the role that created the object, but can also be transferred using the GRANT OWNERSHIP command to a different role by the owning role (or any role with the MANAGE GRANTS privilege).

Operar em um objeto em um esquema requer pelo menos um privilégio no banco de dados pai e pelo menos um privilégio no esquema pai.

Para instruções sobre como criar uma função personalizada com um conjunto específico de privilégios, consulte Criação de funções personalizadas.

Para informações gerais sobre concessões de funções e privilégios para executar ações de SQL em objetos protegíveis, consulte Visão geral do controle de acesso.

Notas de uso¶

Ao modificar a especificação de uma versão ativa, a nova especificação substitui completamente a existente. Os campos que não estão incluídos na nova especificação são removidos.
Ambos os formatos YAML e JSON são compatíveis com as especificações.
Os campos de especificação inválidos resultam em um erro.
Em relação aos metadados:

Atenção

Os clientes devem garantir que nenhum dado pessoal (exceto para um objeto do usuário), dados sensíveis, dados controlados por exportação ou outros dados regulamentados sejam inseridos como metadados ao usar o serviço Snowflake. Para obter mais informações, consulte Campos de metadados no Snowflake.

Exemplos¶

Atualizar o comentário de um agente:

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

Copy

Atualizar o perfil de um agente:

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

Copy

Atualizar o comentário e o perfil juntos:

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

Copy

Atualizar a especificação da versão ativa usando o formato YAML:

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

  orchestration:
    budget:
      seconds: 30
      tokens: 50000

  instructions:
    system: "You are a helpful customer support assistant."
    response: "Always be concise and accurate."
    sample_questions:
      - question: "What is the status of my order?"
        answer: "I can help you check your order status. Please provide your order number."
  $$;

Copy

Atualizar a especificação da versão ativa usando o formato JSON:

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

Copy