Files
orchestration_engine/tests/orchestration/test_sequence.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

297 lines
9.2 KiB
Python

"""A sequence of agents (ADR-0003, step F4): each agent's files go to the next as
`sources`, under one Customer case, with every agent's prompts relayed."""
from __future__ import annotations
import json
import uuid
from collections.abc import AsyncIterator
from typing import Any
import httpx
from a2a.helpers.proto_helpers import new_data_part, new_text_part
from a2a.types import (
Artifact,
Message,
Role,
StreamResponse,
Task,
TaskState,
TaskStatus,
)
from orchestration.agents import Agent, Sequence, load_routes
from orchestration.config import OrchestrationSettings
from orchestration.main import create_app
from orchestration.routing import route
ARCHITECTURE = Agent(
work="architecture", url="http://architecture", description="Designs."
)
OPERATIONS = Agent(work="operations", url="http://operations", description="Operates.")
BOTH = Sequence(
work="architecture_and_operations",
steps=(ARCHITECTURE, OPERATIONS),
description="Designs, then operates.",
)
SETTINGS = OrchestrationSettings(_env_file=None, HEARTBEAT_SECONDS=3600) # type: ignore[call-arg]
def finished(
task_id: str,
files: dict[str, str],
status: str = "completed",
guide: str | None = None,
) -> StreamResponse:
"""A completed task with `files`; `guide` is sent as markdown, as the Execution
engine sends its final Deliverable."""
message = Message(
message_id=str(uuid.uuid4()),
role=Role.ROLE_AGENT,
parts=[
new_text_part("Done."),
new_data_part({"status": status, "warnings": []}),
],
)
return StreamResponse(
task=Task(
id=task_id,
context_id=f"ctx-{task_id}",
status=TaskStatus(state=TaskState.TASK_STATE_COMPLETED, message=message),
artifacts=[
Artifact(
artifact_id=f"{task_id}-{name}",
name=name,
parts=[
new_text_part(text, media_type="text/markdown")
if name == guide
else new_text_part(text)
],
)
for name, text in files.items()
],
)
)
def asking(task_id: str) -> StreamResponse:
message = Message(
message_id=str(uuid.uuid4()),
role=Role.ROLE_AGENT,
parts=[new_text_part("Who operates it?")],
)
return StreamResponse(
task=Task(
id=task_id,
context_id=f"ctx-{task_id}",
status=TaskStatus(
state=TaskState.TASK_STATE_INPUT_REQUIRED, message=message
),
)
)
class ScriptedAgents:
"""Stand-ins for the agents: each answers its turns in order and records what
it was sent."""
def __init__(self, turns: dict[str, list[StreamResponse]]) -> None:
self.turns = {work: list(events) for work, events in turns.items()}
self.received: dict[str, list[Message]] = {work: [] for work in turns}
self._current = ""
async def for_agent(self, agent: Agent) -> Any:
self._current = agent.work
return _Client(self, agent.work)
def forget(self, agent: Agent) -> None:
pass
class _Client:
def __init__(self, agents: ScriptedAgents, work: str) -> None:
self._agents, self._work = agents, work
async def send_message(self, request: Any) -> AsyncIterator[StreamResponse]:
self._agents.received[self._work].append(request.message)
yield self._agents.turns[self._work].pop(0)
async def call(
agents: ScriptedAgents,
parts: list[dict],
metadata: dict | None = None,
task: dict | None = None,
app: Any = None,
) -> tuple[dict, Any]:
app = app or create_app(
[ARCHITECTURE, OPERATIONS],
SETTINGS,
clients=agents, # type: ignore[arg-type]
sequences=[BOTH],
)
message: dict[str, Any] = {
"messageId": str(uuid.uuid4()),
"role": "ROLE_USER",
"parts": parts,
}
if metadata:
message["metadata"] = metadata
if task:
message.update(taskId=task["id"], contextId=task["contextId"])
async with httpx.AsyncClient(
transport=httpx.ASGITransport(app=app), base_url="http://orchestration"
) as caller:
response = await caller.post(
"/a2a",
json={
"jsonrpc": "2.0",
"id": 1,
"method": "SendMessage",
"params": {"message": message},
},
headers={"A2A-Version": "1.0"},
)
body = response.json()
assert "error" not in body, body
return body["result"]["task"], app
def struct(message: Message) -> dict[str, Any]:
from google.protobuf import json_format
return json_format.MessageToDict(message.metadata)
def test_a_sequence_is_named_like_any_work():
decision = route(
{"work": "architecture_and_operations"}, [ARCHITECTURE, OPERATIONS], [BOTH]
)
assert decision.agents == (ARCHITECTURE, OPERATIONS)
def test_sequences_are_read_with_the_agents(tmp_path):
path = tmp_path / "agents.yaml"
path.write_text(
"agents:\n"
" - {work: architecture, url: http://architecture, description: Designs.}\n"
" - {work: operations, url: http://operations, description: Operates.}\n"
"sequences:\n"
" - work: architecture_and_operations\n"
" steps: [architecture, operations]\n"
" description: Designs, then operates.\n",
encoding="utf-8",
)
agents, sequences = load_routes(path)
assert agents == [ARCHITECTURE, OPERATIONS]
assert sequences == [BOTH]
async def test_the_first_agents_files_are_the_next_agents_sources():
agents = ScriptedAgents(
{
"architecture": [
finished("a1", {"graph.json": "{}", "guide.md": "# Guide"})
],
"operations": [finished("o1", {"model.json": "{}"})],
}
)
task, _ = await call(
agents,
[{"text": "A landing zone"}],
metadata={
"work": "architecture_and_operations",
"request": "A landing zone",
"customer_case": "acme",
"pre_approved": True,
"scope": "architecture: spec",
"operations": {"scope": "operations: overlay"},
},
)
assert task["status"]["state"] == "TASK_STATE_COMPLETED"
# Every agent's files reach the caller, each marked with the work it is of.
relayed = {(a["name"], a["metadata"]["work"]) for a in task["artifacts"]}
assert relayed == {
("graph.json", "architecture"),
("guide.md", "architecture"),
("model.json", "operations"),
}
(first,) = agents.received["architecture"]
sent = struct(first)
assert sent["scope"] == "architecture: spec"
assert "operations" not in sent and "work" not in sent
(second,) = agents.received["operations"]
sent = struct(second)
assert [part.text for part in second.parts] == ["A landing zone"]
assert sent["customer_case"] == "acme"
assert sent["pre_approved"] is True
# Its own fields, not the first agent's spec.
assert sent["scope"] == "operations: overlay"
sources = sent["sources"]
assert sources["graph.json"] == "{}" and sources["guide.md"] == "# Guide"
record = json.loads(sources["execution.json"])
assert record == {
"status": "completed",
"customer_case": "acme",
"execution_id": "a1",
"workflow_request": "A landing zone",
"work": "architecture",
}
async def test_an_agent_that_ends_with_warnings_starts_nothing_after_it():
agents = ScriptedAgents(
{
"architecture": [
finished("a1", {"graph.json": "{}"}, status="completed_with_warnings")
],
"operations": [],
}
)
task, _ = await call(
agents,
[{"text": "A landing zone"}],
metadata={"work": "architecture_and_operations"},
)
assert task["status"]["state"] == "TASK_STATE_COMPLETED"
text = " ".join(p.get("text", "") for p in task["status"]["message"]["parts"])
assert "warnings" in text and "operations" in text
data = next(p["data"] for p in task["status"]["message"]["parts"] if "data" in p)
assert data == {
"status": "stopped",
"after": "architecture",
"not_started": ["operations"],
}
assert agents.received["operations"] == []
async def test_the_next_agents_questions_are_relayed_and_answered():
agents = ScriptedAgents(
{
"architecture": [finished("a1", {"graph.json": "{}"})],
"operations": [asking("o1"), finished("o1", {"model.json": "{}"})],
}
)
task, app = await call(
agents,
[{"text": "A landing zone"}],
metadata={"work": "architecture_and_operations"},
)
assert task["status"]["state"] == "TASK_STATE_INPUT_REQUIRED"
assert "Who operates it?" in task["status"]["message"]["parts"][0]["text"]
task, _ = await call(agents, [{"text": "A service provider"}], task=task, app=app)
assert task["status"]["state"] == "TASK_STATE_COMPLETED"
reply = agents.received["operations"][-1]
assert [part.text for part in reply.parts] == ["A service provider"]
assert reply.task_id == "o1"