feat: working orhcestration engine

This commit is contained in:
2026-10-21 19:50:24 +01:00
commit ce5e2f20cd
161 changed files with 31794 additions and 0 deletions

View File

@@ -0,0 +1,2 @@
"""The Orchestration engine: every request comes through it, and it decides which
agent the work belongs to (ADR-0003). It produces no Deliverable."""

68
orchestration/agents.py Normal file
View File

@@ -0,0 +1,68 @@
"""The agents the Orchestration engine routes to, and the sequences of them, from
configuration."""
from __future__ import annotations
from dataclasses import dataclass
from pathlib import Path
import yaml
@dataclass(frozen=True)
class Agent:
"""One kind of work, and the agent that does it."""
work: str # what a caller names: "operating_model", "solution_architecture"
url: str # the agent's base URL; its card says where its A2A interface is
description: str = ""
@dataclass(frozen=True)
class Sequence:
"""Work done by agents in turn: each one's files are the next one's sources."""
work: str # what a caller names: "architecture_and_operating_model"
steps: tuple[Agent, ...]
description: str = ""
def load_routes(path: str | Path) -> tuple[list[Agent], list[Sequence]]:
"""The agents and the sequences in `path`, in the order written. One agent or
sequence per kind of work; a sequence names only agents configured here."""
raw = yaml.safe_load(Path(path).read_text(encoding="utf-8")) or {}
agents = [
Agent(
work=str(entry["work"]),
url=str(entry["url"]).rstrip("/"),
description=str(entry.get("description") or ""),
)
for entry in raw.get("agents") or []
]
by_work = {agent.work: agent for agent in agents}
sequences: list[Sequence] = []
for entry in raw.get("sequences") or []:
unknown = [str(step) for step in entry["steps"] if str(step) not in by_work]
if unknown:
raise ValueError(
f"The sequence {entry['work']!r} names no configured agent for "
+ ", ".join(repr(step) for step in unknown)
)
sequences.append(
Sequence(
work=str(entry["work"]),
steps=tuple(by_work[str(step)] for step in entry["steps"]),
description=str(entry.get("description") or ""),
)
)
seen: set[str] = set()
for work in [*(a.work for a in agents), *(s.work for s in sequences)]:
if work in seen:
raise ValueError(f"Two agents are configured for the work {work!r}")
seen.add(work)
return agents, sequences
def load_agents(path: str | Path) -> list[Agent]:
"""The agents in `path`, without its sequences."""
return load_routes(path)[0]

140
orchestration/card.py Normal file
View File

