The Orchestration engine keeps every completed agent Execution it relays, by tenant, Customer case and Execution, and serves its record and files at signed, expiring links. A KAB workflow step, which takes one output per step, is given one JSON document of links (`deliver: links`); other callers still get each file, and what they are given is kept either way. - store.py, links.py, delivery.py, serving.py; the relay keeps and links - the card declares `deliver`, `sources` and an output schema - image: STORE_DIR on a /data volume; PUBLIC_URL and LINK_SECRET settings - option 1's tests replaced by tests of the links document Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
194 lines
7.0 KiB
Python
194 lines
7.0 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."
|
|
),
|
|
},
|
|
"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
|