CodeAct

CodeAct permite a un agente resolver una tarea escribiendo código y ejecutándolo a través de una execute_code herramienta. En lugar de pedir al modelo que emita una llamada de herramienta a la vez, CodeAct le proporciona un lugar aislado para combinar el flujo de control, la transformación de datos y la orquestación de herramientas dentro de un solo paso de ejecución.

En Agent Framework, CodeAct se expone a través de paquetes específicos del back-end en lugar de un único tipo de núcleo integrado. Un conector puede añadir la herramienta execute_code, inyectar orientación en tiempo de ejecución y, opcionalmente, exponer herramientas propias del proveedor a las que se pueda acceder desde dentro del entorno de pruebas.

Por qué CodeAct

Los agentes de IA modernos a menudo no se ven limitados por la calidad del modelo, sino por la sobrecarga de orquestación. Cuando un agente encadena muchas llamadas a herramientas pequeñas, cada paso normalmente requiere otro turno de modelo, lo que aumenta la latencia y el uso del token.

CodeAct simplifica ese modelo: el bucle herramienta > — modelo >. En lugar de pedir al modelo que elija una herramienta a la vez, Agent Framework puede exponer una sola execute_code herramienta y permitir que el modelo exprese el plan completo como un programa corto. Las herramientas siguen siendo las mismas, el modelo sigue siendo el mismo, y el cambio principal es que el plan se ejecuta una sola vez dentro de un entorno de pruebas en lugar de distribuirse a lo largo de varias rondas de llamadas a herramientas.

En el caso de las cargas de trabajo intensivas en herramientas, ese cambio puede reducir materialmente la latencia de un extremo a otro y el uso de tokens, al tiempo que mantiene el plan compacto y auditable en un bloque de código. Consulte la integración de Hyperlight CodeAct para obtener una comparación de cableado en paralelo.

Cuando CodeAct es una buena opción

Use CodeAct cuando una tarea se beneficia de:

  • combinar varias llamadas a herramientas con bucles, ramificación, filtrado o agregación
  • transformar los resultados de la herramienta antes de devolver una respuesta final
  • generar salidas o artefactos estructurados más grandes como parte de una ejecución
  • mantener algunas herramientas disponibles solo dentro de un entorno de ejecución controlado
  • agrupando muchas consultas pequeñas y encadenables o cálculos ligeros en un único paso de ejecución

Sigue utilizando la llamada directa a herramientas cuando:

  • La tarea solo necesita una o dos llamadas a herramientas, por lo que hay poca sobrecarga de orquestación que eliminar.
  • cada llamada tiene efectos secundarios que deben permanecer visibles individualmente para el modelo y el usuario
  • Necesitas solicitudes de aprobación por llamada, en lugar de una única decisión de aprobación para toda la ejecución de execute_code

Cómo encaja CodeAct en Agent Framework

Normalmente, un conector CodeAct realiza cuatro cosas para una ejecución:

  1. Añade una herramienta execute_code a la interfaz de herramientas orientada al modelo.
  2. Proporciona instrucciones para el entorno de ejecución de zona configurado.
  3. Opcionalmente, expone herramientas propiedad del proveedor a través de call_tool(...).
  4. Aplica límites de capacidad, como el acceso al sistema de archivos o las listas de permitidos de red saliente.

Dado que el conector posee la configuración en tiempo de ejecución, los detalles exactos de configuración dependen del back-end que elija.

Limitaciones actuales

Warning

No se admite la combinación de FIDES con proveedores actuales de CodeAct. FIDES actualmente solo es compatible con Python y no está disponible en proveedores de CodeAct para .NET.

Las llamadas a herramientas del host administradas por el proveedor dentro del código generado no pasan por la canalización de middleware por función del agente. Las comprobaciones en las herramientas directas del agente o en la llamada externa execute_code no establecen la aplicación de FIDES para las llamadas anidadas ni los valores intermedios internos del código. Tampoco cubren las funcionalidades de archivo o red.

