AGENT_RUN (SNOWFLAKE.CORTEX)¶

構文¶

SNOWFLAKE.CORTEX.AGENT_RUN( <request_body> )

引数¶

request_body

エージェントに送信するJSONリクエスト本文。この値は文字列（たとえば、:code:`$$...$$`リテラル）である必要があります。

リクエスト本文では、以下のフィールドがサポートされています。

フィールド	型	説明
thread_id	integer	会話のためのスレッド ID。thread_idを使用する場合、parent_message_idも渡す必要があります。
parent_message_id	integer	そのスレッドの親メッセージの ID。これが最初のメッセージである場合、parent_message_idは0である必要があります。
messages	Message の配列	リクエストでthread_idとparent_message_idを渡す場合、messagesには会話の現在のユーザーメッセージが含まれます。そうでない場合は、messagesには会話履歴と現在のメッセージが含まれます。messagesには、ユーザークエリとアシスタントの応答の両方が時系列で含まれます。
stream	boolean	ストリーミング応答（テキスト/イベントストリーム）を返すか、非ストリーミング JSON 応答（アプリケーション/JSON）を返すかを指定します。trueの場合、応答はサーバー送信イベントとしてストリーミングされます。falseの場合、応答は JSON として返されます。
tool_choice	ToolChoice	対話中にエージェントがどのようにツールを選択し、使用するかを構成します。ツールの使用が自動か、必須か、または特定のツールを使用すべきかを制御します。
models	ModelConfig	エージェントのモデル構成。オーケストレーションモデル（claude-4-sonnetなど）が含まれます。提示されない場合、モデルは自動的に選択されます。現在、オーケストレーション ステップでのみ利用可能です。
instructions	AgentInstructions	応答、オーケストレーション、システム、サンプルの質問など、エージェントの動作の指示。
orchestration	OrchestrationConfig	予算の制約（秒、トークンなど）を含むオーケストレーション構成。
tools	Tool の配列	エージェントが利用可能なツールのリスト。各ツールには、型、名前、説明、入力スキーマを含むtool_specが含まれています。toolsにはtool_resourcesに対応する構成がある場合があります。
tool_resources	ToolResource のマップ	ツール配列で参照される各ツールの構成。キーはそれぞれのツール名と一致する必要があります。

例

{
  "thread_id": 0,
  "parent_message_id": 0,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is the total revenue for 2023?"
        }
      ]
    }
  ],
  "stream": false,
  "tool_choice": {
    "type": "auto",
    "name": [
      "analyst_tool",
      "search_tool"
    ]
  },
  "models": {
    "orchestration": "claude-4-sonnet"
  },
  "instructions": {
    "response": "You will respond in a friendly but concise manner",
    "orchestration": "For any query related to revenue we should use Analyst; For all policy questions we should use Search",
    "system": "You are a friendly agent ..."
  },
  "orchestration": {
    "budget": {
      "seconds": 30,
      "tokens": 16000
    }
  },
  "tools": [
    {
      "tool_spec": {
        "type": "generic",
        "name": "get_revenue",
        "description": "Fetch the delivery revenue for a location.",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            }
          }
        },
        "required": [
          "location"
        ]
      }
    }
  ],
  "tool_resources": {
    "get_revenue": {
      "type": "function",
      "execution_environment": {
        "type": "warehouse",
        "warehouse": "MY_WH"
      },
      "identifier": "DB.SCHEMA.UDF"
    }
  }
}

Copy

戻り値¶

エージェントの応答を含むJSON文字列を返します。

アクセス制御の要件¶

エージェントを実行するには、Cortex Agentにアクセスできるロールを使用する必要があります。詳細については、 アクセス制御の要件 をご参照ください。

使用上の注意¶

• 関数はJSON文字列を返します。この文字列を:doc:`try_parse_json`に渡し、応答をVARIANT値に変換します。

• :doc:`data_agent_run-snowflake-cortex`とは異なり、この関数では最初にエージェントオブジェクトを作成する必要はありません。代わりに、リクエスト本文で直接設定を提供します。

例¶

エージェントを実行し、応答JSONを解析します。

SELECT
  TRY_PARSE_JSON(
    SNOWFLAKE.CORTEX.AGENT_RUN(
      $${
        "messages": [
          {
            "role": "user",
            "content": [
              {
                "type": "text",
                "text": "What is the total revenue for 2025?"
              }
            ]
          }
        ],
        "models": {
          "orchestration": "claude-4-sonnet"
        }
      }$$
    )
  ) AS resp;

戻り値のサンプル:

{
  "content": [
    {
      "text": "The total revenue for 2025 was $100,000.",
      "type": "text"
    }
  ],
  "metadata": {
    "usage": {
      "tokens_consumed": [
        {
          "context_window": 200000,
          "input_tokens": {
            "cache_read": 0,
            "cache_write": 0,
            "total": 67,
            "uncached": 67
          },
          "model_name": "claude-4-sonnet",
          "output_tokens": {
            "total": 38
          }
        }
      ]
    }
  },
  "role": "assistant"
}