Files
orchestration_engine/orchestration/main.py
Jonathan Boniface 6d32bc696d feat: keep what agents deliver and serve it at signed links (ADR-0004)
The Orchestration engine keeps every completed agent Execution it relays,
by tenant, Customer case and Execution, and serves its record and files at
signed, expiring links. A KAB workflow step, which takes one output per
step, is given one JSON document of links (`deliver: links`); other callers
still get each file, and what they are given is kept either way.

- store.py, links.py, delivery.py, serving.py; the relay keeps and links
- the card declares `deliver`, `sources` and an output schema
- image: STORE_DIR on a /data volume; PUBLIC_URL and LINK_SECRET settings
- option 1's tests replaced by tests of the links document

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-21 20:05:47 +01:00

161 lines
5.3 KiB
Python

"""The Orchestration engine's A2A server: `python -m orchestration.main`."""
from __future__ import annotations
import logging
import secrets
from collections.abc import AsyncIterator, Sequence
from contextlib import asynccontextmanager
import click
import httpx
import uvicorn
from a2a.server.request_handlers.default_request_handler_v2 import (
DefaultRequestHandlerV2,
)
from a2a.server.routes.jsonrpc_routes import create_jsonrpc_routes
from a2a.server.tasks import InMemoryTaskStore
from a2a.utils.constants import AGENT_CARD_WELL_KNOWN_PATH
from starlette.applications import Starlette
from starlette.requests import Request
from starlette.responses import JSONResponse
from starlette.routing import Route
from orchestration.agents import Agent, load_routes
from orchestration.agents import Sequence as AgentSequence
from orchestration.card import A2A_PATH, build_card, card_document
from orchestration.config import OrchestrationSettings
from orchestration.delivery import Delivery
from orchestration.links import Signer
from orchestration.relay import AgentClients, RelayExecutor
from orchestration.serving import kept_routes
from orchestration.store import Store
logger = logging.getLogger(__name__)
LEGACY_CARD_PATH = "/.well-known/agent.json"
def create_app(
agents: Sequence[Agent],
settings: OrchestrationSettings | None = None,
*,
httpx_client: httpx.AsyncClient | None = None,
clients: AgentClients | None = None,
sequences: Sequence[AgentSequence] = (),
store: Store | None = None,
signer: Signer | None = None,
public_url: str | None = None,
) -> Starlette:
"""The server. `httpx_client` is how it reaches the agents; one is made
(and closed) here when none is given. `clients` replaces how agents are
called altogether, for tests. `store`, `signer` and `public_url` replace what
the settings make of them."""
settings = settings or OrchestrationSettings()
delivery = _delivery(settings, store, signer, public_url)
own_client = httpx_client is None
client = httpx_client or httpx.AsyncClient(
timeout=httpx.Timeout(None, connect=settings.CONNECT_TIMEOUT_SECONDS)
)
card = build_card(settings, agents, sequences)
served_card = card_document(card, agents, sequences)
handler = DefaultRequestHandlerV2(
agent_executor=RelayExecutor(
agents,
clients or AgentClients(client),
settings.HEARTBEAT_SECONDS,
sequences,
delivery,
),
task_store=InMemoryTaskStore(),
agent_card=card,
)
async def agent_card(request: Request) -> JSONResponse:
return JSONResponse(served_card)
async def health(request: Request) -> JSONResponse:
return JSONResponse(
{
"status": "healthy",
"agent": settings.AGENT_NAME,
"version": settings.AGENT_VERSION,
"agents": [agent.work for agent in agents],
"sequences": [sequence.work for sequence in sequences],
}
)
@asynccontextmanager
async def lifespan(app: Starlette) -> AsyncIterator[None]:
try:
yield
finally:
await handler.aclose()
if own_client:
await client.aclose()
# The card names /a2a; the root serves the same handler, because the KAB
# platform calls the address an agent was registered with.
jsonrpc = [
route
for path in (A2A_PATH, "/")
for route in create_jsonrpc_routes(handler, path, enable_v0_3_compat=True)
]
return Starlette(
routes=[
Route("/health", health, methods=["GET"]),
Route(AGENT_CARD_WELL_KNOWN_PATH, agent_card, methods=["GET"]),
Route(LEGACY_CARD_PATH, agent_card, methods=["GET"]),
*(kept_routes(delivery) if delivery else []),
*jsonrpc,
],
lifespan=lifespan,
)
def _delivery(
settings: OrchestrationSettings,
store: Store | None,
signer: Signer | None,
public_url: str | None,
) -> Delivery | None:
"""Where what agents deliver is kept, and how it is linked to; None when
nothing is to be kept."""
if store is None and settings.STORE_DIR:
store = Store(settings.STORE_DIR)
if store is None:
return None
if signer is None:
secret = settings.LINK_SECRET
if not secret:
logger.warning(
"LINK_SECRET is not set: links made now stop working on a restart"
)
secret = secrets.token_hex(32)
signer = Signer(secret, settings.LINK_TTL_SECONDS)
base = (
public_url
or settings.PUBLIC_URL
or settings.A2A_PUBLIC_URL
or f"http://{settings.A2A_HOST}:{settings.A2A_PORT}"
)
return Delivery(store, signer, base)
@click.command()
@click.option("--host", default=None, help="Host to bind (default A2A_HOST)")
@click.option("--port", default=None, type=int, help="Port (default A2A_PORT)")
def main(host: str | None, port: int | None) -> None:
settings = OrchestrationSettings()
logging.basicConfig(level=settings.LOG_LEVEL.upper())
agents, sequences = load_routes(settings.AGENTS_FILE)
uvicorn.run(
create_app(agents, settings, sequences=sequences),
host=host or settings.A2A_HOST,
port=port or settings.A2A_PORT,
)
if __name__ == "__main__":
main()