"""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/`, " "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