Files
orchestration_engine/orchestration/card.py

141 lines
4.9 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"],
)
],
)
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