Runtime de agentes

Rol y contrato HTTP#

El backend llama al runtime por HTTP con una tarea, el perfil del agente y el contexto que armó. El runtime devuelve una salida estructurada validada y, si el agente quiere actuar, una lista de tool_requests. Nunca ejecuta una herramienta ni llama a un sistema externo: el modelo puede ser engañado por texto no confiable, pero solo puede proponer.

Cuando RUNTIME_TOKEN está definido, el runtime exige Authorization: Bearer <token> en todas las rutas salvo GET /healthz, comparado en tiempo constante; sin él responde 401. Los endpoints son:

curl http://localhost:8000/healthz
# {"status":"ok","mode":"live","provider":"anthropic",
#  "configured_providers":["anthropic","custom"],"default_provider":"anthropic"}

Simulación y modo real#

El contrato HTTP es el mismo en ambos modos; solo cambia el motor.

• Simulación: se activa con SIMULATION=true o cuando no hay ningún proveedor configurado. Devuelve planes, resultados, tokens y costos plausibles con latencia simulada (SIM_LATENCY_SCALE=0 elimina la espera), sin red ni costo, e ignora la política de proveedores porque ningún dato sale del proceso.
• Real: el motor CrewAI llama al proveedor y valida la salida contra el esquema StructuredOutput. LLM_DIRECT_CALL=true cambia el bucle de CrewAI por una sola llamada de chat.
• Degradado: si hay un proveedor configurado pero el motor real no arranca, el runtime responde en simulación y GET /healthz devuelve status: degraded con un warning.

Proveedores de modelo#

Hay cinco proveedores. Uno queda configurado cuando su clave está en el entorno (para custom basta la URL base) o cuando la solicitud trae la clave propia de la organización. Un modelo custom se pasa como openai/<nombre>, y un modelo local sin costo puede tarificarse en 0 con CUSTOM_PRICE_IN_PER_M y CUSTOM_PRICE_OUT_PER_M.

Las organizaciones pueden traer su propia clave. Se sella con AES-256-GCM bajo una clave envuelta por CONNECTIONS_KEK, ninguna respuesta de la API la devuelve salvo sus últimos cuatro caracteres (key_last4) y solo viaja en claro por el salto interno del backend al runtime.

Orden de proveedores y respaldo#

Para cada llamada el runtime arma una lista de intentos. Cada fuente agrega solo los proveedores que aún no están, así que todo proveedor configurado y permitido acaba siendo un respaldo:

• MODEL_PROVIDER_ORDER_<ROL>: el role del agente en mayúsculas (por ejemplo MODEL_PROVIDER_ORDER_LEGAL) o el tipo de llamada: PLAN, REVIEW, CONSULT, SYNTHESIZE, SUMMARIZE, ROUTE, COUNTERARGUMENT.
• role_providers de la política de modelos de la organización.
• preferred_providers de la solicitud.
• El orden global MODEL_PROVIDER_ORDER (por defecto deepseek,anthropic,openai,kimi,custom).

# Runtime (agent-runtime)
SIMULATION=false                 # true: scripted engine, no network, no cost
DEEPSEEK_API_KEY=...             # one configured provider is enough
ANTHROPIC_API_KEY=...
CUSTOM_LLM_BASE_URL=https://llm.internal.example/v1   # OpenAI-compatible
MODEL_PROVIDER_ORDER=anthropic,deepseek,custom
MODEL_PROVIDER_ORDER_LEGAL=anthropic                  # per role / call kind
ALLOWED_PROVIDERS=anthropic,custom                    # operator ceiling
RUNTIME_TOKEN=<shared secret>    # same value in the backend

# Backend
RUNTIME_URL=http://agent-runtime:8000
RUNTIME_TOKEN=<shared secret>
BUDGET_USD=50                    # organization budget (default 50)
REQUEST_BUDGET_CAP_USD=5         # default cap per request
AGENT_BUDGET_USD=20              # default monthly cap per agent

Política de datos: ALLOWED_PROVIDERS#

