Outil d’exécution de code pour les Agents Cortex¶

L’exécution de code pour les Agents Cortex est un outil intégré qui permet à un agent d’exécuter du code pendant une conversation. Lorsque l’accès à un outil d’exécution de code est activé, vos agents peuvent exécuter des scripts pour traiter des données, effectuer des calculs et produire des visualisations. Par défaut, l’outil d’exécution de code s’exécute dans un environnement sandbox et isolé, qui ne peut accéder qu’aux données de la session d’agent en cours.

Vous activez l’outil d’exécution de code en le configurant dans une spécification d’agent. L’agent décide alors, au cours de l’orchestration, quand générer et exécuter du code en fonction de la requête de l’utilisateur. L’outil d’exécution de code est également utilisé pour exécuter des scripts Python dans le cadre d’une stratégie d’agent.

Comment fonctionne l’exécution de code ?¶

L’agent utilise l’exécution de code avec d’autres outils et capacités configurés. Pendant l’orchestration, l’agent évalue la requête de l’utilisateur et détermine si l’exécution de code est la meilleure approche. Si tel est le cas, l’agent appelle l’outil d’exécution de code.

L’agent génère ensuite du code et l’exécute dans un environnement sandbox sécurisé. Par défaut, l’environnement de l’outil d’exécution de code est isolé et ne peut accéder qu’aux données transmises à la session. Des autorisations supplémentaires de lecture ou d’écriture peuvent être accordées dans la spécification de l’agent.

Portée de l’accès par défaut¶

Le sandbox de l’outil d’exécution de code reste actif pendant une seule session. Les données fournies dans le contexte de la conversation correspondent à celles dont dispose l’outil d’exécution de code pour opérer. Le sandbox conserve les importations, les variables et les résultats intermédiaires entre plusieurs exécutions au cours de la session.

Activation de l’outil d’exécution de code¶

Pour utiliser l’outil d’exécution de code avec un Agent Cortex, celui-ci doit disposer à la fois des autorisations de contrôle d’accès requises et de la section de la spécification de l’agent décrivant l’outil d’exécution de code.

Autorisations requises sur les Agents Cortex¶

Les autorisations suivantes sur un Agent Cortex concernent votre capacité à configurer et à interroger l’agent :


Privilège	Obligatoire pour
USAGE	Permet d’invoquer l’agent, y compris l’utilisation de l’outil d’exécution de code
MODIFY	Modification d’une spécification d’agent pour activer ou configurer l’outil d’exécution de code
OWNERSHIP	Accès total sur la configuration et l’utilisation des agents

Spécification d’agent¶

Vous activez l’outil d’exécution de code en ajoutant les ressources et la configuration correspondantes à une spécification d’agent.

La définition de l’outil à ajouter dans la section tools de votre spécification d’agent est la suivante :

tools:
  - tool_spec:
    type: code_execution
    name: code_execution

Activez l’outil en ajoutant une section code_execution aux tool_resources dans votre spécification d’agent :

tool_resources:
  code_execution:

Pour obtenir des informations complètes sur le format d’une spécification d’agent et des instructions sur la manière de modifier une spécification d’agent existante, consultez Configurer des agents et interagir avec.

Bibliothèques disponibles par défaut¶

L’environnement d’exécution par défaut de l’outil d’exécution de code utilise Python 3.12, avec la bibliothèque standard Python disponible. Les bibliothèques supplémentaires suivantes sont également disponibles par défaut :


Bibliothèque	Version
`numpy`	TKTK
`pandas`	TKTK

Ajouter des bibliothèques via le dépôt d’artefacts¶

Vous pouvez utiliser le dépôt d’artefacts par défaut de Snowflake pour récupérer des paquets depuis PyPI dans l’environnement de l’outil d’exécution de code. Ajoutez la clé artifact_repositories aux ressources code_execution dans votre spécification d’agent, sous la forme d’une liste contenant une entrée pour SNOWFLAKE.SNOWPARK.PYPI_SHARED_REPOSITORY :

tool_resources:
  code_execution:
    artifact_repositories:
      - SNOWFLAKE.SNOWPARK.PYPI_SHARED_REPOSITORY

Pour accéder au dépôt PyPI, vous devez aussi attribuer le rôle SNOWFLAKE.PYPI_REPOSITORY_USER au propriétaire de l’Agent Cortex.

Important

Cela donne à l’outil d’exécution de code l’accès pour récupérer n’importe quel paquet publié sur PyPI. Faites preuve de prudence lorsque vous accordez ce niveau d’accès.

Activation de l’accès externe¶

Vous pouvez activer l’exécution de code pour accéder à des points de terminaison externes sur Internet en créant une règle réseau et une intégration d’accès externe, puis en fournissant des informations sur les intégrations auxquelles l’outil d’exécution de code a accès dans la spécification de l’agent.

L’exemple suivant illustre la création d’une nouvelle règle réseau (github_access_rule) et d’une nouvelle intégration d’accès externe (github_integration) permettant d’accéder à github.com et à certains sous-domaines sur HTTP et HTTPS :

CREATE OR REPLACE NETWORK RULE github_access_rule
  MODE = EGRESS
  TYPE = HOST_PORT
  VALUE_LIST = ('github.com', 'api.github.com', 'raw.githubusercontent.com');

CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION github_integration
  ALLOWED_NETWORK_RULES = (github_access_rule)
  ENABLED = true;

Pour activer les intégrations d’accès externes, ajoutez la clé external_access_integrations aux ressources code_execution de votre spécification d’agent, contenant une liste d’intégrations d’accès externes auxquelles l’outil d’exécution de code peut accéder. L’extrait de spécification d’agent suivant montre comment donner à l’outil d’exécution de code l’accès à l’intégration d’accès externe github_integration :

tool_resources:
  code_execution:
    external_access_integrations:
      - github_integration

Pour plus de détails sur la configuration des règles réseau et des intégrations d’accès externes, consultez Création et utilisation d’une intégration d’accès externe.

Limitations connues¶

L’outil d’exécution de code pour les Agents Cortex est soumis aux limitations connues suivantes :

Portée d’une seule session : Par défaut, l’outil d’exécution de code ne peut accéder qu’aux données de la session en cours. L’état n’est pas partagé entre les sessions ou entre les appels distincts. Pour conserver les informations générées par l’outil d’exécution de code, vous aurez besoin de votre propre magasin permanent sur Snowflake, auquel l’outil d’exécution de code aura accès en lecture et en écriture.
Héritage d’accès : L’outil d’exécution de code fonctionne avec les privilèges de rôle du propriétaire de l’Agent Cortex. Assurez-vous que le rôle de propriétaire de tout agent dont l’exécution de code est activée est défini de manière appropriée.