Files
orchestration_engine/orchestration/card.py
Jonathan Boniface 1ec939f4fd feat: build on kept work by reference with sources_from (ADR-0004 phase 2)
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>
2026-10-21 21:00:26 +01:00

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