ALTER AGENT

既存の:doc:`Cortex Agent</user-guide/snowflake-cortex/cortex-agents>`のプロパティまたは仕様を変更します。

こちらもご参照ください。

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

必須パラメーター

name

変更するエージェントの識別子（つまり、名前）を指定する文字列。

識別子にスペースまたは特殊文字が含まれる場合は、文字列全体を二重引用符で囲む必要があります。二重引用符で囲まれた識別子も大文字と小文字が区別されます。

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

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

SET ...

エージェントの1つ以上の指定されたプロパティまたはパラメーターを設定します。

COMMENT = comment

エージェントの説明を指定します。

PROFILE = string

表示名、アバター、色などのエージェントプロファイル情報を指定します。文字列を次のようにフォーマットします。

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

次のテーブルは、文字列のキーと値のペアについて説明したものです。

キー

型

説明

display_name

String

エージェントの表示名。

avatar

String

アバター画像のファイル名または識別子。

color

String

エージェントのカラーテーマ（「青」、「緑」、「赤」など）
MODIFY LIVE VERSION SET SPECIFICATION specification

エージェントの置換設定を含むVARCHAR値を、YAMLまたはJSONオブジェクトとして指定します。

仕様オブジェクトの最大長は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>'
    ...
  ...
Copy

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

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

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

キー

型

説明

models

ModelConfig

エージェントのオプションのモデル構成。オーケストレーションモデル（claude-4-sonnetなど）が含まれます。提示されない場合、モデルは自動的に選択されます。現在、 `オーケストレーション ` ステップでのみ利用可能です。

orchestration

OrchestrationConfig

予算の制約（秒、トークンなど）を含むオプションのオーケストレーション構成。

instructions

AgentInstructions

応答、オーケストレーション、システム、サンプルの質問など、エージェントの動作のオプション指示。

tools

Tool の配列

エージェントが利用可能なツールのオプションのリスト。各ツールには、型、名前、説明、入力スキーマを含む tool_spec が含まれています。ツールには tool_resources に対応する構成がある場合があります。

tool_resources

ToolResource のマップ

ツール配列で参照される各ツールのオプションの構成。キーはそれぞれのツール名と一致する必要があります。

アクセス制御の要件

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

権限

オブジェクト

メモ

OWNERSHIP または MODIFY

エージェント

エージェントのプロパティまたは仕様を変更するために必要。

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

スキーマ内のオブジェクトを操作するには、親データベースの少なくとも1つの権限と、親スキーマの少なくとも1つの権限が必要です。

指定された権限のセットを使用してカスタムロールを作成する手順については、 カスタムロールの作成 をご参照ください。

セキュリティ保護可能なオブジェクト に対して SQL アクションを実行するためのロールと権限付与に関する一般的な情報については、 アクセス制御の概要 をご参照ください。

使用上の注意

  • ライブバージョンの仕様を変更する場合、新しい仕様は既存の仕様を完全に置き換えます。新しい仕様に含まれていないフィールドは削除されます。

  • 仕様では、YAMLとJSONの両方の形式がサポートされています。

  • 無効な仕様フィールドはエラーになります。

  • メタデータについて:

    注意

    Snowflakeサービスを使用する場合、お客様は、個人データ（ユーザーオブジェクト向け以外）、機密データ、輸出管理データ、またはその他の規制されたデータがメタデータとして入力されていないことを確認する必要があります。詳細については、 Snowflakeのメタデータフィールド をご参照ください。

例

エージェントのコメントを更新します。

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

エージェントのプロファイルを更新します。

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

コメントとプロファイルの両方を同時に更新します。

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

YAML形式を使用してライブバージョン仕様を更新します。

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

JSON形式を使用してライブバージョン仕様を更新します。

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