koda-agent-runtime

Runtime compartido para agentes Koda A2A sobre Amazon Bedrock AgentCore. Extrae en un solo paquete versionado las piezas que cada koda-agent-* repite: constantes de custom headers, middleware FastAPI, cliente HTTP hacia el registry, decoradores de tools, loader del agent.yaml, y un bootstrap build_agent_app(cfg) que ensambla Strands + A2A + FastAPI en una llamada.

Ver KODA_AGENT_RUNTIME_ARCHITECTURE.md en el monorepo koda-platform para el diseño completo, precedente (koda-mcp-access), roadmap y compatibilidad.

Instalación

Elige el extra según lo que consuma el agente:

# El mínimo — headers, middleware, auth, registry client, config loader.
"koda-agent-runtime>=0.2.0,<0.3"

# El agente típico — además Strands + A2A + Bedrock (y AnthropicModel) para
# build_agent_app.
"koda-agent-runtime[bootstrap]>=0.2.0,<0.3"

# El stack CDK del agente — Construct KodaAgentRuntime.
"koda-agent-runtime[cdk]>=0.2.0,<0.3"

Mientras 0.2 está en release candidate (0.2.0rc1), >=0.2.0 no la toma (PEP 440: 0.2.0rc1 < 0.2.0). Para probarla, fija "koda-agent-runtime[bootstrap]>=0.2.0rc1,<0.3": acepta la RC y, cuando salga, toma 0.2.0 sin cambiar el pin. Los agentes que fijan <0.2 no la toman.

0.2 rompe compatibilidad con 0.1.x. El agente ya no recibe ni reenvía bearers: se eliminan get_bearer, set_context, KODA_AUTHZ_HEADER y el header Koda-Authorization del allowlist. La identidad es un CallerContext verificado por request (get_caller()) y las llamadas al registry van firmadas (ver "Auth M2M"). Un agente que se invoca directo por InvokeAgentRuntime, sin identidad, y no llama a nada puede tomar 0.2 con KODA_AGENT_M2M=off.

El extra bootstrap instala strands-agents[a2a,anthropic], de modo que build_agent_app soporta tanto provider: bedrock como provider: anthropic (este último vía AnthropicModel, con ANTHROPIC_API_KEY en el entorno).

Uso — un agente en 10 líneas

src/agent.py:

from pathlib import Path
import uvicorn
from koda_agent_runtime.config import load_agent_config
from koda_agent_runtime.app import build_agent_app

_BASE = Path(__file__).resolve().parent.parent
app = build_agent_app(load_agent_config(_BASE / "agent.yaml"), base_dir=_BASE)

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=9000)

agent.yaml:

name: koda-agent-example
version: 0.1.0
description: |
  Un agente de ejemplo.

model:
  provider: bedrock              # bedrock | anthropic
  model_id: us.amazon.nova-lite-v1:0
  temperature: 0.3               # opcional; OMITIR en modelos que la tienen
                                 # deprecada (Sonnet 5, Opus 4.8) o dan error
  max_tokens: 4000

tools:
  - discover_skills
  - fetch_registry_skill
  - invoke_agent

Módulos

Contrato de headers Koda-*

koda-proxy (broker del registry) inyecta estos custom headers al invocar tu runtime. AgentCore solo forwardea headers con prefix X-Amzn-Bedrock-AgentCore-Runtime-Custom- y que estén en el allowlist del runtime: usa ALLOWLISTED_HEADERS completo (más los extras de tu agente).

Todos los strings viven en koda_agent_runtime.headers como constantes. Nunca los repitas en tu código.

Auth M2M (0.2.0)

Una sola flag, KODA_AGENT_M2M:

Cualquier otro valor de KODA_AGENT_M2M, o on sin las dos variables, falla al arrancar: un typo no puede apagar la seguridad. El valor efectivo se loguea al arrancar. La firma la implementa koda_agent_runtime._vendor.koda_signing (copia de koda-mcp-access 1.8.0); los vectores compartidos están en tests/vectors/.

Para firmar un cliente httpx propio (p. ej. el MCPClient de Strands), construye el AgentM2MAuth dentro de la request, porque captura la delegación y el request_id del caller al construirse:

from koda_agent_runtime.auth import AgentM2MAuth

auth = AgentM2MAuth()  # agent:<KODA_AGENT_NAME>, keyring de KODA_AGENT_M2M_SECRET_ID

Anti-patrones

• No lances threads propios sin el contexto: un threading.Thread pelado no ve el CallerContext. Usa asyncio.to_thread o contextvars.copy_context().run (Strands >= 1.0 ya lo hace con las tools).
• No firmes SigV4 desde el agente para invocar peers. Delega via invoke_peer(<path>, <msg>) — el registry firma por ti.
• No trates un CallerContext vacío como un usuario: con KODA_AGENT_M2M=off (o en /ping) no hay identidad. Para decisiones de seguridad, exige get_caller().verified.

Desarrollo

uv sync --all-extras   # los tests importan strands (extra bootstrap)
uv run pytest
uv run ruff check .
uv build

Release (manual, no hay CI de publicación):

# 1. version en pyproject.toml (p. ej. 0.2.0rc1 / 0.2.0) y uv lock
uv lock
uv run pytest && uv run ruff check .
rm -rf dist && uv build && uvx twine check dist/*
# 2. commit, tag vX.Y.Z y push del branch y del tag
# 3. publicar (el token vive en .pypi-token, que NUNCA se versiona)
uv publish --token "$(cat .pypi-token)" dist/*

Una versión subida a PyPI no se puede reemplazar (solo yank): verifica antes.

Versionado

• v0.x — alpha, breaking changes tolerados. Todos los agentes en migración inicial.
• v1.0.0 — cuando la API sea estable y >=3 agentes la consuman en producción. A partir de acá, SemVer estricto.