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

@@ -44,6 +44,7 @@ from google.protobuf import json_format
from orchestration.agents import Agent
from orchestration.agents import Sequence as AgentSequence
from orchestration.delivery import Delivery
from orchestration.routing import WORK, route
logger = logging.getLogger(__name__)
@@ -64,6 +65,14 @@ _CARRIED = ("customer_case", "pre_approved", "request")
# The Orchestration engine's own record that an agent's Execution completed, sent
# with its files to the next agent.
RECORD = "execution.json"
# How a caller is given what agents delivered (ADR-0004): one document of links to
# what was kept, or each file as the agent sent it.
DELIVER, LINKS, FILES = "deliver", "links", "files"
# The one artifact a caller given links receives.
DOCUMENT = "result.json"
# What a KAB workflow step sends with every call, by which it is known: it takes
# one output per step, so it is given links unless it asks otherwise.
_PLATFORM_STEP = ("workflow_id", "step_number")
@dataclass
@@ -71,9 +80,13 @@ class Plan:
"""What one of our tasks runs: the agents, in turn, and the caller's fields."""
steps: tuple[Agent, ...]
fields: dict[str, Any] # the request's metadata, but for `work`
fields: dict[str, Any] # the request's metadata, but for `work` and `deliver`
text: str # the request, as the agents are sent it
other_parts: list[Part] = field(default_factory=list) # data and files sent with it
work: str = "" # the work the caller named, an agent's or a sequence's
deliver: str = FILES
# Each agent that completed, by its work: its Execution, how it ended, links.
results: dict[str, dict[str, Any]] = field(default_factory=dict)
def metadata(self, step: int, sources: Mapping[str, str] | None) -> dict[str, Any]:
"""The metadata for the agent at `step`."""
@@ -87,6 +100,8 @@ class Plan:
sent.update(own)
if sources is not None:
sent["sources"] = dict(sources)
if isinstance(sent.get("sources"), Mapping):
sent["sources"] = _as_files(sent["sources"])
return sent
@@ -130,7 +145,9 @@ class RelayExecutor(AgentExecutor):
clients: AgentClients,
heartbeat_seconds: float,
sequences: Sequence[AgentSequence] = (),
delivery: Delivery | None = None,
) -> None:
self._delivery = delivery
self._agents = list(agents)
self._sequences = list(sequences)
self._clients = clients
@@ -174,7 +191,7 @@ class RelayExecutor(AgentExecutor):
)
)
return
fields = {key: value for key, value in options.items() if key != WORK}
fields = {k: v for k, v in options.items() if k not in (WORK, DELIVER)}
texts = [part.text for part in parts if part.HasField("text")]
# A KAB step sends its fields as metadata and, as the text, all of them
# again as one JSON document. The agents are sent the request as their text.
@@ -183,6 +200,8 @@ class RelayExecutor(AgentExecutor):
fields=fields,
text=str(fields["request"]) if fields.get("request") else "\n".join(texts),
other_parts=[part for part in parts if not part.HasField("text")],
work=str(options.get(WORK) or decision.agents[0].work),
deliver=_deliver(options),
)
await self._run(task_id, plan, 0, self._opening(plan, 0, None), updater)
@@ -257,6 +276,8 @@ class RelayExecutor(AgentExecutor):
heartbeat = asyncio.create_task(self._beat(agent, updater))
relayed: set[str] = set() # artifact ids already passed on
files: dict[str, str] = {} # what it delivered, by name, for the next agent
guide: list[str] = [] # the file it sent as its document, if any
relay_files = plan.deliver == FILES
try:
client = await self._clients.for_agent(agent)
async for event in client.send_message(SendMessageRequest(message=message)):
@@ -264,11 +285,19 @@ class RelayExecutor(AgentExecutor):
if event.HasField("task"):
self._hold(task_id, plan, step, event.task)
for artifact in event.task.artifacts:
await self._artifact(agent, artifact, relayed, files, updater)
await self._artifact(
agent, artifact, relayed, files, guide, updater, relay_files
)
status = event.task.status
elif event.HasField("artifact_update"):
await self._artifact(
agent, event.artifact_update.artifact, relayed, files, updater
agent,
event.artifact_update.artifact,
relayed,
files,
guide,
updater,
relay_files,
)
elif event.HasField("status_update"):
status = event.status_update.status
@@ -282,11 +311,11 @@ class RelayExecutor(AgentExecutor):
return
if status is not None and status.state in _ENDS_A_TURN:
heartbeat.cancel()
waiting = self._waiting.get(task_id)
following = step + 1 < len(plan.steps)
if status.state == TaskState.TASK_STATE_COMPLETED and following:
await self._next(
task_id, plan, step, status, files, waiting, updater
if status.state == TaskState.TASK_STATE_COMPLETED:
waiting = self._waiting.get(task_id)
self._kept(plan, agent, waiting, status, files, guide)
await self._completed(
task_id, plan, step, status, files, updater
)
else:
await self._end_turn(task_id, status, updater)
@@ -325,50 +354,85 @@ class RelayExecutor(AgentExecutor):
finally:
heartbeat.cancel()
async def _next(
def _kept(
self,
plan: Plan,
agent: Agent,
waiting: Waiting | None,
status: TaskStatus,
files: Mapping[str, str],
guide: list[str],
) -> None:
"""Keep what the agent delivered and note it in the plan's results."""
execution_id = waiting.task_id if waiting else ""
ended = _ended(status)
result: dict[str, Any] = {"execution_id": execution_id, "status": ended}
record = (
self._delivery.keep(
plan.fields,
work=agent.work,
execution_id=execution_id or str(uuid.uuid4()),
status=ended,
request=plan.text,
files=files,
guide=guide[0] if guide else None,
)
if self._delivery is not None
else None
)
if record is not None and self._delivery is not None:
result.update(self._delivery.links(record))
else:
result["files"] = {name: None for name in sorted(files)}
plan.results[agent.work] = result
async def _completed(
self,
task_id: str,
plan: Plan,
step: int,
status: TaskStatus,
files: dict[str, str],
waiting: Waiting | None,
updater: TaskUpdater,
) -> None:
"""The agent at `step` completed: start the next with its files, unless it
ended with warnings, when nothing after it starts."""
ended with warnings, when nothing after it starts; or, after the last,
finish."""
agent = plan.steps[step]
parts = list(status.message.parts) if status.HasField("message") else []
said = next(
(data for data in get_data_parts(parts) if isinstance(data, Mapping)), {}
)
if said.get("status", "completed") != "completed":
self._waiting.pop(task_id, None)
ended = _ended(status)
if step + 1 == len(plan.steps):
await self._finish(task_id, plan, parts, ended, updater)
return
if ended != "completed":
not_started = [later.work for later in plan.steps[step + 1 :]]
await updater.complete(
updater.new_agent_message(
[
new_text_part(
f"The {agent.work} agent ended with warnings, so "
f"{', '.join(not_started)} was not started. Settle them "
"and ask again."
),
new_data_part(
{
"status": "stopped",
"after": agent.work,
"not_started": not_started,
}
),
*parts, # what the agent itself said
]
)
await self._finish(
task_id,
plan,
[
new_text_part(
f"The {agent.work} agent ended with warnings, so "
f"{', '.join(not_started)} was not started. Settle them "
"and ask again."
),
new_data_part(
{
"status": "stopped",
"after": agent.work,
"not_started": not_started,
}
),
*parts, # what the agent itself said
],
"stopped",
updater,
not_started,
)
return
record = {
"status": "completed",
"customer_case": plan.fields.get("customer_case"),
"execution_id": waiting.task_id if waiting else None,
"execution_id": plan.results[agent.work]["execution_id"] or None,
"workflow_request": plan.text,
"work": agent.work,
}
@@ -392,6 +456,48 @@ class RelayExecutor(AgentExecutor):
task_id, plan, step + 1, self._opening(plan, step + 1, sources), updater
)
async def _finish(
self,
task_id: str,
plan: Plan,
parts: list[Part],
ended: str,
updater: TaskUpdater,
not_started: list[str] | None = None,
) -> None:
"""Complete our task; a caller given links has one document of them."""
self._waiting.pop(task_id, None)
if plan.deliver == LINKS:
document = self._document(plan, ended, not_started)
await updater.add_artifact(
[new_text_part(json.dumps(document), media_type="application/json")],
name=DOCUMENT,
)
await updater.complete(updater.new_agent_message(parts))
def _document(
self, plan: Plan, ended: str, not_started: list[str] | None
) -> dict[str, Any]:
"""One document of links to what each agent delivered; at its top level,
the last agent's."""
last = list(plan.results.values())[-1] if plan.results else {}
_, case = Delivery.place(plan.fields)
document: dict[str, Any] = {
"status": ended,
"work": plan.work,
"customer_case": case,
"execution_id": last.get("execution_id"),
"record": last.get("record"),
"guide": last.get("guide"),
"files": last.get("files", {}),
"latest": last.get("latest"),
"case": last.get("case"),
"results": plan.results,
}
if not_started:
document["not_started"] = not_started
return document
def _hold(self, task_id: str, plan: Plan, step: int, task: Task) -> None:
if task.id:
self._waiting[task_id] = Waiting(plan, step, task.id, task.context_id)
@@ -422,7 +528,9 @@ class RelayExecutor(AgentExecutor):
artifact: Artifact,
relayed: set[str],
files: dict[str, str],
guide: list[str],
updater: TaskUpdater,
relay: bool,
) -> None:
if artifact.artifact_id in relayed:
return
@@ -430,6 +538,13 @@ class RelayExecutor(AgentExecutor):
text = "".join(part.text for part in artifact.parts if part.HasField("text"))
if artifact.name and text:
files[artifact.name] = text
# The Execution engine sends its final Deliverable as markdown.
if not guide and any(
part.media_type == "text/markdown" for part in artifact.parts
):
guide.append(artifact.name)
if not relay:
return
metadata = (
json_format.MessageToDict(artifact.metadata)
if artifact.HasField("metadata")
@@ -453,6 +568,34 @@ class RelayExecutor(AgentExecutor):
)
def _deliver(options: Mapping[str, Any]) -> str:
"""How the caller is given what agents delivered: as it asked, or links for a
KAB workflow step, which takes one output per step, and files for anyone else."""
asked = options.get(DELIVER)
if asked in (LINKS, FILES):
return str(asked)
return LINKS if all(key in options for key in _PLATFORM_STEP) else FILES
def _ended(status: TaskStatus) -> str:
"""How an agent says its work ended, from its last word: `completed` unless it
says otherwise, such as `completed_with_warnings`."""
parts = list(status.message.parts) if status.HasField("message") else []
said = next(
(data for data in get_data_parts(parts) if isinstance(data, Mapping)), {}
)
return str(said.get("status", "completed"))
def _as_files(sources: Mapping[str, Any]) -> dict[str, str]:
"""Sources as files by name: what was parsed on the way, as a platform step
does with an earlier step's output, is sent on as JSON text."""
return {
str(name): content if isinstance(content, str) else json.dumps(content)
for name, content in sources.items()
}
def _options(context: RequestContext) -> dict[str, Any]:
"""The request's metadata: the message's, then the request's own."""
options: dict[str, Any] = {}