Lassen Sie das Modell schreiben den Arbeitsablauf.
CodeAct ist eine Möglichkeit für einen KI-Agenten, Maßnahmen zu ergreifen, indem er ein kurzes Programm schreibt. Dieses Programm ruft nur die von Ihnen genehmigten Tools auf, kombiniert ihre Ergebnisse mit gewöhnlichem Code und gibt über die ADK-Rust-Laufzeit eine Antwort zurück.
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)
Beginnen Sie hier
Was ist ein CodeAct-Agent?
Ein CodeAct-Agent ist ein KI-Agent, der executable-Code schreibt, um zu entscheiden, wie mehrere zugelassene Tools zusammenarbeiten sollen. Ihre Anwendung führt diesen Code in einem kontrollierten Interpreter aus und bleibt für jede externe Aktion verantwortlich.
Traditioneller Werkzeugaufruf
Das Modell wählt jeweils eine Aktion aus.
- 01Fragen Sie das Model, welches Tool es aufrufen soll.
- 02Führen Sie dieses Tool aus und senden Sie das Ergebnis an das Modell zurück.
- 03Fragen Sie das Modell, was als nächstes zu tun ist, und wiederholen Sie den Vorgang.
CodeAct
Das Modell schreibt die komplette Prozedur.
- 01Bitten Sie das Model um ein kurzes Programm mit den verfügbaren Tools.
- 02Führen Sie das Programm aus und pausieren Sie es erst, wenn es ein echtes Werkzeug erreicht.
- 03Fahren Sie mit dem Werkzeugergebnis fort, bis das Programm seine Antwort zurückgibt.
Eine einfache Analogie
Der traditionelle Tool-Aufruf ist so, als würde man einen Kollegen bitten, eine Taschenrechnertaste zu drücken, den Bildschirm anzuzeigen und auf die nächste Anweisung zu warten. CodeAct ist, als würde man einem Kollegen die Erlaubnis erteilen, eine kleine Tabellenkalkulationsformel zu schreiben: Die zulässigen Eingaben bleiben gleich, aber die Berechnung kann Variablen, Bedingungen, Schleifen und mehrere Schritte enthalten.
Acht Wörter werden Sie auf dieser Seite sehen
Modell
Der LLM, der das Skript schreibt.
Agent
Die Komponente, die ein Ziel in Aktionen und Ergebnisse umwandelt.
Werkzeug
Eine genehmigte Rust-Funktion, die Geschäftsdaten oder -systeme erreicht.
Skript
Das Kurzprogramm, das für den aktuellen Agentenzug geschrieben wurde.
Laufzeit
Der Interpreter, der das Skript executes und pausiert.
Beobachtung
Ein Ergebnis oder Fehler wird für eine weitere Runde an das Modell zurückgegeben.
Kontrollpunkt
Ein gespeichertes pausiertes Programm, das später fortgesetzt werden kann.
Endergebnis
Die getippte Antwort wurde an Ihre Bewerbung zurückgegeben.
Woher die Idee kam
CodeAct begann als Forschungsfrage zur Handlungssprache eines Agenten.
Die meisten frühen Werkzeug-verwendenden Agenten stellten eine Aktion als natürliche Sprache oder als JSON-Objekt dar, das einen Werkzeugnamen und Argumente enthielt. Die Forscher Xingyao Wang, Yangyi Chen, Lifan Yuan, Yizhe Zhang, Yunzhu Li, Hao Peng und Heng Ji fragten, ob executable Python wäre ein ausdrucksstärkeres Aktionsformat.
Ihr Papier, „Ausführbare Codeaktionen führen zu besseren LLM-Agenten“, wurde im Februar 2024 veröffentlicht und erschien auf der ICML 2024. Es evaluated 17 Sprachmodelle auf API-Bank und dem M³ToolEval-Benchmark des Papiers. Die Autoren berichteten, dass Code-Aktionen bis zu 20 % höhere Erfolgsraten erzielten als die getesteten Text- und JSON-Aktionsformate.
Das Papier stellte auch vor CodeActInstruct, einem Datensatz aus 7.000 Multi-Turn-Interaktionen und CodeActAgent-Modellen, die auf den execute-Code abgestimmt sind, Ergebnisse beobachten, fehlgeschlagene Programme überarbeiten und die Konversation fortsetzen. Dabei handelt es sich um Forschungsergebnisse zu den Aufgabenstellungen der Arbeit; Sie bedeuten nicht, dass Codeaktionen automatisch für jedes Produkt besser sind.
Warum sollte ich CodeAct verwenden?
CodeAct
CodeAct ist überzeugend, wenn der Agent Werkzeuge mit Berechnung kombinieren muss. Dadurch erhält das Modell eine vertraute Sprache zum Ausdruck von Logik, während Ihre Anwendung die Tool- und Laufzeitgrenzen beibehält.
Stellen Sie mehrere Tools zusammen
Ein Skript kann mehrere zugelassene Tools aufrufen und ein Ergebnis direkt an den nächsten Schritt übergeben.
Verwenden Sie einen echten Kontrollfluss
Schleifen, Bedingungen, Variablen, Sortierung, Filterung und Arithmetik werden direkt im Code ausgedrückt.
Modellrundfahrten reduzieren
Arbeiten, die mehrere Werkzeugauswahldurchgänge erfordern würden, können manchmal in einem generierten Skript ausgedrückt werden.
Halten Sie Zwischendaten lokal
Die Laufzeit kann umfangreiche Werkzeugergebnisse filtern oder aggregieren, bevor sie entscheidet, was in das Modelltranskript gehört.
Korrigieren Sie executable-Fehler
Ein Syntaxfehler, eine Ausnahme oder eine fehlgeschlagene Behauptung kann zu einer Beobachtung werden, die das Modell zur Überarbeitung des nächsten Skripts verwendet.
Überprüfen Sie die Aktion
Entwickler können das generierte Programm, Toolaufrufe, Ausgaben und Prüfpunkte als execution-Trail lesen.
Kompromisse
Wann sollte ich es vermeiden?
Eine einfache Aktion
Ein normaler LlmAgent-Toolaufruf ist einfacher, wenn die Anforderung eindeutig einem Geschäftsvorgang zugeordnet ist.
Schwache Codegenerierung
Ein Modell, das Schwierigkeiten hat, gültigen Code zu schreiben, benötigt möglicherweise mehr Korrekturdurchgänge als strukturierte Toolaufrufe.
Keine sichere Laufzeit
Generierter Code benötigt einen Interpreter mit expliziten Zugriffs- und Ressourcenbeschränkungen. Geben Sie es niemals an den uneingeschränkten eval oder exec weiter.
Vollständige Softwareentwicklung
Verwenden Sie CodingAgent, wenn das Ziel darin besteht, Repositorys zu bearbeiten, Shell-Befehle auszuführen oder einen Entwicklungsarbeitsbereich zu betreiben.
Implementierungen im Ökosystem
Das CodeAct-Konzept taucht mittlerweile in mehreren Agentensystemen auf.
Sie teilen die Idee von Code als Aktionsformat, unterscheiden sich jedoch in der Sprachunterstützung, der Tool-Bereitstellung, dem Sandboxing, dem Status und der beabsichtigten Arbeitsbelastung.
CodeAct
Originalforschung
Python-Aktionen, CodeActInstruct, fein abgestimmte Forschungsmodelle und eine containerisierte execution-Engine.
Erfahren Sie mehr ↗OpenHands
Software-Agenten
Sein CodeActAgent kann sich unterhalten, execute Python und Shell-Befehle für Softwareentwicklungsarbeiten ausführen.
Erfahren Sie mehr ↗smolagents
Hugging Face
CodeAgent verwendet Python-Aktionen mit Schleifen und Bedingungen und unterstützt mehrere Sandbox-executors.
Erfahren Sie mehr ↗Pydantic AI
Codemodus
Packt die Tools eines Agenten in eine Codeschnittstelle und verwendet Monty als kontrollierte Python-Laufzeit.
Erfahren Sie mehr ↗ADK-Rust
Rust-native Laufzeit
Fügt die CodeAct-Schleife zu typisierten Agenten, Tools, Sitzungen, Ereignissen, Genehmigungen, Rückrufen und Weiterleitungen hinzu.
Erfahren Sie mehr ↗Wie ADK-Rust CodeAct implementiert
CodeAct funktioniert innerhalb der ADK-Rust-Laufzeit.
CodeActAgent ist nebenbei ein Agententyp LlmAgent. Sie geben ihm ein Modell, a CodeRuntime, und Rust-Tools. Anschließend führen Sie es über dieselben Runner-, Sitzungs-, Ereignis-, Rückruf-, Autorisierungs- und Ausgabesysteme aus, die auch von anderen ADK-Rust-Agenten verwendet werden.
1. Modell
Wählen Sie einen beliebigen ADK-Rust-Modellanbieter, der in der Lage ist, zuverlässigen Code zu erstellen.
2. CodeRuntime
Verwenden Sie die von Monty unterstützte Laufzeit Python oder implementieren Sie das sprachunabhängige Merkmal CodeRuntime.
3. Rust-Werkzeuge
Registrieren Sie getippte Werkzeuge. Das Skript kann nur die für diesen Aufruf bereitgestellten Tools erreichen.
4. Runner
Führen Sie den Agenten mit einem Benutzer und einer Sitzung aus und nutzen Sie dann normal typisierte ADK-Rust-Ereignisse.
5. Sitzung
Behalten Sie Prüfpunkte bei, wenn die Genehmigung oder ein Tool mit langer Laufzeit das Programm anhält.
6. Kontrollen
Wenden Sie Bestätigungen, Wiederholungsversuche, Zeitüberschreitungen, Rückrufe, Leitplanken und validierte Ausgaben an.
Schnellster Arbeitsstart
Führen Sie zuerst das eingecheckte Beispiel aus.
Es verwendet ein deterministisches Modell, einen echten Monty Python-Interpreter, zwei Rust-Tools, eine In-Memory-Sitzung und den ADK-Rust Runner. Es ist kein Modell-API-Schlüssel erforderlich.
Der Monty-Adapter ist derzeit eine experimentelle Git-Abhängigkeit und erfordert Rust 1.95+, daher verfügt das Beispiel über eine eigene Toolchain-Datei.
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.Architektur
Das Skript wird im Agentensystem ausgeführt.
Das Modell schlägt die executable-Logik vor. Der CodeRuntime steuert, wie diese Logik voranschreitet. ADK-Rust besitzt alle externen Aktionen, dauerhaften Prüfpunkte und Ereignisse, die die Anwendung sieht.
Modell
Schreibt ein Skript unter Verwendung der Laufzeitbesprechung und der für diesen Aufruf verfügbaren Tools.
CodeRuntime
Führt das Skript Schritt für Schritt aus und macht Aufrufe, Vervollständigungen, stdout und Skriptfehler sichtbar.
ADK-Rust-Host
Führt Tools mit Autorisierung und Kontext aus, behält den Status bei und streamt das Endergebnis.
Quellgestützte execution-Komplettlösung
Fallstudie: Bewerten Sie einen Warenkorb in einer CodeAct-Runde.
Dies folgt dem deterministischen CodeAct × Monty-Beispiel im ADK-Rust-Repository. Wählen Sie jede Grenze aus, um zu sehen, welcher Teil des Systems funktioniert und was für den nächsten Teil sichtbar wird.
Runner
Die Anforderung wird als ADK-Rust eingegeben
Der Runner hängt den Benutzer, die Sitzung, den Aufrufkontext, Rückrufe und verfügbare Tools an, bevor der CodeAct-Agent beginnt.
Sichtbares Signal
Wie hoch ist der Gesamtbetrag für den Warenkorb U-42, einschließlich CA-Steuer?
Wählen Sie die richtige Agentenform
CodeAct hat einen bestimmten Job.
Verwenden Sie es, wenn ein Modell die Arbeit als Programm klarer ausdrücken kann. ADK-Rust bietet außerdem Agentenformen für die Verwendung von Konversationstools und vollständige Softwareentwicklungsumgebungen.
LlmAgent
Werkzeuge im Gespräch auswählen und aufrufen.
Am besten für: Fragen, Dialoge, isolierte Geschäftshandlungen und natürliche Übergaben.
Modell → Werkzeug → Modell
CodeActAgent
Stellen Sie Tools und Logik in einem executable-Plan zusammen.
Am besten für: Analyse, Datentransformation, Batch-Arbeit, Berechnungen und bedingte Abläufe.
Modell → Skript ↔ Werkzeuge → Ergebnis
CodingAgent
Arbeiten Sie innerhalb eines Software-Entwicklungssystems.
Am besten für: Repository-Bearbeitung, Shell-Befehle, Builds, Tests, Patches und Coding-Agent-Protokolle.
Agent ↔ Arbeitsbereich + Shell
Monty-Laufzeit
Geben Sie dem generierten Code eine klare Betriebsgrenze.
Der aktuelle Python-Adapter von ADK-Rust führt Monty im Prozess aus. Der Host entscheidet, was das Skript lesen, schreiben, wissen und konsumieren kann, bevor execution beginnt.
Monty ist noch experimentell. Es handelt sich derzeit um eine angeheftete Git-Abhängigkeit und erfordert Rust 1.95+. Der Adapter bleibt in seiner eigenen Kiste, bis Monty auf crates.io verfügbar ist.
Standard-Sandbox
Kein Dateisystemzugriff und eine leere Umgebung. Netzwerk- und Unterprozessoperationen haben keine Monty-Oberfläche.
Explizite Mounts
Ordnen Sie ausgewählte Hostverzeichnisse virtuellen Pfaden zu und wählen Sie für jedes Verzeichnis schreibgeschützten oder Lese-/Schreibzugriff.
Ressourcengrenzen
Legen Sie für jeden Fortschritt eine Zeit- und Speicherobergrenze fest. Serialisierte Fortsetzungen behalten diese Grenzwerte bei, wenn sie fortgesetzt werden.
Ein Werkzeugformular
Skripte rufen call_tool(name, args) auf. Exakt benannte Argumente überleben die Serialisierung und werden zentral in ADK-Rust gebunden.
Kontrollierte Umgebung
Stellen Sie nur die Umgebungswerte bereit, die die Aufgabe benötigt. Geheimnisse des Hostprozesses werden niemals automatisch vererbt.
Sichtbare Fehler
Syntaxfehler und Ausnahmen werden als behebbares Skript-Feedback an das Modell zurückgegeben. Host-Laufzeitfehler stoppen die Ausführung.
Langlebige execution
Ein angehaltenes Programm kann zum dauerhaften Agentenstatus werden.
Bei bestätigungsgesteuerten und lang laufenden Tools kann es erforderlich sein, dass die Anfrage beendet wird, bevor die Antwort vorliegt. CodeAct erstellt einen Snapshot des angehaltenen Interpreters, seines Transkripts und des ausstehenden Aufrufs in der Sitzung, sodass ein weiterer Aufruf von derselben Codezeile aus fortgesetzt werden kann.
Vorher speichern
Behalten Sie die Fortsetzung bei, bevor ein externes Tool ausgeführt werden darf.
Lösen
Führen Sie das ausstehende Werkzeugergebnis aus, genehmigen Sie es, lehnen Sie es ab oder warten Sie darauf.
Speichern Sie danach
Behalten Sie den zurückgegebenen Wert bei, damit bei der Wiederherstellung ein abgeschlossener Aufruf nicht wiederholt wird.
Lebenslauf
Laden Sie den Prüfpunkt und setzen Sie dasselbe Skript ab seiner Aufrufgrenze fort.
Entwicklerverantwortung: Ein Absturz nach einem externen Nebeneffekt, aber vor dem Save-After-Checkpoint kann dazu führen, dass das Tool erneut ausgeführt wird. Geben Sie nicht-idempotenten Werkzeugen einen Idempotenzschlüssel oder einen anderen Schutz mit doppelter Aktion.
Umsetzung
Vier Teile definieren den gesamten Agenten.
Wählen Sie ein Modell, stellen Sie einen CodeRuntime bereit, registrieren Sie die Tools, die das Skript aufrufen kann, und führen Sie den Agenten über den normalen ADK-Rust Runner aus.
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()?;Erstellen Sie mit CodeAct
Verwandeln Sie eine mehrstufige Tool-Konversation in ein lesbares Programm.
Beginnen Sie mit dem deterministischen Beispiel, überprüfen Sie jede Pause und jeden Neustart und verbinden Sie dann das Modell und die Tools, die Ihr Produkt bereits verwendet.