La política de datos se aplica antes de enviar nada. La lista efectiva es ALLOWED_PROVIDERS del operador intersectado con allowed_providers de la solicitud: un proveedor fuera de la lista ni se llama ni se usa como respaldo, y una solicitud puede reducir el techo del operador pero nunca ampliarlo.

El backend completa allowed_providers desde la política de modelos de cada organización (GET/PUT /api/v1/settings/model-policy, solo owner y admin, y cada cambio queda auditado). Si no queda ningún proveedor permitido envía el valor centinela none, así que el runtime rechaza la llamada en lugar de ampliar el conjunto. Con byo_only, solo las claves propias de la organización pueden contestar. Los fallos son explícitos:

{
  "detail": {
    "code": "no_allowed_provider",
    "message": "No allowed model provider is configured for this request; nothing was sent.",
    "providers_tried": [],
    "allowed_providers": ["anthropic"],
    "configured_providers": ["deepseek"]
  }
}

Qué sale del proceso y redacción#

A un proveedor solo llegan los prompts de cada llamada. El contrato no tiene campos para credenciales, connection_id, URLs de API ni tokens, así que no pueden enviarse. Un prompt puede contener:

• El texto de la solicitud del usuario y la persona, responsabilidades y herramientas del agente.
• Salidas de tareas dependientes, memoria del agente y contenido externo.
• Resultados de herramientas que el backend ya filtró y redactó.
• Preguntas de consulta o de síntesis.

Herramientas: el modelo pide, el backend ejecuta#

Una solicitud de herramienta es una propuesta. El backend revisa la lista de herramientas del agente, los argumentos, el motor de políticas y el nivel de autonomía, y puede crear una aprobación para una persona. Solo entonces la ejecuta, con credenciales de la bóveda cifrada que nunca salen del backend. El resultado vuelve al modelo redactado y delimitado como datos no confiables.

Las capacidades marcadas como irreversibles en el manifiesto del proveedor, como email.send de Gmail, siempre requieren una decisión humana, sea cual sea la autonomía del agente. Una acción aprobada se reclama como máximo una vez, así que un reinicio no puede ejecutarla dos veces. Las herramientas sin conexión real usan adaptadores falsos en memoria, que es como funciona la simulación de punta a punta.

{
  "tool_requests": [
    { "tool": "email", "action": "send", "risk": "high",
      "args": { "to": "customer@example.com", "subject": "Proposal", "body": "..." } }
  ]
}

Sandbox de código#

La acción code.run permite que un agente pida ejecutar Python. Solo está disponible si el backend tiene SANDBOX_URL y SANDBOX_TOKEN; sin ellos se deniega con sandbox_unavailable. Por defecto cada ejecución es una aprobación que muestra el código, los archivos de entrada y el propósito, y queda ligada al hash del código y al SHA-256 de cada entrada: cambiar cualquiera exige una aprobación nueva.

Tras la aprobación el backend envía la ejecución a un runner aparte que inicia un contenedor desechable:

• Sin red (--network none), raíz de solo lectura, usuario no root y todas las capabilities eliminadas.
• Límites de tiempo, memoria, procesos y tamaño de salida (SANDBOX_MAX_RUNTIME_SECONDS, SANDBOX_MEMORY_MB, SANDBOX_PIDS, SANDBOX_MAX_OUTPUT_BYTES) y una lista de tipos de archivo de salida permitidos.
• El entorno del runner no se reenvía, así que ningún secreto llega al código.
• El kill switch, la pausa del agente o el modo de solo lectura abortan una ejecución en curso.

Contabilidad de costos y presupuestos#

Los precios viven en una sola tabla, model_prices.json, en USD por millón de tokens, idéntica byte a byte en el backend y en el runtime (una prueba en cada servicio lo exige). Un modelo ausente se cobra a la tarifa por defecto de la tabla y se avisa una vez en el log. PRICE_IN_PER_M y PRICE_OUT_PER_M fuerzan una tarifa para todos los modelos.

Antes de cada llamada el backend reserva la estimación máxima contra la solicitud, el agente y la organización. Después registra el mayor entre el costo que reporta el runtime y su propio recálculo, así que no depende de la exactitud del runtime. El gasto se lee de un ledger en Postgres y sobrevive a reinicios.