koda-agent-runtime 0.1.0__py3-none-any.whl

koda_agent_runtime/__init__.py

@@ -0,0 +1,76 @@
+"""Runtime común para agentes Koda expuestos por A2A sobre Amazon Bedrock AgentCore.
+
+Cinco piezas reutilizables, todas activables a la carta desde el
+``pyproject.toml`` del agente vía ``extras``:
+
+  * ``headers``     — constantes de custom headers ``Koda-*`` (fuente única).
+  * ``context``     — module-level state donde el middleware guarda bearer+request_id.
+  * ``middleware``  — factory FastAPI que captura los headers y salta ``/ping``.
+  * ``registry``    — helpers HTTP para descubrir agentes/skills, fetch bundle e
+                      invocar peers vía el registry (el broker firma SigV4).
+  * ``config``      — loader/validador de ``agent.yaml``.
+  * ``tools``       — decoradores ``@strands.tools.tool`` que envuelven los helpers.
+  * ``app``         — ``build_agent_app(cfg)`` que ensambla el ASGI completo (Strands+A2A).
+
+Un agente minimalista consume el ``runtime`` extra y llama a las piezas
+individuales; un agente completo consume el ``bootstrap`` extra y su
+``src/agent.py`` baja a ~10 líneas.
+
+Ver ``KODA_AGENT_RUNTIME_ARCHITECTURE.md`` en el monorepo koda-platform
+para el diseño completo y el plan de release.
+"""
+
+from .config import AgentConfig, load_a2a_skills_from_card, load_agent_config
+from .context import get_bearer, get_request_id, set_context
+from .headers import (
+    AGENTCORE_HEADER_PREFIX,
+    ALLOWLISTED_HEADERS,
+    KODA_AGENT_PATH_HEADER,
+    KODA_AUTHZ_HEADER,
+    KODA_CALLER_TYPE_HEADER,
+    KODA_CHAIN_DEPTH_HEADER,
+    KODA_EMAIL_HEADER,
+    KODA_REQUEST_ID_HEADER,
+    KODA_ROLES_HEADER,
+    KODA_SUB_HEADER,
+)
+from .middleware import koda_headers_middleware
+from .registry import (
+    RegistryError,
+    discover_agents,
+    discover_skills,
+    fetch_skill_bundle,
+    invoke_peer,
+)
+from .tools import build_tools
+
+__all__ = [
+    "AGENTCORE_HEADER_PREFIX",
+    "ALLOWLISTED_HEADERS",
+    "AgentConfig",
+    "KODA_AGENT_PATH_HEADER",
+    "KODA_AUTHZ_HEADER",
+    "KODA_CALLER_TYPE_HEADER",
+    "KODA_CHAIN_DEPTH_HEADER",
+    "KODA_EMAIL_HEADER",
+    "KODA_REQUEST_ID_HEADER",
+    "KODA_ROLES_HEADER",
+    "KODA_SUB_HEADER",
+    "RegistryError",
+    "build_tools",
+    "discover_agents",
+    "discover_skills",
+    "fetch_skill_bundle",
+    "get_bearer",
+    "get_request_id",
+    "invoke_peer",
+    "koda_headers_middleware",
+    "load_a2a_skills_from_card",
+    "load_agent_config",
+    "set_context",
+]
+
+# `build_agent_app` NO se exporta desde el top-level porque su import
+# desencadena `strands` + `bedrock` (dependencias pesadas del extra
+# `bootstrap`, no del core). Los consumidores lo importan explícito:
+#     from koda_agent_runtime.app import build_agent_app

koda_agent_runtime/app.py