@@ -0,0 +1,140 @@
"""The Orchestration engine's A2A card: the work it can route, and the fields a
request carries on to the agent that does it."""
from __future__ import annotations
from collections.abc import Sequence
from typing import Any
from a2a.server.request_handlers.response_helpers import agent_card_to_dict
from a2a.types import (
AgentCapabilities,
AgentCard,
AgentInterface,
AgentProvider,
AgentSkill,
)
from orchestration.agents import Agent
from orchestration.agents import Sequence as AgentSequence
from orchestration.config import OrchestrationSettings
from orchestration.routing import WORK
A2A_PATH = "/a2a"
def _offered(
agents: Sequence[Agent], sequences: Sequence[AgentSequence]
) -> list[tuple[str, str]]:
"""Each kind of work a caller can name, with what it is."""
return [
*((agent.work, agent.description) for agent in agents),
*((sequence.work, sequence.description) for sequence in sequences),
]
def build_card(
settings: OrchestrationSettings,
agents: Sequence[Agent],
sequences: Sequence[AgentSequence] = (),
) -> AgentCard:
base_url = (
settings.A2A_PUBLIC_URL or f"http://{settings.A2A_HOST}:{settings.A2A_PORT}"
).rstrip("/")
offered = "; ".join(
f"{work}: {description}" if description else work
for work, description in _offered(agents, sequences)
)
return AgentCard(
name=settings.AGENT_NAME,
description=(
"Takes every request for work, decides which agent it belongs to, and "
"relays that agent's questions and Approvals. It produces nothing itself."
),
version=settings.AGENT_VERSION,
provider=AgentProvider(
organization="Kyndryl Agent Builder", url="https://www.kyndryl.com"
),
supported_interfaces=[
AgentInterface(
url=f"{base_url}{A2A_PATH}",
protocol_binding="JSONRPC",
protocol_version="1.0",
)
],
capabilities=AgentCapabilities(streaming=True, push_notifications=False),
default_input_modes=["text/plain", "application/json"],
default_output_modes=["text/plain", "text/markdown", "application/json"],
skills=[
AgentSkill(
id="orchestration",
name="Route work to an agent",
description=(
f"Name the work as `{WORK}` and it goes to the agent that does it, "
f"with every question and Approval passed back. Work: {offered}."
),
tags=["orchestration", *(w for w, _ in _offered(agents, sequences))],
input_modes=["text/plain", "application/json"],
output_modes=["text/plain", "text/markdown", "application/json"],
)
],
)
def input_contract(
agents: Sequence[Agent], sequences: Sequence[AgentSequence] = ()
) -> dict[str, Any]:
"""The fields KAB's workflow builder offers for a step (`skills[0].inputSchema`).
`work` chooses the agent; the rest go to it as they are, and are what every
agent on the Execution engine starts from."""
return {
"inputArrives": "as_fields",
"inputSchema": {
"type": "object",
"properties": {
WORK: {
"type": "string",
"enum": [work for work, _ in _offered(agents, sequences)],
"description": "The work this is. "
+ "; ".join(
f"{work}: {description}"
for work, description in _offered(agents, sequences)
),
},
"request": {
"type": "string",
"description": "What is wanted, in the customer's words.",
},
"customer_case": {
"type": "string",
"description": "The Customer case's short slug. A spec names its own.",
},
"scope": {
"type": "string",
"uiFieldType": "textarea",
"description": "The spec to start from, as a YAML or JSON document.",
},
"pre_approved": {
"type": "boolean",
"default": True,
"description": (
"Treat every Approval as granted. A platform step cannot "
"answer the agent's questions, so leave it on there."
),
},
},
"required": [WORK, "customer_case"],
},
}
def card_document(
card: AgentCard,
agents: Sequence[Agent],
sequences: Sequence[AgentSequence] = (),
) -> dict[str, Any]:
"""The card as served: the A2A card, with the input contract on its skill."""
document = agent_card_to_dict(card)
document["skills"][0].update(input_contract(agents, sequences))
return document

28
orchestration/config.py Normal file
View File

@@ -0,0 +1,28 @@
"""The Orchestration engine's settings, from the environment or `.env`."""
from __future__ import annotations
from pydantic_settings import BaseSettings, SettingsConfigDict
class OrchestrationSettings(BaseSettings):
model_config = SettingsConfigDict(
env_file=".env", env_file_encoding="utf-8", extra="ignore"
)
AGENT_NAME: str = "orchestration_engine"
AGENT_VERSION: str = "0.1.0"
LOG_LEVEL: str = "INFO"
A2A_HOST: str = "0.0.0.0"
A2A_PORT: int = 8080
A2A_PUBLIC_URL: str | None = None
# The agents it routes to: a YAML file of `agents: [{work, url, description}]`.
AGENTS_FILE: str = "agents.yaml"
# While an agent works, report that it still is at this interval, so a caller
# that takes a silent stream for a dead one does not retry (ADR-0003).
HEARTBEAT_SECONDS: float = 60
# How long to wait to connect to an agent. Reading waits as long as the
# agent's work takes.
CONNECT_TIMEOUT_SECONDS: float = 10

117
orchestration/main.py Normal file
View File

