A request names work the Orchestration engine kept instead of carrying its files: a record or latest link from an earlier document of links (checked, and of the request's tenant and Customer case), latest/<work>, or an Execution's id. The kept files and the record that the work completed are the agent's sources. Nothing starts, and the caller is told why, when the reference does not resolve to completed work it may use. A sequence's next agent is given what was kept of the one before, the same way. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
202 lines
7.4 KiB
Python
202 lines
7.4 KiB
Python
"""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"],
|
|
)
|
|
],
|
|
)
|
|
|
|
|
|
_LINK = {"type": ["string", "null"], "format": "uri"}
|
|
# The document of links a caller asking for links is given (ADR-0004).
|
|
OUTPUT_SCHEMA: dict[str, Any] = {
|
|
"type": "object",
|
|
"properties": {
|
|
"status": {
|
|
"type": "string",
|
|
"description": "completed, completed_with_warnings, or stopped when a "
|
|
"sequence did not run to its end.",
|
|
},
|
|
"work": {"type": "string", "description": "The work that was done."},
|
|
"customer_case": {"type": "string"},
|
|
"execution_id": {
|
|
"type": "string",
|
|
"description": "The last agent's Execution.",
|
|
},
|
|
"record": {**_LINK, "description": "The last Execution's record and links."},
|
|
"guide": {**_LINK, "description": "The last agent's guide."},
|
|
"files": {
|
|
"type": "object",
|
|
"description": "A signed link to each file the last agent delivered.",
|
|
},
|
|
"latest": {
|
|
**_LINK,
|
|
"description": "The newest completed Execution of this work.",
|
|
},
|
|
"case": {**_LINK, "description": "Every Execution kept for the Customer case."},
|
|
"results": {
|
|
"type": "object",
|
|
"description": "Each agent's Execution, how it ended and its links, by its work.",
|
|
},
|
|
"not_started": {"type": "array", "items": {"type": "string"}},
|
|
},
|
|
}
|
|
|
|
|
|
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.",
|
|
},
|
|
"sources": {
|
|
"type": "object",
|
|
"description": (
|
|
"Files to start from, by name, such as an earlier step's "
|
|
"`files`: another agent's delivered work."
|
|
),
|
|
},
|
|
"sources_from": {
|
|
"type": "string",
|
|
"description": (
|
|
"Work kept earlier to start from instead of its files: an "
|
|
"earlier step's `record` or `latest` link, `latest/<work>`, "
|
|
"or an Execution's id in this Customer case."
|
|
),
|
|
},
|
|
"deliver": {
|
|
"type": "string",
|
|
"enum": ["links", "files"],
|
|
"description": (
|
|
"links: one document of signed links to what the agents "
|
|
"delivered, kept here (a platform step is given this). "
|
|
"files: each file as the agent sent it."
|
|
),
|
|
},
|
|
"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"],
|
|
},
|
|
"outputSchema": OUTPUT_SCHEMA,
|
|
}
|
|
|
|
|
|
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
|