Files
orchestration_engine/orchestration/relay.py

476 lines
18 KiB
Python

"""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