koda-agent-runtime 0.1.0__tar.gz

koda_agent_runtime-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+.eggs/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.tox/
+.coverage
+htmlcov/
+
+# Build artifacts
+build/
+dist/
+*.whl
+*.tar.gz
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/
+*.swp
+
+# uv.lock is tracked (reproducibility). Same convention as koda-mcp-access.

koda_agent_runtime-0.1.0/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.

koda_agent_runtime-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,125 @@
+# 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/pyproject.toml

@@ -0,0 +1,76 @@
+[project]
+name = "koda-agent-runtime"
+version = "0.1.0"
+description = "Reusable runtime, config loader and bootstrap for KODA-ecosystem A2A agents on Amazon Bedrock AgentCore."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Kushki" }]
+keywords = ["a2a", "agentcore", "bedrock", "strands", "koda", "agent"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+# Core deps — lo mínimo para que `runtime` y `config` funcionen (importar
+# headers, middleware, config loader, registry client, tools). Nada de
+# Strands/Bedrock/CDK: esos van en extras.
+dependencies = [
+    "fastapi>=0.110.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+# `bootstrap`: para consumir `build_agent_app`. Requiere Strands + Bedrock
+# runtime + a2a-sdk (los tipos `AgentSkill`). Es lo que la mayoría de los
+# agentes va a instalar en producción.
+bootstrap = [
+    "strands-agents[a2a]>=0.1.0",
+    "bedrock-agentcore>=0.1.0",
+    "boto3>=1.35.0",
+    "uvicorn>=0.30.0",
+]
+
+# `cdk`: para consumir el Construct `KodaAgentRuntime`. Solo relevante en
+# el CDK del agente, no en el runtime.
+cdk = [
+    "aws-cdk-lib>=2.150.0",
+    "aws-cdk.aws-bedrock-agentcore-alpha",
+    "constructs>=10.0.0",
+]
+
+[project.urls]
+Homepage = "https://bitbucket.org/kushki/koda-agent-runtime"
+Repository = "https://bitbucket.org/kushki/koda-agent-runtime"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "ruff>=0.6.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/koda_agent_runtime"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

koda_agent_runtime-0.1.0/src/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-0.1.0/src/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}"
+    )