@@ -0,0 +1,150 @@
+"""Bootstrap: construye una app FastAPI + Strands A2A a partir de ``AgentConfig``.
+
+Reduce el `src/agent.py` típico de un agente Koda a ~10 líneas. Ver
+``AGENT_SPEC.md`` en koda-platform y §4.3 de
+``KODA_AGENT_RUNTIME_ARCHITECTURE.md`` para la motivación.
+
+Ejemplo:
+
+    from pathlib import Path
+    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)
+
+Agentes que quieran inyectar tools locales pueden pasarlas con
+``extra_tools=[...]``; agentes con requerimientos más raros pueden
+saltarse este helper y usar directo ``koda_agent_runtime.middleware`` y
+``koda_agent_runtime.tools``.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI
+
+from .config import AgentConfig, load_a2a_skills_from_card
+from .middleware import koda_headers_middleware
+from .tools import build_tools
+
+logger = logging.getLogger(__name__)
+
+
+def build_agent_app(
+    cfg: AgentConfig,
+    *,
+    base_dir: Path,
+    extra_tools: list[Any] | None = None,
+) -> FastAPI:
+    """Ensambla un ASGI app completo para un agente Koda.
+
+    Args:
+        cfg: Config parseada del ``agent.yaml``.
+        base_dir: Directorio raíz del agente (donde viven ``prompts/`` y
+            ``a2a/``). Normalmente ``Path(__file__).resolve().parent.parent``
+            desde ``src/agent.py``.
+        extra_tools: Herramientas locales del agente que no están en el
+            catálogo compartido. Se anexan a las declaradas en
+            ``agent.yaml.tools``.
+    """
+    # Imports lazy: Strands/Bedrock son pesados y no todos los consumidores
+    # del paquete necesitan el bootstrap (algunos usan solo runtime/config).
+    from strands import Agent
+    from strands.models import BedrockModel
+    from strands.multiagent.a2a import A2AServer
+
+    prompt_path = base_dir / "prompts" / "system.md"
+    card_path = base_dir / "a2a" / "agent-card.json"
+    for p in (prompt_path, card_path):
+        if not p.exists():
+            raise FileNotFoundError(f"agent bootstrap missing required file: {p}")
+
+    prompt = prompt_path.read_text(encoding="utf-8")
+
+    # Origen de las skills (flag KODA_SKILLS_SOURCE, ver load_skills_for_agent):
+    #  - "offline" (default, dev): lee skills/<name>/SKILL.md del disco y las
+    #    inyecta al system prompt en arranque. No depende del registry.
+    #  - "registry": NO inyecta en arranque; el agente resuelve skills en runtime
+    #    con la tool `fetch_registry_skill` (necesita el JWT por-request).
+    skills_text = load_skills_for_agent(base_dir)
+    if skills_text:
+        prompt = f"{prompt}\n\n{skills_text}"
+        logger.info("skills offline cargadas en el prompt (%d chars)", len(skills_text))
+
+    tools = build_tools(cfg) + list(extra_tools or [])
+
+    agent = Agent(
+        model=BedrockModel(**cfg.model_kwargs()),
+        system_prompt=prompt,
+        tools=tools,
+        name=cfg.name,
+        description=cfg.description,
+    )
+
+    a2a_server = A2AServer(
+        agent=agent,
+        http_url=cfg.runtime_url(),
+        serve_at_root=True,
+        version=cfg.version,
+        skills=load_a2a_skills_from_card(card_path),
+    )
+
+    app = FastAPI()
+    koda_headers_middleware(app)
+    app.mount("/", a2a_server.to_fastapi_app())
+
+    logger.info(
+        "agent app built: name=%s version=%s tools=%d peers=%d",
+        cfg.name,
+        cfg.version,
+        len(tools),
+        len(cfg.peers),
+    )
+    return app
+
+
+def load_skills_for_agent(base_dir: Path) -> str:
+    """Resuelve las skills del agente según el flag ``KODA_SKILLS_SOURCE``.
+
+    - ``offline`` (default): lee ``skills/<name>/SKILL.md`` del disco y devuelve
+      un bloque para anexar al system prompt. Ideal para desarrollo — sin
+      registry, sin bearer.
+    - ``registry``: devuelve cadena vacía; en este modo las skills se resuelven
+      en runtime con la tool ``fetch_registry_skill`` (que necesita el JWT del
+      caller por-request). No se inyectan en el arranque.
+
+    Nombres de skill: ``koda-skill-<fase>-<target>``.
+    """
+    source = os.environ.get("KODA_SKILLS_SOURCE", "offline").strip().lower()
+    if source == "registry":
+        logger.info("KODA_SKILLS_SOURCE=registry: skills vía fetch_registry_skill en runtime")
+        return ""
+    if source != "offline":
+        logger.warning("KODA_SKILLS_SOURCE=%r no reconocido; usando 'offline'", source)
+
+    skills_dir = base_dir / "skills"
+    if not skills_dir.is_dir():
+        return ""
+    parts: list[str] = []
+    for skill_md in sorted(skills_dir.glob("*/SKILL.md")):
+        try:
+            content = skill_md.read_text(encoding="utf-8").strip()
+        except OSError as exc:
+            logger.warning("no pude leer skill %s: %s", skill_md, exc)
+            continue
+        if content:
+            parts.append(content)
+    if not parts:
+        return ""
+    joined = "\n\n---\n\n".join(parts)
+    return (
+        "# Skill(s) aplicables (cargadas localmente, modo offline)\n\n"
+        "Sigue estas guías al pie de la letra para tu fase. No necesitas "
+        "buscar skills en el registry: ya están aquí.\n\n"
+        f"{joined}"
+    )

koda_agent_runtime/config.py

@@ -0,0 +1,139 @@
+"""Carga y valida ``agent.yaml`` — la declaración de identidad y capacidades del agente.
+
+`agent.yaml` es la fuente de verdad para: nombre, versión, modelo Bedrock,
+tools a activar, peers permitidos, URL del registry, y datos de deploy.
+Ver ``AGENT_SPEC.md`` en la raíz del monorepo para el shape completo.
+
+El schema se valida "a mano" con checks simples en vez de depender de
+pydantic — mantenerlo sin dependencias extra facilita reusarlo en scripts
+de deploy fuera del container.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+@dataclass
+class Peer:
+    path: str
+    role: str
+    description: str = ""
+
+
+@dataclass
+class ModelConfig:
+    provider: str = "bedrock"
+    model_id: str = "us.amazon.nova-lite-v1:0"
+    temperature: float = 0.4
+    max_tokens: int = 4000
+
+
+@dataclass
+class AgentConfig:
+    name: str
+    version: str
+    description: str
+    model: ModelConfig
+    tools: list[str] = field(default_factory=list)
+    peers: list[Peer] = field(default_factory=list)
+    registry_url: str = ""
+    deploy_region: str = ""
+    deploy_account: str | None = None
+    runtime_name: str = ""
+
+    def model_kwargs(self) -> dict[str, Any]:
+        """Args para pasar a ``strands.models.BedrockModel(**...)``."""
+        return {
+            "model_id": self.model.model_id,
+            "temperature": self.model.temperature,
+            "max_tokens": self.model.max_tokens,
+        }
+
+    def runtime_url(self) -> str:
+        """URL A2A local — AgentCore le pasa este valor al AgentCard cuando corre."""
+        # AgentCore inyecta AGENTCORE_RUNTIME_URL en producción; el default cubre
+        # el uvicorn local para pruebas.
+        return os.environ.get("AGENTCORE_RUNTIME_URL", "http://127.0.0.1:9000/")
+
+    def a2a_skills(self) -> list[Any]:
+        """AgentSkill A2A objects construidos desde ``a2a/agent-card.json``.
+
+        `agent.yaml` intencionalmente no duplica lo que ya está en el
+        AgentCard (los skills declarados al registry). Los agentes que
+        quieran exponer skills A2A a nivel del runtime pueden leerlos
+        desde ``a2a/agent-card.json`` (ver ``load_a2a_skills_from_card``
+        más abajo). Devolvemos lista vacía por defecto para agentes sin
+        skills A2A declaradas.
+        """
+        return []
+
+
+def load_agent_config(yaml_path: Path) -> AgentConfig:
+    """Lee ``agent.yaml`` y devuelve un ``AgentConfig`` validado."""
+    if not yaml_path.exists():
+        raise FileNotFoundError(f"agent.yaml not found at {yaml_path}")
+    data = yaml.safe_load(yaml_path.read_text(encoding="utf-8")) or {}
+
+    for k in ("name", "version", "description"):
+        if not data.get(k):
+            raise ValueError(f"agent.yaml missing required field: {k!r}")
+
+    model_data = data.get("model") or {}
+    model = ModelConfig(
+        provider=model_data.get("provider", "bedrock"),
+        model_id=model_data.get("model_id", ModelConfig.model_id),
+        temperature=float(model_data.get("temperature", ModelConfig.temperature)),
+        max_tokens=int(model_data.get("max_tokens", ModelConfig.max_tokens)),
+    )
+
+    peers = [
+        Peer(path=p["path"], role=p.get("role", ""), description=p.get("description", ""))
+        for p in (data.get("peers") or [])
+    ]
+
+    reg = data.get("registry") or {}
+    dep = data.get("deploy") or {}
+    # Config de entorno: env var tiene precedencia sobre el yaml (que queda solo
+    # por retrocompat). Nada quemado en el código — sin env ni yaml, queda vacío.
+    registry_url = os.environ.get("KODA_REGISTRY_URL") or reg.get("url", "")
+    deploy_region = (
+        os.environ.get("KODA_TARGET_DEPLOY_REGION")
+        or os.environ.get("AWS_REGION")
+        or dep.get("region", "")
+    )
+    return AgentConfig(
+        name=data["name"],
+        version=str(data["version"]),
+        description=data["description"].strip(),
+        model=model,
+        tools=list(data.get("tools") or []),
+        peers=peers,
+        registry_url=registry_url,
+        deploy_region=deploy_region,
+        deploy_account=os.environ.get("KODA_AWS_ACCOUNT") or dep.get("account"),
+        runtime_name=dep.get("runtime_name", data["name"].replace("-", "_")),
+    )
+
+
+def load_a2a_skills_from_card(card_path: Path) -> list[Any]:
+    """Deriva ``AgentSkill`` A2A objects desde ``a2a/agent-card.json``."""
+    import json
+
+    from a2a.types import AgentSkill
+
+    card = json.loads(card_path.read_text(encoding="utf-8"))
+    return [
+        AgentSkill(
+            id=s["id"],
+            name=s["name"],
+            description=s["description"],
+            tags=s.get("tags", []),
+        )
+        for s in card.get("skills", [])
+    ]

