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