ALTER AGENT¶

Modifies the properties or specification for an existing Cortex Agent.

See also:: CREATE AGENT, DESCRIBE AGENT, DROP AGENT, SHOW AGENTS

Syntax¶

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

ALTER AGENT [ IF EXISTS ] <name> MODIFY LIVE VERSION SET SPECIFICATION = <specification>

Copy

Required parameters¶

name

String that specifies the identifier (i.e. name) for the agent to alter.

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.

Optional parameters¶

SET ...

Sets one or more specified properties or parameters for the agent:

COMMENT = comment

Specifies the description of the agent.

PROFILE = string

Specifies the agent profile information, such as display name, avatar, and color. Format the string as follows:

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

Copy

The following table describes the key-value pairs in the string:

Key	Type	Description
`display_name`	String	Display name for the agent.
`avatar`	String	Avatar image file name or identifier.
`color`	String	Color theme for the agent (such as “blue”, “green”, “red”)

MODIFY LIVE VERSION SET SPECIFICATION specification

Specifies the VARCHAR value containing the replacement settings for an agent as either a YAML or JSON object:

Dollar-quoted literal: $$ … $$
Single-quoted string: ‘…’

The maximum length of the specification object is 100,000 bytes.

Important

The new specification completely replaces the existing one. Fields that are not included in the new specification are removed.

The YAML object should have the following structure:

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

The JSON object should have the following structure:

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

The following table describes the key-value pairs in this object:

Key	Type	Description
`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, system, and sample questions.
`tools`	array 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_resources`	map of ToolResource	An optional configuration for each tool referenced in the tools array. Keys must match the name of the respective tool.

Access control requirements¶

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

Privilege	Object	Notes
OWNERSHIP or MODIFY	Agent	Required to modify the agent properties or specification. 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).

Privilege

Object

Notes

OWNERSHIP or MODIFY

Agent

Required to modify the agent properties or specification.

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

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.

Usage notes¶

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.
Both YAML and JSON formats are supported for specifications.
Invalid specification fields result in an error.
Regarding metadata:

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.

Examples¶

Update the comment for an agent:

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

Copy

Update the profile for an agent:

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

Copy

Update both the comment and profile together:

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

Copy

Update the live version specification using YAML format:

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

Update the live version specification using JSON format:

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

Copy