koda_agent_runtime/context.py

@@ -0,0 +1,43 @@
+"""Module-level state que preserva la identidad Koda entre middleware y tools.
+
+**Por qué no ContextVar:** Strands ejecuta callbacks de tools en un thread
+pool distinto al que atendió la request HTTP. `contextvars.ContextVar`
+NO se propaga entre threads; el bearer aparece vacío cuando la tool corre.
+Un dict de módulo (mutación protegida por el GIL) es la solución más
+simple que sí cruza threads.
+
+**Por qué no es un problema de concurrencia:** AgentCore levanta UN
+proceso por container y multiplexa requests con FastAPI/asyncio. Un
+único cliente activo por request cabe en el modelo actual (payloads
+JSON-RPC serializados por Strands). Si en el futuro se sirven varias
+sesiones concurrentes en el mismo container habrá que mover a
+``threading.local`` o pasar el bearer explícito por argumento — pero
+para el patrón "AgentCore invoca → agente responde → sale" del broker
+async esto es suficiente y mantiene el código legible.
+"""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+_state: dict[str, str] = {"bearer": "", "request_id": ""}
+
+
+def set_context(bearer: str, request_id: str = "") -> None:
+    _state["bearer"] = bearer or ""
+    _state["request_id"] = request_id or ""
+    logger.info(
+        "koda context set: bearer_len=%d request_id=%s",
+        len(_state["bearer"]),
+        _state["request_id"] or "<none>",
+    )
+
+
+def get_bearer() -> str:
+    return _state.get("bearer", "")
+
+
+def get_request_id() -> str:
+    return _state.get("request_id", "")

