AGENT_RUN (SNOWFLAKE.CORTEX)¶

Syntaxe¶

SNOWFLAKE.CORTEX.AGENT_RUN( <request_body> )

Arguments¶

request_body

Corps de la requête JSON à envoyer à l’agent. Cette valeur doit être une chaîne (par exemple, un littéral $$...$$).

Les champs suivants sont pris en charge dans le corps de la requête :

Champ	Type	Description
thread_id	entier	ID de thread pour la conversation. Si thread_id est utilisé, parent_message_id doit également être transmis.
parent_message_id	entier	ID du message parent dans le thread. S’il s’agit du premier message, parent_message_id doit correspondre à 0.
messages	tableau d”Message	Si thread_id et parent_message_id sont transmis dans la requête, les messages incluent le message actuel de l’utilisateur dans la conversation. Sinon, les messages comprennent l’historique de la conversation et le message actuel. Les messages contiennent à la fois les requêtes des utilisateurs et les réponses des assistants dans l’ordre chronologique.
stream	booléen	Renvoyer une réponse streaming (texte/flux d’événements) ou une réponse JSON non-streaming (application/json). Si « true », la réponse sera envoyée (stream) en tant qu’événements envoyés par le serveur. Si « false », la réponse sera renvoyée en tant que JSON.
tool_choice	ToolChoice	Configure la manière dont l’agent doit sélectionner et utiliser les outils pendant l’interaction. Contrôle si l’utilisation des outils est automatique, obligatoire, ou si des outils spécifiques doivent être utilisés.
models	ModelConfig	Configuration du modèle pour l’agent. Inclut le modèle d’orchestration (par exemple, claude-4-sonnet). S’il n’est pas fourni, un modèle est automatiquement sélectionné. Actuellement disponible uniquement pour l’étape d’orchestration.
instructions	AgentInstructions	Instructions relatives au comportement de l’agent, y compris la réponse, l’orchestration, le système et les exemples de questions.
orchestration	OrchestrationConfig	Configuration de l’orchestration, y compris les contraintes budgétaires (par exemple, secondes, jetons).
tools	tableau d”Tool	Liste des outils disponibles pour l’agent à utiliser. Chaque outil inclut une tool_spec avec un type, un nom, une description et un schéma d’entrée. Les outils peuvent avoir une configuration correspondante dans tool_resources.
tool_resources	carte de ToolResource	Configuration pour chaque outil référencé dans le tableau des outils. Les clés doivent correspondre au nom de l’outil correspondant.

Exemple

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

Renvoie¶

Renvoie une chaîne JSON contenant la réponse de l’agent.

Exigences en matière de contrôle d’accès¶

Pour exécuter un agent, vous devez utiliser un rôle permettant d’accéder aux Agents Cortex. Pour plus de détails, voir Exigences en matière de contrôle d’accès.

Notes sur l’utilisation¶

• La fonction renvoie une chaîne JSON. Transmettez cette chaîne à TRY_PARSE_JSON pour convertir la réponse en une valeur VARIANT.

• Contrairement à DATA_AGENT_RUN (SNOWFLAKE.CORTEX), cette fonction ne nécessite pas que vous créiez d’abord un objet agent. Au lieu de cela, vous fournissez la configuration directement dans le corps de la requête.

Exemples¶

Exécuter un agent et analyser la réponse 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;

Exemple de valeur de retour :

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