Laissez le modèle écrire le flux de travail.
CodeAct est un moyen pour un agent d’IA d'agir en écrivant un programme court. Ce programme appelle uniquement les outils que vous approuvez, combine leurs résultats avec du code ordinaire et renvoie une réponse via le runtime ADK-Rust.
cart = call_tool("fetch_cart", args) subtotal = sum(item["price"] * item["qty"] for item in cart["items"]) rate = call_tool("tax_rate", region) total = subtotal * (1 + rate)
Commencez ici
Qu'est-ce qu'un agent CodeAct ?
Un agent CodeAct est un agent d’IA qui écrit du code executable pour décider comment plusieurs outils approuvés doivent fonctionner ensemble. Votre application exécute ce code dans un interpréteur contrôlé et reste responsable de chaque action externe.
Appel d'outil traditionnel
Le modèle choisit une action à la fois.
- 01Demandez au modèle quel outil appeler.
- 02Exécutez cet outil et renvoyez son résultat au modèle.
- 03Demandez au modèle quoi faire ensuite, puis répétez.
CodeAct
Le modèle écrit la procédure complète.
- 01Demandez au modèle un programme court en utilisant les outils disponibles.
- 02Exécutez le programme et faites une pause uniquement lorsqu'il atteint un outil réel.
- 03Reprenez avec le résultat de l'outil jusqu'à ce que le programme renvoie sa réponse.
Une simple analogie
Appeler un outil traditionnel revient à demander à un collègue d'appuyer sur un bouton de calculatrice, de signaler l'écran et d'attendre l'instruction suivante. CodeAct, c'est comme donner à ce collègue la permission d'écrire une petite formule sur une feuille de calcul : les entrées autorisées restent les mêmes, mais le calcul peut contenir des variables, des conditions, des boucles et plusieurs étapes.
Huit mots que vous verrez sur cette page
Modèle
Le LLM qui écrit le script.
Agent
Le composant qui transforme un objectif en actions et en résultats.
Outil
Une fonction Rust approuvée qui atteint les données ou les systèmes de l'entreprise.
Scénario
Le programme court écrit pour le tour d'agent actuel.
Durée d'exécution
L'interpréteur qui execute et met le script en pause.
Observations
Un résultat ou une erreur renvoyé au modèle pour un autre tour.
Point de contrôle
Un programme en pause enregistré qui peut continuer plus tard.
Résultat final
La réponse tapée est renvoyée à votre candidature.
D'où est venue l'idée
CodeAct a commencé comme une question de recherche sur le langage d'action d'un agent.
La plupart des premiers agents utilisant des outils représentaient une action sous forme de langage naturel ou d'objet JSON contenant un nom d'outil et des arguments. Les chercheurs Xingyao Wang, Yangyi Chen, Lifan Yuan, Yizhe Zhang, Yunzhu Li, Hao Peng et Heng Ji ont demandé si executable Python serait un format d'action plus expressif.
Leur papier, « Les actions de code exécutable génèrent de meilleurs agents LLM », est sorti en février 2024 et est apparu au ICML 2024. Il evaluait 17 modèles de langage sur API-Bank et le benchmark M³ToolEval du journal. Les auteurs ont rapporté que les actions de code atteignaient des taux de réussite jusqu'à 20 % supérieurs à ceux des formats de texte et d'action JSON testés.
Le document a également présenté CodeActInstruct, un ensemble de données de 7 000 interactions multitours et des modèles CodeActAgent affinés au code execute, observez les résultats, révisez les programmes ayant échoué et poursuivez la conversation. Il s'agit de résultats de recherche sur les tâches du journal ; cela ne signifie pas que les actions de code sont automatiquement meilleures pour chaque produit.
Pourquoi devrais-je utiliser CodeAct ?
CodeAct
CodeAct est convaincant lorsque l'agent doit combiner outils et calcul. Il donne au modèle un langage familier pour exprimer la logique tandis que votre application conserve les limites de l'outil et du runtime.
Composer plusieurs outils
Un script peut appeler plusieurs outils approuvés et transmettre un résultat directement à l'étape suivante.
Utiliser un flux de contrôle réel
Les boucles, les conditions, les variables, le tri, le filtrage et l'arithmétique sont exprimés directement dans le code.
Réduire les allers-retours des modèles
Un travail qui nécessiterait plusieurs tours de sélection d'outils peut parfois être exprimé dans un seul script généré.
Conserver les données intermédiaires locales
Le moteur d'exécution peut filtrer ou regrouper les résultats des outils volumineux avant de décider ce qui appartient à la transcription du modèle.
Corriger les erreurs executable
Une erreur de syntaxe, une exception ou une assertion ayant échoué peuvent devenir une observation que le modèle utilise pour réviser le script suivant.
Inspecter l'action
Les développeurs peuvent lire le programme généré, les appels d'outils, les sorties et les points de contrôle sous forme de piste execution.
Compromis
Quand dois-je l’éviter ?
Un geste simple
Un appel d'outil LlmAgent normal est plus facile lorsque la demande est clairement mappée à une opération commerciale.
Génération de code faible
Un modèle qui a du mal à écrire du code valide peut nécessiter plus de tours de correction que d'appels d'outils structurés.
Pas d'exécution sécurisée
Le code généré nécessite un interpréteur avec des limites d'accès et de ressources explicites. Ne le transmettez jamais à un eval ou un exec sans restriction.
Développement logiciel complet
Utilisez CodingAgent lorsque l'objectif est de modifier des référentiels, d'exécuter des commandes shell ou d'exploiter un espace de travail de développement.
Implémentations dans l'écosystème
Le concept CodeAct apparaît désormais dans plusieurs systèmes d'agents.
Ils partagent l'idée du code en tant que format d'action, mais diffèrent par la prise en charge du langage, l'exposition des outils, le sandboxing, l'état et la charge de travail prévue.
CodeAct
Recherche originale
Actions Python, CodeActInstruct, modèles de recherche affinés et moteur execution conteneurisé.
En savoir plus ↗OpenHands
Agents logiciels
Son CodeActAgent peut converser, son execute Python et exécuter des commandes shell pour les travaux de développement logiciel.
En savoir plus ↗smolagents
Hugging Face
CodeAgent utilise des actions Python avec des boucles et des conditions et prend en charge plusieurs sandbox executors.
En savoir plus ↗Pydantic AI
Mode Code
Encapsule les outils d'un agent dans une interface de code et utilise Monty comme environnement d'exécution Python contrôlé.
En savoir plus ↗ADK-Rust
Runtime natif Rust
Ajoute la boucle CodeAct aux agents, outils, sessions, événements, approbations, rappels et transferts saisis.
En savoir plus ↗Comment ADK-Rust implémente CodeAct
CodeAct fonctionne dans le runtime ADK-Rust.
CodeActAgent est un type d'agent à côté LlmAgent. Vous lui donnez un modèle, un CodeRuntimeet les outils Rust. Vous l'exécutez ensuite via les mêmes systèmes Runner, session, événement, rappel, autorisation et sortie utilisés par d'autres agents ADK-Rust.
1. Modèle
Choisissez n’importe quel fournisseur de modèles ADK-Rust capable de produire un code fiable.
2. CodeRuntime
Utilisez le runtime Python basé sur Monty ou implémentez le trait CodeRuntime indépendant du langage.
3. Outils Rust
Enregistrez les outils saisis. Le script ne peut accéder qu'aux outils fournis pour cet appel.
4. Runner
Exécutez l’agent avec un utilisateur et une session, puis consommez les événements ADK-Rust typés normaux.
5. Séance
Conservez les points de contrôle lorsque l’approbation ou un outil de longue durée interrompt le programme.
6. Contrôles
Appliquez la confirmation, les tentatives, les délais d'attente, les rappels, les garde-fous et les sorties validées.
Démarrage de travail le plus rapide
Exécutez d’abord l’exemple archivé.
Il utilise un modèle déterministe, un véritable interpréteur Monty Python, deux outils Rust, une session en mémoire et le ADK-Rust Runner. Aucune clé API de modèle n'est requise.
L'adaptateur Monty est actuellement une dépendance expérimentale Git et nécessite Rust 1.95+, l'exemple comporte donc son propre fichier de chaîne d'outils.
git clone https://github.com/zavora-ai/adk-rust.git
cd adk-rust/examples/codeact_monty_agent
# This example selects Rust 1.95 automatically.
cargo run=== ADK-Rust CodeAct × Monty (Python) example ===
[cart_assistant]
{
"lines": 3,
"region": "CA",
"subtotal": 132.0,
"tax_rate": 0.0725,
"total": 141.57,
"user": "u-42"
}
Done.Architecture
Le script s'exécute dans le système d'agent.
Le modèle propose une logique executable. Le CodeRuntime contrôle la façon dont cette logique avance. ADK-Rust est propriétaire de chaque action externe, point de contrôle durable et événement détecté par l'application.
Modèle
Écrit un script à l'aide du briefing d'exécution et des outils disponibles pour cet appel.
CodeRuntime
Exécute le script étape par étape et expose les appels, l'achèvement, stdout et les erreurs de script.
Hôte ADK-Rust
Exécute les outils avec autorisation et contexte, conserve l'état et diffuse le résultat final.
Procédure pas à pas de execution basée sur la source
Étude de cas : tarifer un panier en un seul tour CodeAct.
Cela fait suite à l'exemple déterministe CodeAct × Monty dans le référentiel ADK-Rust. Sélectionnez chaque limite pour voir quelle partie du système fonctionne et ce qui devient visible pour la partie suivante.
Runner
La demande entre ADK-Rust
Le Runner attache l'utilisateur, la session, le contexte d'appel, les rappels et les outils disponibles avant le démarrage de l'agent CodeAct.
Signal visible
Quel est le total du chariot u-42, incluant la taxe CA ?
Choisissez la bonne forme d'agent
CodeAct a un travail spécifique.
Utilisez-le lorsqu'un modèle peut exprimer plus clairement le travail sous forme de programme. ADK-Rust fournit également des formes d'agent pour l'utilisation d'outils conversationnels et d'environnements de développement logiciel complets.
LlmAgent
Choisissez et appelez les outils de manière conversationnelle.
Idéal pour : Questions, dialogues, actions commerciales isolées et transferts naturels.
modèle → outil → modèle
CodeActAgent
Composez des outils et une logique dans un seul plan executable.
Idéal pour : Analyse, transformation de données, travail par lots, calculs et flux conditionnels.
modèle → script ↔ outils → résultat
CodingAgent
Travaillez au sein d’un harnais de développement logiciel.
Idéal pour : Édition du référentiel, commandes shell, builds, tests, correctifs et protocoles d'agent de codage.
agent ↔ espace de travail + shell
Exécution Monty
Donnez au code généré une limite de fonctionnement claire.
L'adaptateur Python actuel de ADK-Rust exécute Monty en cours. L'hôte décide de ce que le script peut lire, écrire, connaître et consommer avant le début de execution.
Monty est encore expérimental. Il s'agit actuellement d'une dépendance Git épinglée et nécessite Rust 1.95+. L'adaptateur vit dans sa propre caisse jusqu'à ce que Monty soit disponible sur crates.io.
Bac à sable par défaut
Aucun accès au système de fichiers et un environnement vide. Les opérations de réseau et de sous-processus n'ont pas de surface Monty.
Montages explicites
Mappez les répertoires hôtes sélectionnés sur des chemins virtuels et choisissez un accès en lecture seule ou en lecture-écriture pour chacun.
Limites des ressources
Définissez un plafond de temps et un plafond de mémoire pour chaque avance. Les continuations sérialisées conservent ces limites lors de leur reprise.
Un formulaire d'outil
Les scripts appellent call_tool(name, args). Les arguments nommés exactement survivent à la sérialisation et se lient de manière centralisée dans ADK-Rust.
Environnement contrôlé
Exposez uniquement les valeurs de l’environnement dont la tâche a besoin. Les secrets du processus hôte ne sont jamais hérités automatiquement.
Des échecs visibles
Les erreurs de syntaxe et les exceptions sont renvoyées au modèle sous forme de retour de script réparable ; les échecs d'exécution de l'hôte arrêtent l'exécution.
Durable execution
Un programme en pause peut devenir un état d'agent durable.
Les outils à confirmation et de longue durée peuvent nécessiter que la demande se termine avant que la réponse n'existe. CodeAct capture l'interpréteur en pause, sa transcription et l'appel en attente dans la session afin qu'un autre appel puisse continuer à partir de la même ligne de code.
Enregistrer avant
Conservez la suite avant qu’un outil externe ne soit autorisé à s’exécuter.
Résoudre
Exécutez, approuvez, rejetez ou attendez le résultat de l'outil en attente.
Enregistrer après
Conservez la valeur renvoyée afin que la récupération ne répète pas un appel terminé.
CV
Chargez le point de contrôle et continuez le même script à partir de sa limite d'appel.
Responsabilité du développeur : un crash après un effet secondaire externe mais avant le point de contrôle de sauvegarde après peut entraîner la réexécution de cet outil. Donnez aux outils non idempotents une clé d'idempotence ou une autre garde à action en double.
Mise en œuvre
Quatre pièces définissent l'agent complet.
Choisissez un modèle, fournissez un CodeRuntime, enregistrez les outils que le script peut appeler et exécutez l'agent via le ADK-Rust Runner normal.
use std::sync::Arc;
use adk_agent::codeact::CodeActAgent;
use adk_codeact_monty::MontyRuntime;
let runtime = MontyRuntime::builder()
.environ_var("CART_USER", "u-42")
.environ_var("TAX_REGION", "CA")
.system_clock(true)
.build();
let agent = CodeActAgent::builder()
.name("cart_assistant")
.model(model)
.runtime(Arc::new(runtime))
.instruction("Price the cart by writing Python.")
.tool(Arc::new(fetch_cart))
.tool(Arc::new(tax_rate))
.output_key("priced_cart")
.build()?;Construire avec CodeAct
Transformez une conversation d'outil en plusieurs étapes en un programme lisible.
Commencez par l'exemple déterministe, inspectez chaque pause et reprise, puis connectez le modèle et les outils que votre produit utilise déjà.