CREATE AGENT¶

Creates a new Cortex Agent object with the specified attributes and specification.

See also:: ALTER AGENT, DESCRIBE AGENT, DROP AGENT, SHOW AGENTS, DATA_AGENT_RUN (SNOWFLAKE.CORTEX)

语法

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

必填参数

name: String that specifies the identifier (i.e. name) for the agent; must be unique for the schema in which the agent 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.

可选参数

COMMENT = comment

代理的描述。

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

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

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

FROM SPECIFICATION $$ specification_object $$

Specifies the VARCHAR value containing the settings for an agent as a YAML object. The maximum length of the specification object is 100,000 bytes.

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

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

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

访问控制要求

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

权限	对象	备注
CREATE AGENT	架构	这是创建 Cortex 代理所必需的。
USAGE	Cortex Search Service	需要在 Cortex Agents 请求中运行 Cortex Search Service。
USAGE	数据库、架构、表	Required to access the objects referenced in the Cortex Agents semantic model.

使用说明

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.

关于元数据：

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.

示例

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"
    sample_questions:
      - question: "What was our revenue last quarter?"

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