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, registry client, config loader.
"koda-agent-runtime>=0.1.2,<0.2"

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

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

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 8 custom headers al invocar tu runtime. AgentCore solo forwardea headers con prefix X-Amzn-Bedrock-AgentCore-Runtime-Custom-.

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

Anti-patrones

• No uses contextvars.ContextVar para propagar el bearer entre middleware y tools: Strands corre tools en threads distintos al request handler; el ContextVar aparece vacío. Usa set_context().
• No firmes SigV4 desde el agente para invocar peers. Delega via invoke_peer(<path>, <msg>) — el registry firma por ti.
• No llames set_context() en el middleware si no hay bearer. Los /ping de AgentCore te borrarían el state que otra request iba a usar.

Desarrollo

uv sync --dev
uv run pytest
uv run ruff check src/
uv build

Release: bump pyproject.toml, tag vX.Y.Z, push tag.

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.