@@ -0,0 +1,117 @@
"""The Orchestration engine's A2A server: `python -m orchestration.main`."""
from __future__ import annotations
import logging
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.relay import AgentClients, RelayExecutor
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] = (),
) -> 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."""
settings = settings or OrchestrationSettings()
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,
),
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"]),
*jsonrpc,
],
lifespan=lifespan,
)
@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()

475
orchestration/relay.py Normal file
View File

@@ -0,0 +1,475 @@
"""Dispatching a request to agents and relaying everything back (ADR-0003).
Each of the Orchestration engine's tasks runs a plan: one agent, or a sequence of
them. At any moment it stands for one task of one agent. What the agent says, a
status, a question, an Approval it asks for, a file, goes to the caller unchanged;
what the caller replies goes to the agent unchanged. When an agent of a sequence
completes, its files go to the next as `sources` (step F4).
"""
from __future__ import annotations
import asyncio
import contextlib
import json
import logging
import uuid
from collections.abc import Mapping, Sequence
from dataclasses import dataclass, field
from typing import Any
import httpx
from a2a.client import Client, ClientConfig, ClientFactory
from a2a.helpers.proto_helpers import (
get_data_parts,
new_data_part,
new_task,
new_text_part,
)
from a2a.server.agent_execution import AgentExecutor, RequestContext
from a2a.server.events import EventQueue
from a2a.server.tasks import TaskUpdater
from a2a.types import (
Artifact,
CancelTaskRequest,
Message,
Part,
Role,
SendMessageRequest,
Task,
TaskState,
TaskStatus,
)
from google.protobuf import json_format
from orchestration.agents import Agent
from orchestration.agents import Sequence as AgentSequence
from orchestration.routing import WORK, route
logger = logging.getLogger(__name__)
# The states after which the agent waits for the caller, or is done.
_ENDS_A_TURN = {
TaskState.TASK_STATE_INPUT_REQUIRED,
TaskState.TASK_STATE_AUTH_REQUIRED,
TaskState.TASK_STATE_COMPLETED,
TaskState.TASK_STATE_FAILED,
TaskState.TASK_STATE_CANCELED,
TaskState.TASK_STATE_REJECTED,
}
_PAUSES = {TaskState.TASK_STATE_INPUT_REQUIRED, TaskState.TASK_STATE_AUTH_REQUIRED}
# What every agent of a sequence is sent of the caller's fields. The rest go to the
# first agent only, or to the agent whose work names them: `operating_model: {...}`.
_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"
@dataclass
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`
text: str # the request, as the agents are sent it
other_parts: list[Part] = field(default_factory=list) # data and files sent with it
def metadata(self, step: int, sources: Mapping[str, str] | None) -> dict[str, Any]:
"""The metadata for the agent at `step`."""
works = {agent.work for agent in self.steps}
if step == 0:
sent = {k: v for k, v in self.fields.items() if k not in works}
else:
sent = {k: self.fields[k] for k in _CARRIED if k in self.fields}
own = self.fields.get(self.steps[step].work)
if isinstance(own, Mapping):
sent.update(own)
if sources is not None:
sent["sources"] = dict(sources)
return sent
@dataclass
class Waiting:
"""The agent's task one of our tasks stands for, and where it is in its plan."""
plan: Plan
step: int
task_id: str
context_id: str
@property
def agent(self) -> Agent:
return self.plan.steps[self.step]
class AgentClients:
"""One A2A client per agent, made from its card the first time it is called."""
def __init__(self, httpx_client: httpx.AsyncClient) -> None:
self._factory = ClientFactory(
ClientConfig(streaming=True, httpx_client=httpx_client)
)
self._clients: dict[str, Client] = {}
async def for_agent(self, agent: Agent) -> Client:
if agent.work not in self._clients:
self._clients[agent.work] = await self._factory.create_from_url(agent.url)
return self._clients[agent.work]
def forget(self, agent: Agent) -> None:
"""Read the agent's card again next time: it may have moved or changed."""
self._clients.pop(agent.work, None)
class RelayExecutor(AgentExecutor):
def __init__(
self,
agents: Sequence[Agent],
clients: AgentClients,
heartbeat_seconds: float,
sequences: Sequence[AgentSequence] = (),
) -> None:
self._agents = list(agents)
self._sequences = list(sequences)
self._clients = clients
self._heartbeat_seconds = heartbeat_seconds
self._waiting: dict[str, Waiting] = {}
async def execute(self, context: RequestContext, event_queue: EventQueue) -> None:
task_id = context.task_id or ""
updater = TaskUpdater(event_queue, task_id, context.context_id or "")
parts = list(context.message.parts) if context.message is not None else []
if context.current_task is not None:
await self._resume(task_id, context, parts, updater)
return
await event_queue.enqueue_event(
new_task(
task_id,
context.context_id or "",
TaskState.TASK_STATE_SUBMITTED,
history=[context.message] if context.message is not None else [],
)
)
await updater.start_work()
options = _options(context)
decision = route(options, self._agents, self._sequences)
logger.info("Task %s: %s", task_id, decision.reason)
if not decision.agents:
await updater.complete(
updater.new_agent_message(
[
new_text_part(decision.reason),
new_data_part(
{
"status": "not_started",
"work": [
*(a.work for a in self._agents),
*(s.work for s in self._sequences),
],
}
),
]
)
)
return
fields = {key: value for key, value in options.items() if key != WORK}
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.
plan = Plan(
steps=decision.agents,
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")],
)
await self._run(task_id, plan, 0, self._opening(plan, 0, None), updater)
async def _resume(
self,
task_id: str,
context: RequestContext,
parts: list[Part],
updater: TaskUpdater,
) -> None:
waiting = self._waiting.get(task_id)
if waiting is None:
await updater.failed(
updater.new_agent_message(
[
new_text_part(
"This task's place in the agent's work is no longer "
"held here, as after a restart. Start the request again."
)
]
)
)
return
await updater.start_work()
message = Message(
message_id=str(uuid.uuid4()),
role=Role.ROLE_USER,
parts=parts,
task_id=waiting.task_id,
context_id=waiting.context_id,
)
metadata = _options(context)
if metadata:
message.metadata.update(metadata)
await self._run(task_id, waiting.plan, waiting.step, message, updater)
@staticmethod
def _opening(plan: Plan, step: int, sources: Mapping[str, str] | None) -> Message:
"""The first message to the agent at `step`."""
message = Message(
message_id=str(uuid.uuid4()),
role=Role.ROLE_USER,
parts=[new_text_part(plan.text), *plan.other_parts]
if plan.text
else list(plan.other_parts),
)
metadata = plan.metadata(step, sources)
if metadata:
message.metadata.update(metadata)
return message
async def cancel(self, context: RequestContext, event_queue: EventQueue) -> None:
task_id = context.task_id or ""
waiting = self._waiting.pop(task_id, None)
if waiting is not None:
with contextlib.suppress(Exception):
client = await self._clients.for_agent(waiting.agent)
await client.cancel_task(CancelTaskRequest(id=waiting.task_id))
await TaskUpdater(event_queue, task_id, context.context_id or "").cancel()
async def _run(
self,
task_id: str,
plan: Plan,
step: int,
message: Message,
updater: TaskUpdater,
) -> None:
"""Relay one turn of the agent at `step`; when it completes and another
agent follows, start that one with its files."""
agent = plan.steps[step]
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
try:
client = await self._clients.for_agent(agent)
async for event in client.send_message(SendMessageRequest(message=message)):
status: TaskStatus | None = None
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)
status = event.task.status
elif event.HasField("artifact_update"):
await self._artifact(
agent, event.artifact_update.artifact, relayed, files, updater
)
elif event.HasField("status_update"):
status = event.status_update.status
elif event.HasField("message"):
# A reply with no task: the agent's whole answer.
heartbeat.cancel()
self._waiting.pop(task_id, None)
await updater.complete(
updater.new_agent_message(list(event.message.parts))
)
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
)
else:
await self._end_turn(task_id, status, updater)
return
if status is not None and status.HasField("message"):
await updater.update_status(
TaskState.TASK_STATE_WORKING,
message=updater.new_agent_message(list(status.message.parts)),
)
heartbeat.cancel()
self._waiting.pop(task_id, None)
await updater.failed(
updater.new_agent_message(
[
new_text_part(
f"The {agent.work} agent stopped before its task ended."
)
]
)
)
except Exception as exc:
heartbeat.cancel()
self._clients.forget(agent)
self._waiting.pop(task_id, None)
logger.exception("Task %s: relaying to %s failed", task_id, agent.work)
await updater.failed(
updater.new_agent_message(
[
new_text_part(
f"Could not relay to the {agent.work} agent at {agent.url}: "
f"{type(exc).__name__}: {exc}"
)
]
)
)
finally:
heartbeat.cancel()
async def _next(
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."""
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)
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
]
)
)
return
record = {
"status": "completed",
"customer_case": plan.fields.get("customer_case"),
"execution_id": waiting.task_id if waiting else None,
"workflow_request": plan.text,
"work": agent.work,
}
sources = {
**files,
RECORD: json.dumps({k: v for k, v in record.items() if v is not None}),
}
following = plan.steps[step + 1]
await updater.update_status(
TaskState.TASK_STATE_WORKING,
message=updater.new_agent_message(
[
new_text_part(
f"The {agent.work} agent completed. Its files go to the "
f"{following.work} agent."
)
]
),
)
await self._run(
task_id, plan, step + 1, self._opening(plan, step + 1, sources), updater
)
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)
async def _end_turn(
self, task_id: str, status: TaskStatus, updater: TaskUpdater
) -> None:
parts = list(status.message.parts) if status.HasField("message") else []
message = updater.new_agent_message(parts) if parts else None
if status.state not in _PAUSES:
self._waiting.pop(task_id, None)
if status.state == TaskState.TASK_STATE_INPUT_REQUIRED:
await updater.requires_input(message)
elif status.state == TaskState.TASK_STATE_AUTH_REQUIRED:
await updater.requires_auth(message)
elif status.state == TaskState.TASK_STATE_COMPLETED:
await updater.complete(message)
elif status.state == TaskState.TASK_STATE_REJECTED:
await updater.reject(message)
elif status.state == TaskState.TASK_STATE_CANCELED:
await updater.cancel(message)
else:
await updater.failed(message)
@staticmethod
async def _artifact(
agent: Agent,
artifact: Artifact,
relayed: set[str],
files: dict[str, str],
updater: TaskUpdater,
) -> None:
if artifact.artifact_id in relayed:
return
relayed.add(artifact.artifact_id)
text = "".join(part.text for part in artifact.parts if part.HasField("text"))
if artifact.name and text:
files[artifact.name] = text
metadata = (
json_format.MessageToDict(artifact.metadata)
if artifact.HasField("metadata")
else {}
)
await updater.add_artifact(
list(artifact.parts),
artifact_id=artifact.artifact_id or None,
name=artifact.name or None,
metadata={**metadata, "work": agent.work},
)
async def _beat(self, agent: Agent, updater: TaskUpdater) -> None:
while True:
await asyncio.sleep(self._heartbeat_seconds)
await updater.update_status(
TaskState.TASK_STATE_WORKING,
message=updater.new_agent_message(
[new_text_part(f"The {agent.work} agent is still working.")]
),
)
def _options(context: RequestContext) -> dict[str, Any]:
"""The request's metadata: the message's, then the request's own."""
options: dict[str, Any] = {}
if context.message is not None and context.message.HasField("metadata"):
options.update(
_whole_numbers(json_format.MessageToDict(context.message.metadata))
)
options.update(context.metadata)
return options
def _whole_numbers(value: Any) -> Any:
"""Metadata holds every number as a double; a caller's 9 is sent on as 9."""
if isinstance(value, float) and value.is_integer():
return int(value)
if isinstance(value, Mapping):
return {key: _whole_numbers(item) for key, item in value.items()}
if isinstance(value, list):
return [_whole_numbers(item) for item in value]
return value

58
orchestration/routing.py Normal file
View File

@@ -0,0 +1,58 @@
"""Which agents a request is for (ADR-0003). It never guesses.
In order: the work the caller named, an agent's or a sequence's; the only agent,
when there is one and no sequence; otherwise none, with how to name the work.
Reading a request by Jev is step F3, added to these rules rather than in place of
them.
"""
from __future__ import annotations
from collections.abc import Mapping
from collections.abc import Sequence as Seq
from dataclasses import dataclass
from typing import Any
from orchestration.agents import Agent, Sequence
WORK = "work" # the metadata field a caller names the work in
@dataclass(frozen=True)
class Decision:
agents: tuple[Agent, ...] # in the order they work; empty when none
reason: str
@property
def agent(self) -> Agent | None:
"""The first agent, or None when nothing is to start."""
return self.agents[0] if self.agents else None
def route(
options: Mapping[str, Any],
agents: Seq[Agent],
sequences: Seq[Sequence] = (),
) -> Decision:
named = options.get(WORK)
offered = ", ".join([*(a.work for a in agents), *(s.work for s in sequences)])
if named:
for agent in agents:
if agent.work == named:
return Decision((agent,), f"The caller named the work {named!r}.")
for sequence in sequences:
if sequence.work == named:
return Decision(
sequence.steps, f"The caller named the sequence {named!r}."
)
return Decision(
(),
f"No agent here does the work {named!r}. The work it can name: {offered}.",
)
if len(agents) == 1 and not sequences:
return Decision((agents[0],), "It is the only agent.")
return Decision(
(),
"Nothing was started: name the work this is, as `work` in the request's "
f"metadata. The work it can name: {offered}.",
)