CREATE AGENT¶

Syntax¶

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

Required parameters¶

name

String that specifies the identifier (i.e. name) for the book; must be unique for the schema in which the book is created.

In addition, the identifier must start with an alphabetic character and cannot contain spaces or special characters unless the entire identifier string is enclosed in double quotes (for example, "My object"). Identifiers enclosed in double quotes are also case-sensitive.

For more information, see Identifier requirements.

Optional parameters¶

COMMENT = comment

Description of the agent.

PROFILE = profile_object

Specifies the OBJECT value containing agent profile information, such as display name, avatar, and color. Serialize the profile_object into a string as follows:

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

Copy

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

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

FROM SPECIFICATION $$ specification_object $$

Specifies the VARCHAR value containing the settings for an agent as a YAML object.

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 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:

Usage notes¶

• The OR REPLACE and IF NOT EXISTS clauses are mutually exclusive. They can’t both be used in the same statement.

• CREATE OR REPLACE <object> statements are atomic. That is, when an object is replaced, the old object is deleted and the new object is created in a single transaction.

• 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¶

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>"
  $$;