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>
This commit is contained in:
2026-10-21 20:05:47 +01:00
parent ce5e2f20cd
commit 6d32bc696d
17 changed files with 1235 additions and 205 deletions

View File

@@ -3,6 +3,7 @@
from __future__ import annotations
import logging
import secrets
from collections.abc import AsyncIterator, Sequence
from contextlib import asynccontextmanager
@@ -24,7 +25,13 @@ 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"
@@ -36,11 +43,16 @@ def create_app(
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."""
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)
@@ -53,6 +65,7 @@ def create_app(
clients or AgentClients(client),
settings.HEARTBEAT_SECONDS,
sequences,
delivery,
),
task_store=InMemoryTaskStore(),
agent_card=card,
@@ -93,12 +106,42 @@ def create_app(
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)")