koda_agent_runtime/headers.py

@@ -0,0 +1,42 @@
+"""Custom headers Koda-* inyectados por koda-proxy al invocar un runtime.
+
+AgentCore Runtime SOLO forwardea request headers cuyo nombre empieza con
+``X-Amzn-Bedrock-AgentCore-Runtime-Custom-``. koda-proxy inyecta ocho headers
+bajo ese prefijo con la información de identidad del usuario original, el
+service-token vigente (Okta o self-signed 8h) y datos de trace/loop-detect.
+
+Las constantes viven aquí para que exista **una sola fuente de verdad** entre
+el paquete común y cualquier agente que quiera leerlas directamente. En la
+mayoría de los casos, el middleware de este paquete y el `_state` dict del
+módulo ``context`` cubren todo el uso; los agentes rara vez importan estas
+constantes de forma directa.
+"""
+
+from __future__ import annotations
+
+# AgentCore prefix, ya en lowercase — todos los headers entrantes se
+# normalizan a lowercase en el middleware antes de compararse.
+AGENTCORE_HEADER_PREFIX = "x-amzn-bedrock-agentcore-runtime-custom-"
+
+KODA_AUTHZ_HEADER = AGENTCORE_HEADER_PREFIX + "koda-authorization"
+KODA_REQUEST_ID_HEADER = AGENTCORE_HEADER_PREFIX + "koda-request-id"
+KODA_SUB_HEADER = AGENTCORE_HEADER_PREFIX + "koda-sub"
+KODA_EMAIL_HEADER = AGENTCORE_HEADER_PREFIX + "koda-email"
+KODA_ROLES_HEADER = AGENTCORE_HEADER_PREFIX + "koda-roles"
+KODA_CHAIN_DEPTH_HEADER = AGENTCORE_HEADER_PREFIX + "koda-chain-depth"
+KODA_AGENT_PATH_HEADER = AGENTCORE_HEADER_PREFIX + "koda-agent-path"
+KODA_CALLER_TYPE_HEADER = AGENTCORE_HEADER_PREFIX + "koda-caller-type"
+
+# Lista literal que se copia en el `request_header_configuration` del CDK
+# stack del agente (o en `agentcore configure --allowlisted-headers-file`).
+# Un allowlist incompleto = identidad vacía en el agente destino.
+ALLOWLISTED_HEADERS: tuple[str, ...] = (
+    "X-Amzn-Bedrock-AgentCore-Runtime-Custom-Koda-Authorization",
+    "X-Amzn-Bedrock-AgentCore-Runtime-Custom-Koda-Sub",
+    "X-Amzn-Bedrock-AgentCore-Runtime-Custom-Koda-Email",
+    "X-Amzn-Bedrock-AgentCore-Runtime-Custom-Koda-Roles",
+    "X-Amzn-Bedrock-AgentCore-Runtime-Custom-Koda-Chain-Depth",
+    "X-Amzn-Bedrock-AgentCore-Runtime-Custom-Koda-Request-Id",
+    "X-Amzn-Bedrock-AgentCore-Runtime-Custom-Koda-Agent-Path",
+    "X-Amzn-Bedrock-AgentCore-Runtime-Custom-Koda-Caller-Type",
+)

koda_agent_runtime/middleware.py

