CREATE に AGENT¶

指定された属性と仕様で新しい Cortex Agent オブジェクトを作成します。

こちらもご参照ください。: 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

エージェントの識別子（つまり、名前）を指定する文字列。エージェントが作成されるスキーマに対して一意である必要があります。

また、識別子はアルファベット文字で始まる必要があり、識別子文字列全体が二重引用符で囲まれていない限り、スペースや特殊文字を含めることはできません（例: "My object"）。二重引用符で囲まれた識別子も大文字と小文字が区別されます。

詳細については、識別子の要件をご参照ください。

オプションのパラメーター¶

COMMENT = comment

エージェントの説明。

PROFILE = profile_object

表示名、アバター、色などのエージェントプロファイル情報を含む OBJECT 値を指定します。次のように profile_object を文字列にシリアライズします。

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

次のテーブルは、このオブジェクトのキーと値のペアについて説明したものです。


キー	型	説明
`display_name`	String	エージェントの表示名。
`avatar`	String	アバター画像のファイル名または識別子。
`color`	String	エージェントのカラーテーマ（「青」、「緑」、「赤」など）

FROM SPECIFICATION $$ specification_object $$

エージェントの設定を含むVARCHARの値をYAMLオブジェクトとして指定します。仕様オブジェクトの最大長は100,000バイトです。

YAML オブジェクトは次のような構造になります。

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

次のテーブルは、このオブジェクトのキーと値のペアについて説明したものです。


キー	型	説明
`models`	ModelConfig	エージェントのオプションのモデル構成。オーケストレーションモデル（claude-4-sonnetなど）が含まれます。提示されない場合、モデルは自動的に選択されます。現在、 `オーケストレーション ` ステップでのみ利用可能です。
`orchestration`	OrchestrationConfig	予算の制約（秒、トークンなど）を含むオプションのオーケストレーション構成。
`instructions`	AgentInstructions	応答、オーケストレーション、システム、サンプルの質問など、エージェントの動作のオプション指示。
`tools`	Tool の配列	エージェントが利用可能なツールのオプションのリスト。各ツールには、型、名前、説明、入力スキーマを含む `tool_spec` が含まれています。ツールには `tool_resources` に対応する構成がある場合があります。
`tool_resources`	ToolResource のマップ	ツール配列で参照される各ツールのオプションの構成。キーはそれぞれのツール名と一致する必要があります。

アクセス制御の要件¶

この操作の実行に使用されるロールには、少なくとも次の権限が必要です。


権限	オブジェクト	メモ
CREATE に AGENT	スキーマ	Cortex Agentの作成に必要です。
USAGE	Cortex Searchサービス	Cortex AgentsリクエストでCortex Searchサービスを実行するために必要です。
USAGE	データベース、スキーマ、テーブル	Cortex Agentsのセマンティックモデルで参照されるオブジェクトにアクセスするために必要です。

使用上の注意¶

OR REPLACE 句と IF NOT EXISTS 句は互いに排他的です。この2つを同じステートメントで使うことはできません。
CREATE OR REPLACE <オブジェクト> ステートメントはアトミックです。つまり、オブジェクトが置き換えられると、単一のトランザクションで、古いオブジェクトが削除されて新しいオブジェクトが作成されます。

メタデータについて:

注意

Snowflakeサービスを使用する場合、お客様は、個人データ（ユーザーオブジェクト向け以外）、機密データ、輸出管理データ、またはその他の規制されたデータがメタデータとして入力されていないことを確認する必要があります。詳細については、 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"
    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>"
  $$;