Las herramientas de host deben aplicar sus propios controles de autorización y destino. Mantenga las herramientas dependientes de FIDES como herramientas de agente directo, no herramientas administradas por CodeAct o deje CodeAct deshabilitado para los flujos de trabajo que requieren estas garantías. Este límite de compatibilidad es una limitación de integración actual, no una limitación inherente del patrón CodeAct. Consulte Seguridad del agente con FIDES.

CodeAct es una buena opción para flujos de trabajo pesados de herramientas, pero tenga en cuenta las siguientes restricciones:

  • Hyperlight CodeAct admite Python y .NET. Monty es exclusivo de Python; Local CodeAct es solo para .NET.
  • Actualmente, las aprobaciones se aplican a la llamada execute_code en su conjunto. Si necesitas que las operaciones individuales se aprueben una por una, mantén esas operaciones como herramientas directas del agente en lugar de depender de call_tool(...).
  • Las herramientas a las que se accede a través de call_tool(...) siguen ejecutándose en el proceso del host. Utiliza herramientas del host específicas y revisadas para las operaciones de E/S sensibles, en lugar de ampliar innecesariamente el acceso al entorno de pruebas.
  • CodeAct funciona mejor cuando predomina la sobrecarga de la orquestación. Para tareas pequeñas con solo una o dos invocaciones de herramientas, puede que la abstracción adicional no merezca la pena.
  • Los nombres de las herramientas, los metadatos de los parámetros y los tipos de retorno cobran mayor importancia aquí, ya que el modelo escribe código según ese contrato, en lugar de elegir entre una llamada directa a una herramienta cada vez.

Comienza

Para .NET, Hyperlight CodeAct se distribuye como el paquete Microsoft.Agents.AI.Hyperlight. Local CodeAct ejecuta Python generado en un subproceso y se basa en el aislamiento externo.

El paquete Hyperlight proporciona:

  • HyperlightCodeActProvider — un AIContextProvider que inyecta execute_code y las directrices de CodeAct en cada ejecución
  • HyperlightExecuteCodeFunction — un AIFunction independiente para el cableado estático/manual cuando la configuración del entorno aislado es fija
  • herramientas administradas por el proveedor que permanecen disponibles dentro del espacio aislado a través de call_tool(...)
  • Integración de CodeActApprovalMode y ApprovalRequiredAIFunction para las aprobaciones
  • configuración opcional del sistema de archivos (FileMounts, HostInputDirectory) y de la red de salida (AllowedDomains) para el entorno de ejecución del espacio aislado

Importante

El paquete .NET está en versión preliminar y depende de Hyperlight.HyperlightSandbox.Api NuGet, que aún no se publica en nuget.org. Consulte Hyperlight CodeAct para ver las advertencias de instalación actuales y los requisitos de la plataforma.

Consulte Hyperlight CodeAct para obtener información sobre la instalación, ejemplos y instrucciones específicas del entorno de ejecución.

Comienza

Para Python, usa Hyperlight CodeAct para un espacio aislado o Monty para un intérprete restringido multiplataforma.

El paquete Hyperlight proporciona:

  • HyperlightCodeActProvider para ejecuciones basadas en proporcionador de contexto
  • HyperlightExecuteCodeTool cuando desea conectar execute_code directamente
  • herramientas administradas por el proveedor que permanecen disponibles dentro del espacio aislado a través de call_tool(...)
  • configuración opcional del sistema de archivos y de la red externa para el tiempo de ejecución de la sandbox

Consulte Hyperlight CodeAct para la instalación, ejemplos, instrucciones específicas del entorno de ejecución, como cuándo usar print(...) y /output/, y las limitaciones actuales específicas de Hyperlight.

Note

La compatibilidad con go para esta característica estará disponible próximamente. Consulte el repositorio de Agent Framework Go para obtener el estado más reciente.

Pasos siguientes

Seguridad del agente

Contenido relacionado

  • Se actualizó por última vez el