"""Runs a role as a KAB sub-agent, behind the engine's AgentRuntime interface. A sub-agent's functions are fixed in agent.yaml, and a role's tools change with each Deliverable, so every sub-agent has one function, `use_tool`, and is told in its request which tools it has. The tools themselves are the engine's, so every rule they enforce holds. Going through ask_sub_agent keeps each call under the runtime's gateway, limits, logs and cost tracking. """ from __future__ import annotations import contextvars import json from collections.abc import Mapping, Sequence from dataclasses import dataclass from pathlib import Path from typing import Any from kyndryl_agent_runtime import SubAgentFailed, ask_sub_agent from app.engine.skill_tools import skill_tools from app.engine.runtime import ( AgentTask, BudgetExhausted, Outcome, RoleSpec, Stopped, ToolSpec, ) @dataclass class _Run: tools: dict[str, ToolSpec] outcome: Outcome | None = None _run: contextvars.ContextVar[_Run | None] = contextvars.ContextVar("role_run", default=None) def sub_agent_name(role: str) -> str: return role.replace("-", "_") def request_for(role: RoleSpec, task: AgentTask, tools: Sequence[ToolSpec]) -> str: listed = [ {"name": tool.name, "description": tool.description, "arguments": tool.parameters} for tool in tools ] return "\n\n".join( [ role.instructions, f"Your task: {task.prompt}", "Call `use_tool` with a tool's name and its arguments as a JSON object in " "text. A tool that ends your turn ends your work. These are your tools:\n" + json.dumps(listed, ensure_ascii=False), "What you are given:\n" + json.dumps(task.context, ensure_ascii=False, default=str), ] ) class KabRuntime: def __init__(self, skills: Mapping[str, Path] | None = None) -> None: self._skills = dict(skills or {}) async def run(self, role: RoleSpec, task: AgentTask, tools: Sequence[ToolSpec]) -> Outcome: tools = [*skill_tools(self._skills, role.skills), *tools] run = _Run({tool.name: tool for tool in tools}) token = _run.set(run) try: reply = await ask_sub_agent(sub_agent_name(role.name), request_for(role, task, tools)) except SubAgentFailed as exc: if run.outcome is None: return BudgetExhausted(str(exc)) reply = "" finally: _run.reset(token) return run.outcome or Stopped(reply or "It stopped without submitting anything.") async def use_tool(tool: str, arguments: str = "{}") -> str: """Call one of the tools your request lists, with its arguments as a JSON object.""" run = _run.get() if run is None: return "Refused: no work is in progress." if run.outcome is not None: return "Your turn has ended. Stop now." spec = run.tools.get(tool) if spec is None: return f"Refused: {tool} is not one of your tools: {', '.join(run.tools)}." try: parsed: Any = json.loads(arguments or "{}") except ValueError as exc: return f"Refused: arguments are not JSON: {exc}" if not isinstance(parsed, dict): return "Refused: arguments must be a JSON object." result = await spec.handler(**parsed) if result.outcome is not None: run.outcome = result.outcome return result.message