feat: working orhcestration engine
This commit is contained in:
2
orchestration/__init__.py
Normal file
2
orchestration/__init__.py
Normal 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
68
orchestration/agents.py
Normal 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
140
orchestration/card.py
Normal 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
28
orchestration/config.py
Normal 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
117
orchestration/main.py
Normal 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
475
orchestration/relay.py
Normal 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
58
orchestration/routing.py
Normal 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}.",
|
||||
)
|
||||
Reference in New Issue
Block a user