Notas prácticas: Herramientas de agente de IA empresarial
Guía paso a paso para utilizar las notas prácticas: Herramientas de agente de IA empresarial: contratos, verificaciones y espacios para código listos para usar por los equipos que implementan este patrón.
Las notas siguientes reconstruyen un camino práctico relacionado con “Engineering Enterprise AI Agent Harnesses”. Se da énfasis en los contratos, las verificaciones y los marcadores de posición para código, en lugar de en un enfoque motivacional. Al trabajar en la etapa de Resumen, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema.
1. El modelo, el agente y el harness son cosas diferentes
El agente modelo 1 y la etapa funcionan mejor cuando se tratan como una superficie medible. Capture una transcripción exitosa, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el camino de recuperación juntos. Las reintentos, los controles humanos y el manejo de correos no entregados forman parte del producto, no son mejoras posteriores. Asigne un presupuesto de tokens por turno y por sesión. Las herramientas agencia expanden el contexto de manera intensiva; los límites máximos evitan que las demostraciones se conviertan en facturas inesperadas.
Observe → Reason → Validate → Act → Observe
2. Por qué los sistemas empresariales necesitan un marco de control
La etapa de los sistemas empresariales “2 Por Qué” funciona mejor cuando se trata como una superficie medible. Capture un registro clave, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el fallo debe apuntar a una sola responsabilidad y no a un proceso complicado. Exponga herramientas con esquemas limitados y etiquetas claras de efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.
3. La arquitectura de aprovechamiento del agente empresarial
La etapa del agente empresarial funciona mejor cuando se trata como una superficie medible. Capture un registro de éxito ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Considere esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los hosts necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.
Límite entre usuario y aplicación
La etapa de límite entre el usuario y la aplicación funciona mejor cuando se trata como una superficie medible. Capture un registro de éxito ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. La visibilidad temprana del costo evita facturas inesperadas cuando el proceso pasa de la fase de demostración a entornos compartidos. Exponga herramientas con esquemas limitados y etiquetas explícitas sobre efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.
Planificador y gestor de estado
La etapa de planificador y gestor estatal funciona mejor cuando se trata como una superficie medible. Capture una transcripción ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el grafo. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los hosts necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.
Rendimiento del modelo
La etapa de ejecución del modelo funciona mejor cuando se trata como una superficie medible. Capture una transcripción exitosa, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el camino de recuperación juntos. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Asigne un presupuesto de tokens por turno y por sesión. Las herramientas agentes amplían el contexto de manera excesiva; los límites máximos evitan que las demostraciones se conviertan en facturas inesperadas.
Registro de herramientas
La etapa de registro de herramientas funciona mejor cuando se trata como una superficie medible. Capture una transcripción ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Exponga las herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los hosts necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.
Motor de políticas
La etapa del motor de políticas funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente. La etapa del motor de políticas funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema.
Lineamientos
En la fase Guardrails, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las intentonas repetidas, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Autentique en la pasarela y vuelva a autorizarlo en el plano de datos. Un token portador por sí solo no constituye un límite entre tenencias.
Control de aprobación humana
En la etapa de aprobación humana, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el error debe indicar una única responsabilidad y no un proceso complicado. Autentique en la puerta de enlace y vuelva a autorizar en el plano de datos. Un token portador por sí solo no constituye un límite entre tenencias.
Ejecutor de herramientas y entorno aislado
Para el ejecutor de herramientas y la etapa de entorno aislado, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Trate esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace las completaciones parciales silenciosas. Autentíquese en la pasarela y vuelva a autorizarse en el plano de datos. Un token portador por sí solo no constituye un límite entre tenencias. Para el ejecutor de herramientas y la etapa de entorno aislado, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar que los operadores puedan auditar sin necesidad de leer todo el sistema.
Memoria y datos
Al trabajar en la etapa de Memoria y datos, anote primero el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documente junto con ello el camino óptimo y el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar agentes en bucles sin esa huella desperdicia horas.
Observabilidad y trazas
Al trabajar en la etapa de Observabilidad y trazas, primero escribe el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Prefiere unidades pequeñas y probables a scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Registra el nombre de la herramienta de registro, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar agentes sin esa huella desperdicia horas.
Evaluaciones y comentarios
Al trabajar en la fase de evaluaciones y retroalimentación, primero escribe el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Considera esta fase como un contrato entre las entradas y los resultados validados. Nombra los artefactos, define las comprobaciones de éxito y rechaza las completaciones parciales silenciosas. Registra el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar sin ese historial desperdicia horas. Al trabajar en la fase de evaluaciones y retroalimentación, primero escribe el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Mantén la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema.
4. Ejecución paso a paso de un ejecutado del agente
La ejecución paso a paso en 4 etapas funciona mejor cuando se trata como una superficie medible. Capture una transcripción exitosa, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el camino de recuperación. Las reintentos, los controles humanos y el manejo de correos no entregados forman parte del producto, no son mejoras posteriores. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los hosts necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.
Paso 1: Recibir y clasificar el objetivo
El Paso 1: Recibir y preparar funciona mejor cuando se trata como una superficie medible. Capture una transcripción exitosa, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.
Paso 2: Construir un contexto delimitado
La etapa de construcción del Paso 2 funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Considere esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente. La etapa de construcción del Paso 2 funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema.
Paso 3: Pida al modelo la siguiente acción
En la fase 3 “Hacer la pregunta”, defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Prefiera salidas estructuradas con validación de esquema sobre texto libre cuando el siguiente paso sea escribir código o realizar una llamada a una herramienta.
Paso 4: Validar fuera del modelo
En la etapa 4 de validación externa, defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea desde un punto de control conocido sin tener que adivinar el estado oculto. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando una tarea falla, el error debe indicar una única responsabilidad y no un proceso complicado. Prefiera salidas estructuradas con validación de esquema en lugar de texto libre cuando el paso siguiente sea código o una llamada a una herramienta.
Paso 5: Obtener aprobación cuando sea necesario
En la etapa 5, Obtener aprobación, defina las entradas, el responsable de la etapa y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la etapa a partir de un punto de control conocido sin tener que adivinar el estado oculto. Trate esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Autentíquese en la pasarela y vuelva a autorizarse en el plano de datos. Un token portador por sí solo no constituye un límite entre tenencias. En la etapa 5, Obtener aprobación, defina las entradas, el responsable de la etapa y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la etapa a partir de un punto de control conocido sin tener que adivinar el estado oculto. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar que los operadores puedan auditar sin tener que leer todo el sistema.
Paso 6: Ejecutar en un entorno controlado
Al trabajar en la fase de Ejecutar del Paso 6, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación ayuda a mantener la transparencia en los cambios posteriores del código. Documente tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras realizadas posteriormente. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar sin ese historial desperdicia horas.
Paso 7: Normalizar la observación
Al trabajar en la etapa 7, “Normalizar”, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación ayuda a mantener honestas las futuras modificaciones del código. Prefiera unidades pequeñas y probables sobre scripts extensos. Cuando una etapa falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar bucles sin esa información desperdicia horas.
Etapa 8: Continuar o detenerse
Al trabajar en la etapa de Continuar del Paso 8, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Considere esta etapa como un contrato entre los datos de entrada y los resultados validados. Asigne nombres a los artefactos, defina las comprobaciones de éxito y evite completaciones parciales silenciosas. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar agentes sin ese historial desperdicia horas. Al trabajar en la etapa de Continuar del Paso 8, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema.
Paso 9: Generar la respuesta final y el seguimiento
La etapa 9, “Producir la fase”, funciona mejor cuando se trata como una superficie medible. Capture un registro exitoso, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el camino de recuperación juntos. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.
5. Ejemplo: un agente de cuentas por cobrar
Los 5 ejemplos demuestran que la etapa de cuentas por cobrar funciona mejor cuando se trata como un área medible. Capture una transcripción ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el fallo debe apuntar a una sola responsabilidad y no a un proceso complicado. Exponga herramientas con esquemas limitados y etiquetas claras sobre efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.
6. Modos de fallo que el sistema debe prevenir
Los 6 modos de fallo para los que esta etapa funciona mejor son cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los hosts necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.
Seguridad basada únicamente en prompts
La etapa de seguridad basada únicamente en prompts funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo en tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando se pasa de entornos de demostración a entornos compartidos. Asigne un presupuesto de tokens por turno y por sesión. Las herramientas agenciales amplían el contexto de manera intensiva; los límites estrictos impiden que las demostraciones se conviertan en facturas inesperadas.
Conexión directa modelo-herramienta
La etapa de conexión directa entre modelo y herramienta funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de credenciales secretas y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema.
Credenciales compartidas excesivamente potentes
La etapa de credenciales compartidas con excesivo poder funciona mejor cuando se trata como una superficie medible. Capture un registro exitoso, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.
Contenido no confiable que se convierte en instrucciones
La etapa en la que el contenido no fiable se convierte en instrucciones funciona mejor cuando se trata como una superficie medible. Capture un registro de éxito ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando falla un paso, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los hosts necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.
Bucles ilimitados
La etapa de bucles ilimitados funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace completaciones parciales silenciosas. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente. La etapa de bucles ilimitados funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema.
Registro de todo
En la etapa de registro de todo, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Autentique en la pasarela y vuelva a autorizarlo en el plano de datos. Un token portador por sí solo no constituye un límite entre tenencias.
Medición únicamente de respuestas correctas
En la fase de “Solo medición de respuestas fluidas”, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el error debe indicar una única responsabilidad y no un proceso complicado. Autentique en la pasarela de entrada y vuelva a autorizarlo en el plano de datos. Un token portador por sí solo no constituye un límite entre tenencias.
7. Configurar un entorno local para aprovechar la IA
Para el paso 7, establezca una etapa, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Trate esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Autentíquese en la pasarela y vuelva a autorizarse en el plano de datos. Un token portador por sí solo no constituye un límite entre tenencias. Para el paso 7, establezca una etapa, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar que los operadores puedan auditar sin tener que leer todo el sistema.
Requisitos previos
Al trabajar en la etapa de Requisitos previos, anote primero el contrato: los datos necesarios, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documente junto con ello el camino óptimo y el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar agentes sin ese rastro desperdicia horas.
mkdir enterprise-agent-harness
cd enterprise-agent-harness
python -m venv .venv
source .venv/bin/activate
.venv\Scripts\Activate.ps1
python -m pip install openai pydantic fastapi uvicorn python-dotenv
Mantenga la configuración separada de los secretos
Al trabajar en la configuración de Keep por separado de la etapa, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Prefiera unidades pequeñas y probables sobre scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar bucles de agentes sin esa huella desperdicia horas.
AI_PROVIDER=openai
AI_MODEL=<approved-model-id>
OPENAI_API_KEY=<set-locally-never-commit>
HARNESS_ENV=development
HARNESS_MAX_STEPS=8
HARNESS_RUN_TIMEOUT_SECONDS=120
HARNESS_MAX_TOOL_RETRIES=2
HARNESS_REQUIRE_APPROVAL_FOR_WRITES=true
Use una estructura de proyecto en capas
Al trabajar en la etapa de “Usar un proyecto en capas”, anote primero el contrato: los insumos requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Trate esta etapa como un contrato entre los insumos y los resultados validados. Asigne nombres a los artefactos, defina las comprobaciones de éxito y evite completar tareas parcialmente sin informar al respecto. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar sin ese historial desperdicia horas.
enterprise-agent-harness/
├── app/
│ ├── api.py # authenticated HTTP entry point
│ ├── harness.py # observe/reason/validate/act loop
│ ├── model_adapter.py # provider-specific model calls
│ ├── schemas.py # typed proposals and observations
│ ├── tools/
│ │ ├── registry.py # available capabilities
│ │ ├── invoices.py # example read-only tool
│ │ └── email.py # example external-write tool
│ ├── policy/
│ │ ├── engine.py # allow/deny/require-approval
│ │ └── rules.yaml # reviewed declarative policy
│ ├── approvals.py # exact-action approval records
│ ├── sandbox.py # isolated execution adapter
│ ├── state.py # run and conversation state
│ ├── telemetry.py # sanitized events and traces
│ └── redaction.py # secret and sensitive-data filtering
├── evals/
│ ├── cases.jsonl # representative tasks and attacks
│ └── run_evals.py
├── tests/
│ ├── test_policy.py
│ ├── test_tools.py
│ └── test_harness.py
├── Dockerfile
├── compose.yaml
├── .env
.example
└── pyproject.toml
Al trabajar en la etapa de “Usar un proyecto en capas”, anote primero el contrato: los insumos requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema.
Defina primero el límite de autonomía
La etapa de definición del límite de autonomía funciona mejor cuando se trata como una superficie medible. Capture una transcripción ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente junto con ello el camino óptimo y el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.
8. Cree un conjunto de referencia ejecutable
El método “8 Build a runnable stage” funciona mejor cuando se considera como una superficie medible. Capture una transcripción exitosa, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el fallo debe referirse a una sola responsabilidad y no a un proceso complicado. Exponga herramientas con esquemas limitados y etiquetas claras sobre efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.
Defina contratos tipados
La etapa de definición de contratos tipados funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.
from enum import Enum
from typing import Any, Literal
from pydantic import BaseModel, Field
class Risk(str, Enum):
READ_ONLY = "read_only"
SENSITIVE_READ = "sensitive_read"
EXTERNAL_WRITE = "external_write"
DESTRUCTIVE = "destructive"
class ToolProposal(BaseModel):
tool: str
arguments: dict[str, Any]
reason: str
class PolicyDecision(BaseModel):
outcome: Literal["allow", "deny", "require_approval"]
reason_code: str
explanation: str
class Observation(BaseModel):
tool: str
ok: bool
data: dict[str, Any] = Field(default_factory=dict)
error_code: str | None = None
class RunState(BaseModel):
run_id: str
user_id: str
tenant_id: str
goal: str
step: int = 0
observations: list[Observation] = Field(default_factory=list)
finished: bool = False
La etapa de definición de contratos tipados funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los administradores puedan auditarlos sin tener que leer todo el sistema.
Registre herramientas con metadatos de seguridad
Para las herramientas de Register con fase de seguridad, defina las entradas, el responsable de la etapa y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la etapa a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las intentonas, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Autentique en la pasarela y vuelva a autorizar en el plano de datos. Un token portador por sí solo no constituye un límite entre tenencias.
from dataclasses import dataclass
from typing import Callable
@dataclass(frozen=True)
class ToolDefinition:
name: str
risk: Risk
handler: Callable[..., dict]
timeout_seconds: int
idempotent: bool
TOOLS = {
"list_overdue_invoices": ToolDefinition(
name="list_overdue_invoices",
risk=Risk.SENSITIVE_READ,
handler=list_overdue_invoices,
timeout_seconds=10,
idempotent=True,
),
"send_email": ToolDefinition(
name="send_email",
risk=Risk.EXTERNAL_WRITE,
handler=send_email,
timeout_seconds=15,
idempotent=False,
),
}
Implemente una política determinista
En la fase de implementación de políticas deterministas, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el error debe indicar una única responsabilidad y no un proceso complicado. Autentique en la pasarela de entrada y vuelva a autorizarlo en el plano de datos. Un token portador por sí solo no constituye un límite entre tenencias.
def authorize(state: RunState, proposal: ToolProposal) -> PolicyDecision:
definition = TOOLS.get(proposal.tool)
if definition is None:
return PolicyDecision(
outcome="deny",
reason_code="UNKNOWN_TOOL",
explanation="The requested capability is not registered.",
)
if not identity_can_use_tool(
user_id=state.user_id,
tenant_id=state.tenant_id,
tool=definition.name,
arguments=proposal.arguments,
):
return PolicyDecision(
outcome="deny",
reason_code="NOT_AUTHORIZED",
explanation="The caller lacks permission for this resource.",
)if definition.risk in {Risk.EXTERNAL_WRITE, Risk.DESTRUCTIVE}:
return PolicyDecision(
outcome="require_approval",
reason_code="CONSEQUENTIAL_ACTION",
explanation="The exact action must be approved before execution.",
)return PolicyDecision(
outcome="allow",
reason_code="POLICY_ALLOWED",
explanation="The action is permitted within the caller's scope.",
)
Vincule la aprobación a la acción exacta
Para obtener la aprobación de Bind para esta etapa, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Trate esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace las completaciones parciales silenciosas. Autentíquese en la pasarela y vuelva a autorizarse en el plano de datos. Un token portador por sí solo no constituye un límite entre tenencias. Para obtener la aprobación de Bind para esta etapa, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar que los operadores puedan auditar sin necesidad de leer todo el sistema.
import hashlib
import json
def action_digest(state: RunState, proposal: ToolProposal) -> str:
value = {
"user_id": state.user_id,
"tenant_id": state.tenant_id,
"tool": proposal.tool,
"arguments": proposal.arguments,
}
canonical = json.dumps(value, sort_keys=True, separators=(",", ":"))
return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
Implementar el bucle controlado
Al trabajar en la fase de implementación del bucle controlado, primero escribe el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación ayuda a mantener honestas las futuras modificaciones del código. Documenta tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Registra el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar bucles sin ese registro desperdicia horas.
async def run_harness(state: RunState, model, approvals, executor):
max_steps = 8
while not state.finished and state.step < max_steps:
state.step += 1context = build_bounded_context(state, TOOLS)
response = await model.next_action(context)if response.final_answer is not None:
state.finished = True
return complete_run(state, response.final_answer)proposal = ToolProposal.model_validate(response.tool_proposal)
decision = authorize(state, proposal)
trace_policy_decision(state, proposal, decision)if decision.outcome == "deny":
state.observations.append(Observation(
tool=proposal.tool,
ok=False,
error_code=decision.reason_code,
))
continueif decision.outcome == "require_approval":
digest = action_digest(state, proposal)
if not approvals.has_valid_approval(digest):
return pause_for_approval(state, proposal, digest)observation = await executor.execute(
definition=TOOLS[proposal.tool],
arguments=proposal.arguments,
identity={
"user_id": state.user_id,
"tenant_id": state.tenant_id,
},
)
state.observations.append(redact_observation(observation))return stop_run(state, reason="STEP_LIMIT_REACHED")
Conectar el modelo a través de un adaptador
Al trabajar en la fase de conectar el modelo, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación ayuda a mantener honestas las futuras modificaciones del código. Prefiera unidades pequeñas y probables sobre scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Almacene en caché las instrucciones del sistema estables y los esquemas de las herramientas. Reenviar un preámbulo idéntico es una causa común de desperdicio de recursos.
class ModelAdapter:
async def next_action(self, context) -> "ModelTurn":
raise NotImplementedError
Exponer una API autenticada
Al trabajar en la fase de “Exponer una API autenticada”, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación ayuda a mantener honestos los cambios posteriores en el código. Considere esta fase como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina comprobaciones de éxito y evite completaciones parciales silenciosas. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar sin ese historial desperdicia horas.
from fastapi import Depends, FastAPI
app = FastAPI()
@app.post("/runs")
async def create_run(request: RunRequest, identity=Depends(require_identity)):
state = RunState(
run_id=new_run_id(),
user_id=identity.user_id,
tenant_id=identity.tenant_id,
goal=request.goal,
)
return await run_harness(state, model, approvals, executor)
@app.post("/runs/{run_id}/approvals")
async def approve_run_action(
run_id: str,
request: ApprovalRequest,
identity=Depends(require_identity),
):
return approve_exact_action(run_id, request.action_digest, identity)
Al trabajar en la etapa de Exponer una API autenticada, primero anote el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación ayuda a mantener honestas las futuras modificaciones del código. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema.
Ejecutar localmente
La etapa de Ejecutar localmente funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son detalles adicionales para pulirlo posteriormente. Ofrezca herramientas con esquemas limitados y etiquetas explícitas sobre efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.
uvicorn app.api:app --host 127.0.0.1 --port 8000 --reload
9. Probar y evaluar el arnés
La etapa 9 de prueba y evaluación funciona mejor cuando se trata como una superficie medible. Capture una transcripción exitosa, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y probables sobre scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad en lugar de a un proceso complicado. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los hosts necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.
Pruebas unitarias e de integración deterministas
La etapa de unidades e integración deterministas funciona mejor cuando se trata como una superficie medible. Capture un registro de referencia ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente. La etapa de unidades e integración deterministas funciona mejor cuando se trata como una superficie medible. Capture un registro de referencia ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema.
def test_external_write_requires_approval():
proposal = ToolProposal(
tool="send_email",
arguments={"to": "customer@example.test", "body": "Reminder"},
reason="Send the approved reminder",
)
decision = authorize(make_finance_run(), proposal)assert decision.outcome == "require_approval"
assert decision.reason_code == "CONSEQUENTIAL_ACTION"
Evaluaciones de modelos y flujos de trabajo
En la fase de evaluaciones de modelos y flujos de trabajo, se deben definir las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Se debe documentar tanto la ruta óptima como la ruta de recuperación. Las intentonas repetidas, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Cuando el siguiente paso sea la ejecución de código o una llamada a una herramienta, es preferible utilizar salidas estructuradas con validación de esquema en lugar de texto libre.
10. Desplegar el conjunto de herramientas a escala empresarial
En la etapa 10 de despliegue, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el error debe indicar una única responsabilidad y no un proceso complicado. Autentique en la pasarela de entrada y vuelva a autorizarlo en el plano de datos. Un token portador por sí solo no constituye un límite entre tenencias.
Topología de producción
En la fase de topología de producción, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Considere esta fase como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Autentíquese en la pasarela y vuelva a autorizarse en el plano de datos. Un token portador por sí solo no constituye un límite entre tenencias.
Client
│
▼
API Gateway / WAF
│ authentication, rate limits, request ID
▼
Harness API
├── Policy Service
├── Approval Service
├── Model Gateway ─────► Model Provider
├── State Store
├── Trace / Audit Pipeline
└── Tool Executor Queue
│
▼
Isolated Workers
├── MCP / SaaS APIs
├── Browser Sandbox
├── Code Sandbox
└── Enterprise Data
En la fase de topología de producción, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos confidenciales y las banderas de funcionalidad deben encontrarse en un lugar que los operadores puedan auditar sin necesidad de leer todo el sistema.
Contenerizar la capa de control
Al trabajar en la etapa de contenerización del plano de control, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documente junto con ello el camino óptimo y el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar agentes en bucles sin esa huella desperdicia horas.
FROM python:3.12-slim
WORKDIR /app
COPY pyproject.toml ./
RUN pip install --no-cache-dir .COPY app ./appRUN useradd --create-home --uid 10001 harness
USER harnessENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1CMD ["uvicorn", "app.api:app", "--host", "0.0.0.0", "--port", "8000"]
Controles de producción
Al trabajar en la fase de controles de producción, anote primero el contrato: los insumos requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Prefiera unidades pequeñas y probables sobre scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar agentes sin esa huella desperdicia horas.
Ruta de desarrollo a producción
Al trabajar en la etapa del camino de desarrollo a producción, anote primero el contrato: los insumos requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Trate esta etapa como un contrato entre los insumos y los resultados validados. Asigne nombres a los artefactos, defina las comprobaciones de éxito y rechace las completaciones parciales silenciosas. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar sin ese rastro desperdicia horas. Al trabajar en la etapa del camino de desarrollo a producción, anote primero el contrato: los insumos requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema.
11. Lista de verificación para la preparación empresarial
La etapa 11 de la lista de verificación para la preparación empresarial funciona mejor cuando se trata como una superficie medible. Capture un registro de ejemplo ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el camino de recuperación. Los intentos repetidos, los controles humanos y el manejo de correos no entregados forman parte del producto, no son mejoras posteriores. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.
Conclusión
La etapa de conclusión funciona mejor cuando se trata como una superficie medible. Capture un registro de ejemplo ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance.