Deja que el modelo escriba el flujo de trabajo.
CodeAct es una forma para que un agente de IA actúe escribiendo un programa corto. Ese programa llama solo a las herramientas que usted aprueba, combina sus resultados con código ordinario y devuelve una respuesta a través del tiempo de ejecución 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)
Empieza aquí
¿Qué es un agente CodeAct?
Un agente CodeAct es un agente de IA que escribe código executable para decidir cómo varias herramientas aprobadas deben funcionar juntas. Su aplicación ejecuta ese código en un intérprete controlado y sigue siendo responsable de cada acción externa.
Llamada de herramientas tradicionales
El modelo elige una acción a la vez.
- 01Pregúntele al modelo qué herramienta llamar.
- 02Ejecute esa herramienta y envíe su resultado al modelo.
- 03Pregúntele al modelo qué hacer a continuación y luego repita.
CodeAct
El modelo escribe el procedimiento completo.
- 01Solicite al modelo un programa breve utilizando las herramientas disponibles.
- 02Ejecute el programa y haga una pausa solo cuando llegue a una herramienta real.
- 03Continúe con el resultado de la herramienta hasta que el programa devuelva su respuesta.
Una analogía sencilla
La llamada con herramienta tradicional es como pedirle a un colega que presione un botón de la calculadora, informe la pantalla y espere la siguiente instrucción. CodeAct es como darle permiso a ese colega para escribir una pequeña fórmula en una hoja de cálculo: las entradas permitidas siguen siendo las mismas, pero el cálculo puede contener variables, condiciones, bucles y varios pasos.
Ocho palabras que verás en esta página
modelo
El LLM que escribe el guión.
Agente
El componente que convierte una meta en acciones y resultados.
Herramienta
Una función aprobada Rust que llega a datos o sistemas comerciales.
Guión
El programa corto escrito para el turno del agente actual.
Tiempo de ejecución
El intérprete que executa y pausa el guión.
Observación
Un resultado o error devuelto al modelo para otro turno.
Punto de control
Un programa guardado en pausa que puede continuar más tarde.
resultado final
La respuesta escrita regresó a su solicitud.
De donde vino la idea
CodeAct comenzó como una pregunta de investigación sobre el lenguaje de acción de un agente.
La mayoría de los primeros agentes que usaban herramientas representaban una acción como lenguaje natural o un objeto JSON que contenía un nombre de herramienta y argumentos. Los investigadores Xingyao Wang, Yangyi Chen, Lifan Yuan, Yizhe Zhang, Yunzhu Li, Hao Peng y Heng Ji preguntaron si executable Python sería un formato de acción más expresivo..
Su papel, "Las acciones de código ejecutable generan mejores agentes LLM", se lanzó en febrero de 2024 y apareció en ICML 2024. evaluó 17 modelos de lenguaje en API-Bank y el punto de referencia M³ToolEval del artículo. Los autores informaron que las acciones de código lograron tasas de éxito hasta un 20% más altas que los formatos de acción de texto y JSON probados.
El documento también presentó CodeActInstruct, un conjunto de datos de 7000 interacciones de múltiples turnos y modelos CodeActAgent ajustados al código execute, observe los resultados, revise los programas fallidos y continúe la conversación. Estos son resultados de investigaciones sobre las tareas del artículo; no significan que las acciones del código sean automáticamente mejores para cada producto.
¿Por qué debería utilizar CodeAct?
CodeAct
CodeAct resulta convincente cuando el agente debe combinar herramientas con computación. Le da al modelo un lenguaje familiar para expresar la lógica mientras su aplicación conserva los límites de la herramienta y el tiempo de ejecución.
Componer varias herramientas
Un script puede llamar a varias herramientas aprobadas y pasar un resultado directamente al siguiente paso.
Utilice un flujo de control real
Los bucles, las condiciones, las variables, la clasificación, el filtrado y la aritmética se expresan directamente en el código.
Reducir los viajes de ida y vuelta del modelo
El trabajo que requeriría varios turnos de selección de herramientas a veces se puede expresar en un guión generado.
Mantenga los datos intermedios locales
El tiempo de ejecución puede filtrar o agregar resultados de herramientas grandes antes de decidir qué pertenece a la transcripción del modelo.
Corregir errores executables
Un error de sintaxis, una excepción o una aserción fallida pueden convertirse en una observación que el modelo utiliza para revisar el siguiente script.
Inspeccionar la acción
Los desarrolladores pueden leer el programa generado, las llamadas a herramientas, los resultados y los puntos de control como un rastro execution.
Compensaciones
¿Cuándo debo evitarlo?
Una simple acción
Una llamada normal a la herramienta LlmAgent es más fácil cuando la solicitud se asigna claramente a una operación comercial.
Generación de código débil
Un modelo que tiene dificultades para escribir código válido puede necesitar más turnos de corrección que las llamadas a herramientas estructuradas.
Sin tiempo de ejecución seguro
El código generado necesita un intérprete con acceso explícito y límites de recursos. Nunca lo pases a eval o exec sin restricciones.
Desarrollo de software completo
Utilice CodingAgent cuando el objetivo sea editar repositorios, ejecutar comandos de shell u operar un espacio de trabajo de desarrollo.
Implementaciones en el ecosistema.
El concepto CodeAct aparece ahora en varios sistemas de agentes.
Comparten la idea del código como formato de acción, pero difieren en el soporte del lenguaje, la exposición de las herramientas, el sandboxing, el estado y la carga de trabajo prevista.
CodeAct
Investigación original
Acciones Python, CodeActInstruct, modelos de investigación ajustados y un motor execution en contenedores.
Más información ↗OpenHands
Agentes de software
Su CodeActAgent puede conversar, execute Python y ejecutar comandos de shell para trabajos de desarrollo de software.
Más información ↗smolagents
Hugging Face
CodeAgent utiliza acciones Python con bucles y condiciones y admite varios executors sandbox.
Más información ↗Pydantic AI
Modo de código
Envuelve las herramientas de un agente en una interfaz de código y utiliza Monty como tiempo de ejecución controlado de Python.
Más información ↗ADK-Rust
Tiempo de ejecución nativo Rust
Agrega el bucle CodeAct a agentes, herramientas, sesiones, eventos, aprobaciones, devoluciones de llamadas y transferencias escritos.
Más información ↗Cómo ADK-Rust implementa CodeAct
CodeAct funciona dentro del tiempo de ejecución ADK-Rust.
CodeActAgent es un tipo de agente junto LlmAgent. Le das un modelo, un CodeRuntimey herramientas Rust. Luego lo ejecuta a través de los mismos sistemas Runner, sesión, evento, devolución de llamada, autorización y salida utilizados por otros agentes ADK-Rust.
1. modelo
Elija cualquier proveedor de modelo ADK-Rust capaz de producir código confiable.
2. CodeRuntime
Utilice el tiempo de ejecución Python respaldado por Monty o implemente el rasgo CodeRuntime independiente del idioma.
3. Herramientas Rust
Registrar herramientas mecanografiadas. El script sólo puede acceder a las herramientas proporcionadas para esa invocación.
4. Runner
Ejecute el agente con un usuario y una sesión, luego consuma eventos ADK-Rust escritos normalmente.
5. Sesión
Persista los puntos de control cuando la aprobación o una herramienta de ejecución prolongada detenga el programa.
6. Controles
Aplique confirmación, reintentos, tiempos de espera, devoluciones de llamadas, barreras de seguridad y salidas validadas.
Inicio de trabajo más rápido
Ejecute primero el ejemplo registrado.
Utiliza un modelo determinista, un intérprete Monty Python real, dos herramientas Rust, una sesión en memoria y el ADK-Rust Runner. No se requiere ninguna clave API de modelo.
El adaptador Monty es actualmente una dependencia experimental de Git y requiere Rust 1.95+, por lo que el ejemplo incluye su propio archivo de cadena de herramientas.
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.Arquitectura
El script se ejecuta dentro del sistema del agente.
El modelo propone lógica executable. El CodeRuntime controla cómo avanza esa lógica. ADK-Rust es propietario de cada acción externa, punto de control duradero y evento que ve la aplicación.
modelo
Escribe un script utilizando el resumen del tiempo de ejecución y las herramientas disponibles para esta invocación.
CodeRuntime
Ejecuta el script paso a paso y expone llamadas, finalización, stdout y errores del script.
anfitrión ADK-Rust
Ejecuta herramientas con autorización y contexto, conserva el estado y transmite el resultado final.
Tutorial de execution respaldado por fuentes
Estudio de caso: poner precio a un carrito de compras en un turno CodeAct.
Esto sigue el ejemplo determinista CodeAct × Monty en el repositorio ADK-Rust. Seleccione cada límite para ver qué parte del sistema está funcionando y qué se vuelve visible para la siguiente parte.
Runner
La solicitud ingresa a ADK-Rust.
El Runner adjunta el usuario, la sesión, el contexto de invocación, las devoluciones de llamada y las herramientas disponibles antes de que comience el agente CodeAct.
señal visible
¿Cuál es el total del carro u-42, incluido el impuesto CA?
Elija la forma de agente adecuada
CodeAct tiene un trabajo específico.
Úselo cuando un modelo pueda expresar el trabajo más claramente como programa. ADK-Rust también proporciona formas de agentes para el uso de herramientas conversacionales y entornos completos de desarrollo de software.
LlmAgent
Elija y llame a herramientas de forma conversacional.
Lo mejor para: Preguntas, diálogo, acciones comerciales aisladas y traspasos naturales.
modelo → herramienta → modelo
CodeActAgent
Componga herramientas y lógica en un plan executable.
Lo mejor para: Análisis, transformación de datos, trabajo por lotes, cálculos y flujos condicionales.
modelo → script ↔ herramientas → resultado
CodingAgent
Trabaje dentro de un arnés de desarrollo de software.
Lo mejor para: Edición de repositorios, comandos de shell, compilaciones, pruebas, parches y protocolos de agentes de codificación.
agente ↔ espacio de trabajo + shell
Tiempo de ejecución Monty
Dé al código generado un límite operativo claro.
El adaptador Python actual de ADK-Rust ejecuta Monty en proceso. El anfitrión decide qué puede leer, escribir, conocer y consumir el script antes de que comience execution.
Monty aún es experimental. Actualmente es una dependencia Git fijada y requiere Rust 1.95+. El adaptador vive en su propia caja hasta que Monty esté disponible en crates.io.
Zona de pruebas predeterminada
Sin acceso al sistema de archivos y un entorno vacío. Las operaciones de red y subprocesos no tienen superficie Monty.
Montajes explícitos
Asigne directorios de host seleccionados a rutas virtuales y elija acceso de solo lectura o lectura y escritura para cada uno.
Límites de recursos
Establezca un límite de tiempo y un límite de memoria para cada avance. Las continuaciones serializadas conservan esos límites cuando se reanudan.
Formulario de una herramienta
Los scripts llaman a call_tool(nombre, argumentos). Los argumentos con nombres exactos sobreviven a la serialización y se vinculan centralmente en ADK-Rust.
Ambiente controlado
Exponga sólo los valores ambientales que la tarea necesita. Los secretos del proceso del host nunca se heredan automáticamente.
Fallos visibles
Los errores y excepciones de sintaxis regresan al modelo como comentarios de script reparables; Las fallas en el tiempo de ejecución del host detienen la ejecución.
Durable execución
Un programa en pausa puede convertirse en un estado de agente duradero.
Es posible que las herramientas de confirmación y de larga duración necesiten que la solicitud finalice antes de que exista la respuesta. CodeAct toma una instantánea del intérprete pausado, su transcripción y la llamada pendiente en la sesión para que pueda continuar otra invocación desde la misma línea de código.
guardar antes
Conserve la continuación antes de permitir la ejecución de una herramienta externa.
resolver
Ejecute, apruebe, rechace o espere el resultado de la herramienta pendiente.
Guardar después
Conserve el valor devuelto para que la recuperación no repita una llamada completada.
Currículum
Cargue el punto de control y continúe con el mismo script desde su límite de llamada.
Responsabilidad del desarrollador: un bloqueo después de un efecto secundario externo pero antes del punto de control de guardar después puede hacer que esa herramienta se ejecute nuevamente. Proporcione a las herramientas no idempotentes una clave de idempotencia u otra protección de acción duplicada.
Implementación
Cuatro piezas definen al agente completo.
Elija un modelo, proporcione un CodeRuntime, registre las herramientas que el script puede llamar y ejecute el agente a través del 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()?;Construir con CodeAct
Convierta una conversación de herramientas de varios pasos en un programa legible.
Comience con el ejemplo determinista, inspeccione cada pausa y reanudación, luego conecte el modelo y las herramientas que su producto ya utiliza.