ALTER AGENT

Modifies the properties or specification for an existing Cortex Agent.

See also:

CREATE AGENT, DESCRIBE AGENT, DROP AGENT, SHOW AGENTS

语法

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

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

必填参数

name

用于指定要修改的代理标识符（即名称）的字符串。

If the identifier contains spaces or special characters, the entire string must be enclosed in double quotes. Identifiers enclosed in double quotes are also case-sensitive.

For more information, see Identifier requirements.

可选参数

SET ...

为代理设置一个或多个指定的属性或参数：

COMMENT = comment

指定代理的描述。

PROFILE = string

指定代理的配置文件信息，例如显示名称、头像和颜色。如下所示，设置字符串格式：

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

下表描述了该字符串中的键值对：

键类型描述
display_name字符串代理的显示名称。
avatar字符串头像图像文件名或标识符。
color字符串代理的颜色主题（例如“蓝色”、“绿色”、“红色”）
MODIFY LIVE VERSION SET SPECIFICATION specification

指定一个 VARCHAR 包含代理替换设置的值，该值以 YAML 或 JSON 对象的形式存在。

规范对象的最大长度为 100,000 字节。

Important

新规范会完全取代现有规范。未包含在新规范中的字段将被移除。

YAML 对象应具有以下结构：

models:
  orchestration: <model_name>

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

instructions:
  response: '<response_instructions>'
  orchestration: '<orchestration_instructions>'
  sample_questions:
      - question: '<sample_question>'
      ...

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

JSON 对象应具有以下结构：

{
  "models": {
    "orchestration": "<model_name>"
  },
  "orchestration": {
    "budget": {
      "seconds": <number_of_seconds>,
      "tokens": <number_of_tokens>
    }
  },
  "instructions": {
    "response": "<response_instructions>",
    "orchestration": "<orchestration_instructions>",
    "sample_questions": [
      {
        "question": "<sample_question>"
      }
    ]
  },
  "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>"
    }
  }
}

下表描述了该对象中的键值对：

KeyTypeDescription
models`ModelConfig`An optional model configuration for the agent. Includes the orchestration model (e.g., claude-4-sonnet). If not provided, a model is automatically selected. Currently only available for the orchestration step.
orchestration`OrchestrationConfig`An optional orchestration configuration, including budget constraints (e.g., seconds, tokens).
instructions`AgentInstructions`Optional instructions for the agent’s behavior, including response, orchestration, and sample questions.
toolsarray of `Tool`An optional list of tools available for the agent to use. Each tool includes a tool_spec with type, name, description, and input schema. Tools may have a corresponding configuration in tool_resources.
tool_resourcesmap of `ToolResource`An optional configuration for each tool referenced in the tools array. Keys must match the name of the respective tool.

访问控制要求

A role used to execute this operation must have the following privileges at a minimum:

PrivilegeObjectNotes
OWNERSHIP or MODIFYAgent

修改代理属性或规范所必需的权限。

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](/sql-reference/sql/grant-ownership) command to a different role by the owning role (or any role with the MANAGE GRANTS privilege).

Operating on an object in a schema requires at least one privilege on the parent database and at least one privilege on the parent schema.

For instructions on creating a custom role with a specified set of privileges, see Creating custom roles.

For general information about roles and privilege grants for performing SQL actions on securable objects, see Overview of Access Control.

使用说明

  • When modifying a live version’s specification, the new specification completely replaces the existing one. Fields that are not included in the new specification are removed.

  • 规范支持 YAML 和 JSON 两种格式。

  • 无效的规范字段会导致错误。

  • 关于元数据：

    Attention

    Customers should ensure that no personal data (other than for a User object), sensitive data, export-controlled data, or other regulated data is entered as metadata when using the Snowflake service. For more information, see Metadata fields in Snowflake.

示例

更新代理的注释：

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-4-sonnet

  orchestration:
    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-4-sonnet"},"orchestration":{"budget":{"seconds":45,"tokens":80000}}}';