@@ -0,0 +1,51 @@
+"""Middleware FastAPI que captura los headers Koda-* en el state del módulo.
+
+Uso desde `src/agent.py`:
+
+    from fastapi import FastAPI
+    from koda_agent_runtime.middleware import koda_headers_middleware
+
+    app = FastAPI()
+    koda_headers_middleware(app)
+    app.mount("/", a2a_server.to_fastapi_app())
+
+**Regla crítica — no sobreescribir con vacío.** AgentCore golpea ``/ping``
+cada ~2s para health checks; esos requests no traen ``Koda-Authorization``.
+Si el middleware llamara ``set_context("", "")`` en cada request, borraría
+el bearer que otra invocación tenía guardado (los tools de Strands corren
+async, DESPUÉS de que el middleware retorna, así que un ping intermedio
+resetea el state que la tool iba a usar). Solución: sólo llamar
+``set_context()`` cuando hay bearer en la request.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import FastAPI, Request
+
+from .context import set_context
+from .headers import KODA_AUTHZ_HEADER, KODA_REQUEST_ID_HEADER
+
+logger = logging.getLogger(__name__)
+
+
+def koda_headers_middleware(app: FastAPI) -> None:
+    """Registra el middleware que captura headers Koda-* del custom prefix AgentCore.
+
+    Registrar SOLO una vez por app. No es idempotente entre llamadas.
+    """
+
+    @app.middleware("http")
+    async def _capture(request: Request, call_next):
+        headers = {k.lower(): v for k, v in request.headers.items()}
+        bearer = headers.get(KODA_AUTHZ_HEADER, "")
+        rid = headers.get(KODA_REQUEST_ID_HEADER, "")
+        if bearer:
+            logger.info(
+                "middleware saw request: path=%s koda-authz-present=True request-id=%s",
+                request.url.path,
+                rid or "<none>",
+            )
+            set_context(bearer=bearer, request_id=rid)
+        return await call_next(request)

koda_agent_runtime/registry.py

@@ -0,0 +1,185 @@
+"""Cliente HTTP hacia el mcp-gateway-registry.
+
+Cuatro funciones que el agente típico consume:
+
+* ``discover_agents(query)`` — búsqueda semántica de peers registrados.
+* ``discover_skills(query)`` — búsqueda semántica de skills registradas.
+* ``fetch_skill_bundle(skill_path)`` — descarga el markdown de una skill.
+* ``invoke_peer(agent_path, message)`` — delega a un agente peer vía el
+  registry (que firma SigV4 y aplica identity headers).
+
+Todos leen el bearer del module state (`context._state`), que el
+middleware guardó al recibir la request de AgentCore. Ninguno recibe el
+bearer por argumento — evita que el prompt del modelo tenga que
+razonar sobre tokens.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import urllib.error
+import urllib.request
+from typing import Any
+
+from .context import get_bearer, get_request_id
+
+logger = logging.getLogger(__name__)
+
+# Sin default quemado: la URL del registry viene por env (KODA_REGISTRY_URL).
+# Si no está seteada, las llamadas al registry fallan con un error claro en vez
+# de apuntar silenciosamente a una URL hardcodeada.
+_REGISTRY_URL = os.environ.get("KODA_REGISTRY_URL", "")
+
+
+class RegistryError(Exception):
+    """Cualquier fallo hablando con el registry."""
+
+
+def _bearer_headers() -> dict[str, str]:
+    bearer = get_bearer()
+    if not bearer:
+        raise RegistryError("no bearer in context — agent was invoked without Koda-Authorization")
+    h = {"Authorization": f"Bearer {bearer}"}
+    rid = get_request_id()
+    if rid:
+        h["X-Koda-Request-Id"] = rid
+    return h
+
+
+def discover_agents(query: str, max_results: int = 5) -> list[dict[str, Any]]:
+    """Búsqueda semántica de peers A2A. Devuelve lista de dicts con name/path/url/score."""
+    headers = _bearer_headers()
+    headers["Content-Type"] = "application/json"
+    body = json.dumps({"query": query, "max_results": max_results}).encode("utf-8")
+    url = (
+        f"{_REGISTRY_URL.rstrip('/')}/api/agents/discover/semantic"
+        f"?query={urllib.request.quote(query)}&max_results={max_results}"
+    )
+    req = urllib.request.Request(url, data=body, headers=headers, method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        body_txt = exc.read().decode("utf-8", errors="replace")[:200]
+        logger.warning("discover_agents failed: %s %s", exc.code, body_txt)
+        return []
+    except Exception as exc:
+        logger.warning("discover_agents unreachable: %s", exc)
+        return []
+    return data.get("agents", []) if isinstance(data, dict) else []
+
+
+def discover_skills(query: str, max_results: int = 5) -> list[dict[str, Any]]:
+    """Búsqueda semántica de skills.
+
+    Preferido sobre adivinar nombres. La clave ``path`` que devuelve es
+    el mismo string que ``fetch_skill_bundle`` acepta (con o sin
+    ``/skills/`` prefix).
+    """
+    headers = _bearer_headers()
+    headers["Content-Type"] = "application/json"
+    body = json.dumps(
+        {"query": query, "entity_types": ["skill"], "max_results": max_results}
+    ).encode("utf-8")
+    url = f"{_REGISTRY_URL.rstrip('/')}/api/search/semantic"
+    req = urllib.request.Request(url, data=body, headers=headers, method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        body_txt = exc.read().decode("utf-8", errors="replace")[:200]
+        logger.warning("discover_skills failed: %s %s", exc.code, body_txt)
+        return []
+    except Exception as exc:
+        logger.warning("discover_skills unreachable: %s", exc)
+        return []
+    return data.get("skills", []) if isinstance(data, dict) else []
+
+
+def fetch_skill_bundle(skill_path: str) -> dict[str, Any]:
+    """GET /api/skills/<name>/bundle.
+
+    Acepta tanto ``playbook-x`` como ``/skills/playbook-x`` — el prefix
+    se normaliza aquí porque el endpoint del registry sólo entiende el
+    nombre bare.
+    """
+    normalized = skill_path.lstrip("/")
+    if normalized.startswith("skills/"):
+        normalized = normalized[len("skills/") :]
+    url = f"{_REGISTRY_URL.rstrip('/')}/api/skills/{normalized}/bundle"
+    req = urllib.request.Request(url, headers=_bearer_headers(), method="GET")
+    try:
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            payload = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8", errors="replace")[:200]
+        logger.warning(
+            "skill bundle fetch failed: skill=%s status=%s body=%s",
+            skill_path,
+            exc.code,
+            body,
+        )
+        raise RegistryError(f"registry returned {exc.code}: {body}") from exc
+    except Exception as exc:
+        raise RegistryError(f"registry unreachable: {exc}") from exc
+    return payload
+
+
+def invoke_peer(agent_path: str, message: str) -> str:
+    """POST /agents/<path>/invoke — delega a un peer A2A vía el registry.
+
+    El registry firma SigV4 hacia AgentCore, mint (o reuse) el
+    service-token y forwardea la identidad. El agente destino recibe
+    los mismos ``Koda-Sub/Email/Roles`` que llegaron a este agente,
+    con ``Koda-Chain-Depth`` incrementado.
+    """
+    bearer = get_bearer()
+    if not bearer:
+        raise RegistryError("no bearer in context — agent was invoked without a caller JWT")
+    if not agent_path.startswith("/"):
+        agent_path = "/" + agent_path
+
+    rid = get_request_id()
+    envelope = {
+        "jsonrpc": "2.0",
+        "id": "1",
+        "method": "message/send",
+        "params": {
+            "message": {
+                "role": "user",
+                "kind": "message",
+                "messageId": rid or "m1",
+                "parts": [{"kind": "text", "text": message}],
+            }
+        },
+    }
+    body = json.dumps(envelope).encode("utf-8")
+    url = f"{_REGISTRY_URL.rstrip('/')}/agents{agent_path}/invoke"
+    headers = {
+        "Authorization": f"Bearer {bearer}",
+        "Content-Type": "application/json",
+    }
+    if rid:
+        headers["X-Koda-Request-Id"] = rid
+
+    req = urllib.request.Request(url, data=body, headers=headers, method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=120) as resp:
+            payload = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", errors="replace")[:200]
+        raise RegistryError(f"registry returned {exc.code}: {detail}") from exc
+    except Exception as exc:
+        raise RegistryError(f"registry unreachable: {exc}") from exc
+
+    result = payload.get("result") or {}
+    artifacts = result.get("artifacts") or []
+    text_parts = [
+        p.get("text", "")
+        for art in artifacts
+        for p in (art.get("parts") or [])
+        if p.get("kind") == "text"
+    ]
+    return "\n".join(text_parts).strip() or json.dumps(payload)

koda_agent_runtime/tools.py

@@ -0,0 +1,154 @@
+"""Adaptadores ``@strands.tools.tool`` sobre los helpers de ``registry.py``.
+
+Cada helper HTTP se expone al modelo como una tool con docstring en
+español (Strands las usa como descripción). ``build_tools(cfg)`` devuelve
+la lista de tools que el agente eligió en ``agent.yaml.tools``.
+
+Esto centraliza los prompts de tools — todos los agentes ven la misma
+descripción de ``fetch_registry_skill``, ``invoke_agent``, etc., en vez
+de que cada uno duplique la suya.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+from strands.tools import tool
+
+from .registry import (
+    RegistryError,
+    fetch_skill_bundle,
+    invoke_peer,
+)
+from .registry import (
+    discover_agents as _discover_agents,
+)
+from .registry import (
+    discover_skills as _discover_skills,
+)
+
+if TYPE_CHECKING:
+    from .config import AgentConfig
+
+logger = logging.getLogger(__name__)
+
+
+@tool
+def discover_agents(query: str) -> str:
+    """Descubre agentes registrados en el registry por descripción semántica.
+
+    Úsalo cuando necesites encontrar un peer al que delegar y no sepas su
+    ``path`` exacto. Devuelve JSON con lista de candidatos ordenados por
+    relevancia (``name``, ``path``, ``description``, ``relevance_score``).
+
+    Args:
+        query: Lenguaje natural describiendo la capacidad buscada.
+    """
+    try:
+        agents = _discover_agents(query, max_results=5)
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("discover_agents error: %s", exc)
+        return "(no fue posible consultar el registro de agentes)"
+
+    if not agents:
+        return "(sin candidatos en el registro)"
+
+    summary = [
+        {
+            "name": a.get("name"),
+            "path": a.get("path"),
+            "url": a.get("url"),
+            "description": (a.get("description") or "")[:200],
+            "relevance_score": a.get("relevance_score"),
+        }
+        for a in agents
+    ]
+    return json.dumps(summary, ensure_ascii=False)
+
+
+@tool
+def discover_skills(query: str) -> str:
+    """Busca skills (playbooks) por descripción semántica en el registry.
+
+    Úsalo ANTES de ``fetch_registry_skill`` para encontrar el ``path``
+    correcto — no adivines nombres.
+
+    Args:
+        query: Lenguaje natural — qué playbook o guía necesitas.
+    """
+    try:
+        skills = _discover_skills(query, max_results=5)
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("discover_skills error: %s", exc)
+        return "(no fue posible consultar el registro de skills)"
+
+    if not skills:
+        return "(sin candidatos en el registro)"
+
+    summary = [
+        {
+            "name": s.get("name"),
+            "path": s.get("path"),
+            "description": (s.get("description") or "")[:200],
+            "relevance_score": s.get("relevance_score"),
+        }
+        for s in skills
+    ]
+    return json.dumps(summary, ensure_ascii=False)
+
+
+@tool
+def fetch_registry_skill(skill_path: str) -> str:
+    """Descarga el markdown completo de una skill (playbook) del registry.
+
+    Args:
+        skill_path: ``path`` de la skill tal como lo devolvió
+            ``discover_skills`` (con o sin prefix ``/skills/``).
+    """
+    try:
+        bundle = fetch_skill_bundle(skill_path)
+        return bundle.get("content") or "(skill encontrada pero sin contenido)"
+    except RegistryError as exc:
+        logger.warning("fetch_registry_skill failed: %s", exc)
+        return f"(skill no disponible: {exc})"
+
+
+@tool
+def invoke_agent(agent_path: str, message: str) -> str:
+    """Delega la ejecución a un agente peer registrado vía el registry.
+
+    El registry firma SigV4 hacia el runtime del peer y forwardea la
+    identidad del usuario original. Úsalo después de ``discover_agents``
+    o cuando tu ``agent.yaml`` ya defina el path del peer.
+
+    Args:
+        agent_path: Path del peer en el registry (e.g. ``/agent-developer``).
+        message: Texto a enviar al peer.
+    """
+    try:
+        return invoke_peer(agent_path, message)
+    except RegistryError as exc:
+        logger.warning("invoke_agent failed: %s", exc)
+        return f"(no fue posible invocar al agente: {exc})"
+
+
+_TOOL_REGISTRY: dict[str, Callable[..., Any]] = {
+    "discover_agents": discover_agents,
+    "discover_skills": discover_skills,
+    "fetch_registry_skill": fetch_registry_skill,
+    "invoke_agent": invoke_agent,
+}
+
+
+def build_tools(cfg: AgentConfig) -> list[Any]:
+    """Selecciona del registro las tools que el agente declaró en ``agent.yaml``."""
+    unknown = [t for t in cfg.tools if t not in _TOOL_REGISTRY]
+    if unknown:
+        raise ValueError(
+            f"agent.yaml declares unknown tools: {unknown}. "
+            f"Available: {sorted(_TOOL_REGISTRY.keys())}"
+        )
+    return [_TOOL_REGISTRY[name] for name in cfg.tools]

koda_agent_runtime-0.1.0.dist-info/METADATA

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: koda-agent-runtime
+Version: 0.1.0
+Summary: Reusable runtime, config loader and bootstrap for KODA-ecosystem A2A agents on Amazon Bedrock AgentCore.
+Project-URL: Homepage, https://bitbucket.org/kushki/koda-agent-runtime
+Project-URL: Repository, https://bitbucket.org/kushki/koda-agent-runtime
+Author: Kushki
+License-Expression: MIT
+License-File: LICENSE
+Keywords: a2a,agent,agentcore,bedrock,koda,strands
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: bootstrap
+Requires-Dist: bedrock-agentcore>=0.1.0; extra == 'bootstrap'
+Requires-Dist: boto3>=1.35.0; extra == 'bootstrap'
+Requires-Dist: strands-agents[a2a]>=0.1.0; extra == 'bootstrap'
+Requires-Dist: uvicorn>=0.30.0; extra == 'bootstrap'
+Provides-Extra: cdk
+Requires-Dist: aws-cdk-aws-bedrock-agentcore-alpha; extra == 'cdk'
+Requires-Dist: aws-cdk-lib>=2.150.0; extra == 'cdk'
+Requires-Dist: constructs>=10.0.0; extra == 'cdk'
+Description-Content-Type: text/markdown
+
+# 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:
+
+```toml
+# El mínimo — headers, middleware, registry client, config loader.
+"koda-agent-runtime>=0.1.0a0"
+
+# El agente típico — ademas Strands + A2A + Bedrock para build_agent_app.
+"koda-agent-runtime[bootstrap]>=0.1.0a0"
+
+# El stack CDK del agente — Construct KodaAgentRuntime.
+"koda-agent-runtime[cdk]>=0.1.0a0"
+```
+
+## Uso — un agente en 10 líneas
+
+`src/agent.py`:
+
+```python
+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`:
+
+```yaml
+name: koda-agent-example
+version: 0.1.0
+description: |
+  Un agente de ejemplo.
+
+model:
+  provider: bedrock
+  model_id: us.amazon.nova-lite-v1:0
+  temperature: 0.3
+  max_tokens: 4000
+
+tools:
+  - discover_skills
+  - fetch_registry_skill
+  - invoke_agent
+```
+
+## Módulos
+
+| Módulo | Responsabilidad |
+|---|---|
+| `koda_agent_runtime.headers` | Constantes `KODA_*_HEADER` + `ALLOWLISTED_HEADERS` (para `agentcore configure --request-header-allowlist`). |
+| `koda_agent_runtime.context` | Module-level `_state` con `bearer` y `request_id`; `set_context`, `get_bearer`, `get_request_id`. |
+| `koda_agent_runtime.middleware` | `koda_headers_middleware(app)` — captura los headers Koda-* que koda-proxy inyecta al invocar el runtime. Salta `/ping` para no borrar el state con health probes. |
+| `koda_agent_runtime.registry` | `discover_agents`, `discover_skills`, `fetch_skill_bundle`, `invoke_peer` — hablan con el registry usando el bearer del state. |
+| `koda_agent_runtime.tools` | Decoradores `@strands.tools.tool` sobre los helpers de `registry`. `build_tools(cfg)` filtra por lo declarado en `agent.yaml.tools`. |
+| `koda_agent_runtime.config` | `load_agent_config(path)` → dataclass tipado `AgentConfig`. |
+| `koda_agent_runtime.app` | `build_agent_app(cfg, base_dir)` → `FastAPI` con Strands `Agent` + `A2AServer` + middleware montados. Requiere `[bootstrap]` extra. |
+
+## 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-`.
+
+| Header | Contenido | Estable en cadenas A→B→C |
+|---|---|---|
+| `Koda-Authorization` | Bearer JWT vigente (Okta o self-signed 8h). | No — se refresca cuando expira. |
+| `Koda-Sub` | Usuario humano original. | Sí. |
+| `Koda-Email` | Email del usuario. | Sí. |
+| `Koda-Roles` | Groups Okta del usuario. | Sí. |
+| `Koda-Chain-Depth` | Hops desde el usuario. | +1 por hop. |
+| `Koda-Request-Id` | uuid para trace end-to-end. | Sí. |
+| `Koda-Agent-Path` | Path del agente que recibe. | N/A. |
+| `Koda-Caller-Type` | `user` \| `agent`. | Depende del hop. |
+
+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
+
+```bash
+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.

koda_agent_runtime-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+koda_agent_runtime/__init__.py,sha256=aKoEupSpEhW7jw271Abae0-XuZzLXrQGE7h7xiW0IVY,2645
+koda_agent_runtime/app.py,sha256=O9LAkqetgIwvQEr5RIpRZGPwxMhoZT9vMHJABysjwRU,5316
+koda_agent_runtime/config.py,sha256=zRKpaGoB6-eB8CWyyGEuX4Hck2sypfcE7YkIYtDst08,4743
+koda_agent_runtime/context.py,sha256=oMXwh7hrCP16-maqGigLDeLMYMTQrbIX_Q5lqbpNFhE,1531
+koda_agent_runtime/headers.py,sha256=ikk46_aKG_aRRFKv8InhXF0RTlZGR_of8TJCw_OkO0w,2232
+koda_agent_runtime/middleware.py,sha256=y__HWH-o9f_sBrFoADd4taBVAAO_6q-0QBP225_MCw8,1822
+koda_agent_runtime/registry.py,sha256=G1Hy5jB0j9qRLxzLJ0v4V_LKP-hQNKLzBMrOYCPqwDA,7066
+koda_agent_runtime/tools.py,sha256=BTetRhyjfzA6hsxeHqjG_42qTEeBW4LONg8lsB_tnKM,4862
+koda_agent_runtime-0.1.0.dist-info/METADATA,sha256=SvfgrK-fDp-hKbxBmog5i8deQTTg1bFzRIdxxyBquog,5956
+koda_agent_runtime-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+koda_agent_runtime-0.1.0.dist-info/licenses/LICENSE,sha256=-zqSdvirucW7JLKAsKp4egqVDzNOE7tt9TRaUpHR5PA,1063
+koda_agent_runtime-0.1.0.dist-info/RECORD,,

koda_agent_runtime-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

koda_agent_runtime-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kushki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.