Agentspan es una capa de ejecución de código abierto para agentes de IA cuyo trabajo debe sobrevivir a fallas de procesos, implementaciones, largas esperas y aprobaciones humanas. En lugar de mantener todo el bucle del agente en la memoria de la aplicación, almacena el estado de ejecución en un servidor Agentspan y delega el trabajo de las herramientas a los trabajadores conectados. El proyecto lo construye Orkes en el motor de flujo de trabajo Conductor y actualmente tiene licencia del MIT y es autohospedable.
La distinción importa: Agentspan no convierte a un agente débil en inteligente, no elige permisos seguros ni valida un resultado empresarial. Cambia el modelo de fracaso. Una ejecución obtiene una identidad duradera, los pasos completados tienen un historial, la aprobación pendiente puede esperar en el lado del servidor y un trabajador de reemplazo puede volver a conectarse. Los equipos deben evaluarla como una infraestructura de sistemas distribuidos, no como una biblioteca rápida.
¿Qué cambia cuando el estado sale del proceso del agente?
| Preocupación | Bucle de agente en proceso | Agentspan modelo | El operador todavía posee |
|---|---|---|---|
| Fallo del proceso | La memoria y la posición actual pueden desaparecer | El servidor conserva el estado del flujo de trabajo y reanuda el trabajo | Disponibilidad de trabajadores y herramientas idempotentes. |
| Aprobación humana | La aplicación debe mantener o reconstruir el estado pendiente | El flujo de trabajo puede pausar el lado del servidor y recibir una respuesta más tarde | Política de identidad, tiempo de espera y escalamiento del aprobador |
| Reintentos | Bucle personalizado, a menudo de grano grueso | El reintento por paso es una primitiva del flujo de trabajo | Qué errores se pueden volver a intentar y si los efectos secundarios son seguros |
| Historia | Registros específicos de la aplicación | Las entradas, salidas, tiempos y pasos son consultables. | Controles de redacción, retención y acceso |
| Escala | Estado y programación acoplados a un proceso. | El servidor coordina trabajadores y ejecuciones. | Capacidad, arrendamiento, colas y recuperación ante desastres |
| Programación/eventos | Separe el cron o la plomería de mensajes | Conductor programación e integraciones de eventos | Superposición, deduplicación y comportamiento de eventos perdidos |
La ruta del tiempo de ejecución, dibujada como un límite de falla
usuario/evento
|
v
.--------------------. estado duradero.----------------------.
| código de aplicación | ------------------------> | Agentspan / Conductor|
| Agente + herramientas | <--- task delegation ---- | run, step, history |
'--------------------' '----------+-----------'
| worker may die |
| and reconnect | calls
v v
custom tool process LLM / HTTP / MCP tools
| |
'---------------- results + side effects ---------------'
Durable checkpoint ≠ transaction over every external side effect
La última línea es la advertencia operativa más importante. Un motor de flujo de trabajo puede recordar que solicitó un pago, un correo electrónico o una mutación del repositorio, pero no puede convertir automáticamente en transaccional una acción externa arbitraria. Si un trabajador tiene éxito de forma remota y falla antes de reconocer la finalización, un reintento puede repetir la acción. Cada herramienta mutante necesita una clave de idempotencia, una consulta de conciliación o una ruta de decisión humana.
Haz la prueba de choque antes de la demostración de happy-path
Una prueba de concepto útil mata deliberadamente al trabajador en diferentes límites. Ejecute un trabajo de investigación de solo lectura, un trabajo con un efecto secundario controlado y un trabajo sujeto a aprobación. Conserve el ID de ejecución, reinicie en una máquina diferente, vuelva a conectarse y compare el estado final con una ejecución de control ininterrumpida.
| Punto de inyección | Evidencia esperada | Fallo que debería bloquear el lanzamiento |
|---|---|---|
| Durante una solicitud de LLM | Reintento limitado y una continuación coherente | Gasto de token ilimitado o contexto duplicado |
| Después de completar la herramienta de solo lectura | Reanudar sin perder el resultado anterior | La ejecución se reinicia desde el principio. |
| Después de la escritura remota, antes del reconocimiento | La clave de idempotencia evita un duplicado | Dos tickets, pagos, mensajes o commits |
| Mientras espera la aprobación | El reinicio conserva la solicitud pendiente y la identidad de auditoría | Aprobación implícita, solicitud perdida o aprobador incorrecto |
| Durante el despliegue | Los trabajadores antiguos y nuevos no ejecutan el mismo paso exclusivo | Efectos secundarios del cerebro dividido |
| Después del reinicio del servidor | Se cumple el objetivo de recuperación documentado. | El historial o el estado del flujo de trabajo son irrecuperables |
Los reintentos necesitan un contrato de efectos secundarios
Clasifique las herramientas antes de habilitar los reintentos automáticos. Las funciones puras y las lecturas repetibles normalmente se pueden volver a intentar. Las escrituras requieren una clave de operación estable cuyo ámbito sea el flujo de trabajo y el paso. Las acciones no repetibles necesitan un adaptador de “consulta antes de reintentar” o una cola de conciliación manual. No le pida a un LLM que infiera si un pago o mensaje ya ocurrió a partir del contexto conversacional.
- Reintento seguro: calcular una suma de verificación, leer una página pública o realizar una consulta mediante ID inmutable.
- Condicionalmente seguro: cree un ticket con una clave de idempotencia aplicada por el servidor o actualice un registro conocido con verificación de versión.
- Inseguro por defecto: envíe un correo electrónico, publique contenido, transfiera dinero o ejecute un cambio de producción sin deduplicación.
- Compensable: reservar un recurso cuando exista una operación de cancelación probada y una ruta de escalamiento responsable.
La aprobación humana es un sistema de políticas, no un botón de pausa
Agentspan documenta las herramientas marcadas para aprobación y CLI, API o respuestas de UI. La política de producción debe definir además quién puede aprobar, qué argumentos exactos se congelan, cómo se autentica la identidad, cuándo vence la solicitud y si una acción modificada crea una nueva aprobación. Muestre al aprobador el efecto secundario propuesto, el destino, la divulgación de datos, el costo estimado y una diferencia legible por humanos.
Separe a los solicitantes de los aprobadores para acciones de alto impacto. La denegación debe poner fin o limitar la acción; no debería indicarle al modelo que rodee la puerta con otra herramienta. Registre la versión de la política y el artefacto de aprobación junto con la ejecución para que una repetición no pueda aplicar una decisión anterior a argumentos nuevos.
La compatibilidad del marco no significa una semántica idéntica
La documentación oficial demuestra su propio Agente API e integraciones con LangGraph, los Agentes OpenAI SDK y Google ADK. Pruebe el adaptador y la versión exactos que planea implementar. Verifique la transmisión, la cancelación, los agentes anidados, los ID de llamadas de herramientas, la salida estructurada, la propagación del contexto y el mapeo de errores. Un contenedor puede conservar la interfaz invocable mientras cambia el punto de control o el comportamiento de reintento.
| Elección de integración | La mejor razón para usarlo | Pregunta de validación |
|---|---|---|
| Agente nativo Agentspan | Superficie conceptual más pequeña y primitivas documentadas. | ¿Su abstracción de modelo/herramienta cubre el comportamiento requerido? |
| LangGraph | Gráfico existente, nodos y diseño de estado. | ¿Qué capa posee puntos de control, reintentos e interrupciones? |
| OpenAI Agentes SDK | Agentes existentes, transferencias y convenciones de rastreo | ¿Se asignan los eventos de herramientas y aprobación sin pérdidas? |
| ADK de Google | Implementación existente del agente de Google | ¿Están representados de forma duradera el estado de la sesión y los artefactos? |
| Herramienta HTTP/OpenAPI | Llamada del lado del servidor sin código de trabajo personalizado | ¿Dónde se aplican las credenciales, los límites de velocidad y los esquemas de respuesta? |
| MCP herramienta | Reutilizar la superficie de capacidad de un servidor MCP | ¿Se puede determinar el alcance y auditar cada método expuesto de forma independiente? |
Credenciales y datos de ejecución almacenados
Agentspan admite claves de proveedor a través de la configuración del entorno y las herramientas HTTP, OpenAPI y MCP ejecutadas por el servidor. La ejecución central puede reducir los secretos copiados a cada trabajador, pero también concentra la autoridad. Utilice un administrador secreto, credenciales de corta duración, identidades por entorno y listas de permitidos salientes. Nunca coloque credenciales dentro de solicitudes, esquemas de herramientas o resultados persistentes.
El historial de ejecución puede contener texto del cliente, documentos recuperados, código fuente, respuestas del modelo, argumentos de herramientas y errores. Decida qué campos se redactan antes del almacenamiento, quién puede buscar o reproducir ejecuciones, cómo se separan los inquilinos y cómo se propagan las solicitudes de eliminación a las copias de seguridad y las exportaciones de observabilidad. Cifre el transporte y el almacenamiento, audite el acceso de lectura y pruebe la restauración en lugar de asumir que la persistencia equivale a la recuperabilidad.
Observabilidad que lleva a la acción.
Los rastreos sin procesar son útiles sólo si responden a preguntas operativas. Adjunte un ID de correlación entre el desencadenador, el flujo de trabajo, las llamadas de modelo y las mutaciones externas. Modelo/versión de registro, versión de política de aviso, recuentos de tokens, latencia de herramientas, motivo de reintento, retraso de aprobación y clasificación de terminales. Evite secretos de alta cardinalidad en las etiquetas.
| Métrica | Por qué es importante | Alerta sugerida |
|---|---|---|
| Resultados comerciales exitosos | Separa los flujos de trabajo completados de los resultados correctos | Caída contra la línea de base específica de la tarea |
| Efectos secundarios duplicados | Detecta idempotencia rota | Cualquier duplicado confirmado de herramientas críticas. |
| Reintentos por paso | Encuentra herramientas inestables y costos ocultos | Aumento sostenido por herramienta/versión |
| Edad de aprobación | Muestra trabajo estancado y carga operativa | SLA de póliza anterior o vencida |
| Éxito de la recuperación | Mide la promesa de durabilidad del núcleo | Cualquier ejecución elegible irrecuperable |
| Costo por resultado aceptado | Combina el costo del modelo, el cálculo y el revisor | Flujo de trabajo de regresión versus control |
Lista de verificación de implementación y actualización
- Fije las versiones SDK, servidor y Conductor; registrar la matriz de compatibilidad.
- Separe las credenciales, colas y almacenes de datos de desarrollo, preparación y producción.
- Realice una copia de seguridad de los metadatos del flujo de trabajo y pruebe una restauración en un entorno aislado.
- Establezca presupuestos de simultaneidad, token, tiempo, reintentos y recursividad por agente e inquilino.
- Configure comprobaciones de estado para servidores, trabajadores, colas, bases de datos y proveedores de modelos.
- Utilice trabajadores canary para actualizaciones y mantenga las definiciones de flujo de trabajo antiguas disponibles para ejecuciones en curso.
- Defina la semántica de cancelación: detener trabajos futuros, revocar credenciales y conciliar efectos secundarios parciales.
- Inyección rápida de modelo de amenaza, SSRF, salida de herramientas maliciosas y exposición demasiado amplia a MCP/OpenAPI.
Alternativas y el límite de la selección honesta
| Opción | Elígelo cuando | Compensación |
|---|---|---|
| Agentspan | Quiere APIs específicos del agente sobre Conductor, autohospedaje e integraciones | Nuevo plano de control y superficie de proyecto en evolución. |
| LangGraph persistencia | Tu aplicación ya tiene una forma profundamente gráfica. | Tienes más opciones de orquestación de producción |
| temporales | La organización ya opera flujos de trabajo duraderos a escala | Los adaptadores de agentes y el código seguro para la reproducción requieren ingeniería |
| Conductor directamente | Necesita primitivas de flujo de trabajo generales más allá de los agentes | Menos comodidad específica del agente |
| Patrones de reformulación o DBOS | Quiere funciones/transacciones duraderas cercanas al código de la aplicación | Diferente ecosistema y modelo de integración |
| Cola + máquina de estado de base de datos | El flujo de trabajo es pequeño, determinista y estable. | Recuento de dependencia más bajo, pero la recuperación personalizada y la interfaz de usuario funcionan |
| Plataforma de agentes administrada | La operación rápida importa más que el control de la infraestructura | Restricciones de proveedores, datos y personalización |
No agregue un tiempo de ejecución duradero simplemente porque un flujo de trabajo utiliza un LLM. Es posible que un asistente sincrónico breve y sin efectos secundarios solo necesite solicitar el registro y los reintentos. Agentspan se vuelve atractivo cuando las ejecuciones son largas, las aprobaciones esperan más allá de la vida útil del proceso, los eventos activan el trabajo o el historial de recuperación es un requisito del producto.
Un plan de evaluación de dos semanas
La primera semana debe establecer un flujo de trabajo de control y de integración. Seleccione un trabajo delimitado con tres a diez pasos, una aprobación y una escritura externa reversible. Mida el éxito y el costo ininterrumpidos y luego inyecte fallas. La segunda semana debería centrarse en casos hostiles y operativos: eventos duplicados, aprobaciones retrasadas, resultados de herramientas con formato incorrecto, límites de tarifas de proveedores, reemplazo de trabajadores, reinicio del servidor y una actualización con una ejecución en curso.
Promocione solo si otro ingeniero puede reproducir la implementación y la recuperación a partir de instrucciones escritas, cada herramienta mutante tiene una política de efectos secundarios probada, se rige el historial confidencial y la tasa de resultados aceptados mejora lo suficiente como para justificar la carga del servidor y de guardia.
Preguntas frecuentes
¿Es Agentspan un marco de agente?
Incluye un Agente API, pero su diferenciador es el tiempo de ejecución duradero bajo el agente. También puede ejecutar agentes creados con marcos externos compatibles.
¿Qué es el motor de ejecución?
El proyecto establece que las definiciones de agentes se compilan en flujos de trabajo en Conductor, lo que proporciona estado duradero, historial, reintentos y primitivas de flujo de trabajo.
¿Puede autohospedarse?
Sí. El sitio oficial lo describe como con licencia del MIT y autohospedable. Los operadores aún necesitan validar dependencias, almacenes de datos, actualizaciones y expectativas de soporte.
¿La recuperación tras fallo evita escrituras duplicadas?
No. La orquestación duradera reduce el estado perdido, pero las escrituras externas aún requieren idempotencia, reconciliación o compensación.
¿Las aprobaciones son automáticamente seguras?
No. Los equipos deben definir la autenticación, la autorización, la vinculación de argumentos, la caducidad, la segregación de funciones y la retención de auditoría.
¿Elimina la necesidad de un marco de agente?
No. Puede complementar las definiciones de agentes existentes. Elija un propietario claro para el estado, los reintentos y las interrupciones para evitar semánticas conflictivas.
¿Cuál debería ser la primera carga de trabajo de producción?
Un flujo de trabajo limitado, reversible y de baja sensibilidad con un éxito mensurable y una escalada clara, sin pagos, cambios de producción ni acceso amplio a datos.
fuentes primarias
- Sitio oficial Agentspan e inicio rápido
- Documentación oficial
- Explicación oficial de arquitectura y durabilidad.
- Conceptos de ejecución del agente
- Tipos de herramientas y ejecución del lado del servidor
- Proveedores de modelos compatibles y configuración
- CLI, aprobaciones e historial de ejecución
- Repositorio de fuentes oficiales
- Guía de OWASP para los riesgos de la aplicación LLM
Última revisión el 25 de julio de 2026. Agentspan está evolucionando rápidamente. Verifique la versión exacta de SDK/servidor, la licencia, el adaptador de marco y las instrucciones de implementación antes de adoptarlo.
