tools.py 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361
  1. """A2A client tools (``a2a`` toolset): a2a_discover/call/list/history/orchestrate talk to *other*
  2. agents. Peers come from config.yaml ``a2a_agents: {name: {url, auth: {type: bearer, token}, timeout,
  3. capabilities}}``. Stdlib urllib; wire format is A2A v1.0 ``SendMessage`` (v0.3 replies still parse)."""
  4. from __future__ import annotations
  5. import contextlib
  6. import json
  7. import logging
  8. import urllib.error
  9. import urllib.request
  10. from concurrent.futures import ThreadPoolExecutor, as_completed
  11. from typing import Any, Optional
  12. from gateway.platforms._shared import coerce_port as _coerce_int, get_scoped_secret as _get_scoped_secret
  13. from . import protocol, security
  14. logger = logging.getLogger(__name__)
  15. _DEFAULT_TIMEOUT = 120
  16. _ORCHESTRATE_MAX_WORKERS = 6 # max parallel peers for fan-out
  17. def _load_config() -> dict:
  18. """Read-only view of config.yaml; peers are only read, never mutated (cache-safe)."""
  19. from hermes_cli.config import load_config_readonly
  20. return load_config_readonly() or {}
  21. def _configured_peers() -> dict:
  22. return _load_config().get("a2a_agents") or {}
  23. def _peer_from_entry(entry: dict, **extra: Any) -> dict:
  24. return {"url": entry.get("url", ""), "auth": entry.get("auth", {}) or {},
  25. "timeout": int(entry.get("timeout", _DEFAULT_TIMEOUT)), **extra}
  26. def _resolve_peer(agent: str) -> Optional[dict]:
  27. """Peer name -> {url, auth, timeout, capabilities, tenant}, or treat ``agent`` as a URL."""
  28. if agent.startswith(("http://", "https://")):
  29. return {"url": agent, "auth": {}, "timeout": _DEFAULT_TIMEOUT, "capabilities": []}
  30. entry = _configured_peers().get(agent)
  31. return _peer_from_entry(entry, capabilities=entry.get("capabilities", []) or [], tenant=entry.get("tenant", "")) if entry else None
  32. def _auth_header(auth: dict) -> dict:
  33. return {"Authorization": f"Bearer {auth['token']}"} if auth and auth.get("type") == "bearer" and auth.get("token") else {}
  34. def _http_json(url: str, headers: dict, timeout: int, method: str, data: Optional[bytes] = None) -> dict:
  35. req = urllib.request.Request(url, data=data, headers=headers, method=method)
  36. with urllib.request.urlopen(req, timeout=timeout) as resp:
  37. return json.loads(resp.read().decode("utf-8"))
  38. def _http_get_json(url: str, headers: dict, timeout: int) -> dict:
  39. return _http_json(url, headers, timeout, "GET")
  40. def _http_post_json(url: str, body: dict, headers: dict, timeout: int) -> dict:
  41. hdrs = {"Content-Type": "application/json", "A2A-Version": protocol.PROTOCOL_VERSION, **headers}
  42. return _http_json(url, hdrs, timeout, "POST", json.dumps(body).encode("utf-8"))
  43. def _fetch_card(base_url: str, headers: dict, timeout: int) -> dict:
  44. """GET the v1.0 agent-card.json; on 404 fall back to the v0.2 agent.json alias."""
  45. base = base_url.rstrip("/")
  46. try:
  47. return _http_get_json(base + "/.well-known/agent-card.json", headers, timeout)
  48. except urllib.error.HTTPError as e:
  49. if e.code != 404:
  50. raise
  51. return _http_get_json(base + "/.well-known/agent.json", headers, timeout)
  52. def _select_jsonrpc_interface(card: Optional[dict]) -> Optional[dict]:
  53. if isinstance(card, dict):
  54. for iface in card.get("supportedInterfaces", []) or []:
  55. if isinstance(iface, dict) and iface.get("protocolBinding") == "JSONRPC" and iface.get("url"):
  56. return iface
  57. return None
  58. def _rpc_url(base_url: str, card: Optional[dict]) -> str:
  59. """Card's JSONRPC interface (v1.0 supportedInterfaces) > card's legacy top-level url > base."""
  60. if iface := _select_jsonrpc_interface(card):
  61. return str(iface["url"])
  62. if isinstance(card, dict) and isinstance(card.get("url"), str) and card["url"]:
  63. return card["url"]
  64. return base_url.rstrip("/")
  65. def _send_task(agent_label: str, peer: dict, message: str, context_id: str) -> tuple[str, str, str]:
  66. """One SendMessage to a peer -> (reply_text, context_id, state). Raises urllib errors /
  67. ValueError for the caller to format; handles redaction, audit, persistence, metrics."""
  68. base_url = peer.get("url", "")
  69. headers = _auth_header(peer.get("auth", {}) or {})
  70. timeout = int(peer.get("timeout", _DEFAULT_TIMEOUT))
  71. try:
  72. card = _fetch_card(base_url, headers, min(timeout, 30)) # best-effort, to learn the rpc URL
  73. except Exception:
  74. card = None
  75. ctx = context_id or protocol.new_context_id()
  76. safe_message = security.redact_outbound(message)
  77. # v1.0: contextId lives inside the Message, not at the params top level.
  78. rpc_body = {"jsonrpc": "2.0", "id": protocol.new_task_id(), "method": "SendMessage",
  79. "params": {"message": protocol.text_message(protocol.ROLE_USER, safe_message, context_id=ctx)}}
  80. iface = _select_jsonrpc_interface(card)
  81. tenant = str(iface["tenant"]) if iface and iface.get("tenant") else str(peer.get("tenant") or "")
  82. if tenant:
  83. rpc_body["params"]["tenant"] = tenant
  84. security.audit("outbound", agent_label, rpc_body["id"], safe_message)
  85. protocol.persist_message(ctx, "user", safe_message, rpc_body["id"])
  86. protocol.metrics.outbound_total += 1
  87. resp = _http_post_json(_rpc_url(base_url, card), rpc_body, headers, timeout)
  88. if "error" in resp:
  89. raise ValueError(f"Peer '{agent_label}' returned an error: {resp['error'].get('message', resp['error'])}")
  90. payload = protocol.unwrap_send_message_response(resp.get("result", {}))
  91. reply = _reply_text_from_result(payload)
  92. reply_ctx, state = ctx, ""
  93. if isinstance(payload, dict):
  94. reply_ctx = payload.get("contextId", ctx)
  95. state = (payload.get("status") or {}).get("state", "")
  96. protocol.persist_message(reply_ctx, "agent", reply, rpc_body["id"])
  97. protocol.metrics.inbound_total += 1
  98. return reply, reply_ctx, state
  99. def _reply_text_from_result(result: Any) -> str:
  100. result = protocol.unwrap_send_message_response(result)
  101. if not isinstance(result, dict):
  102. return str(result)
  103. # Artifacts first (final output), then status message (interim/clarify), else bare Message.
  104. for artifact in result.get("artifacts", []) or []:
  105. txt = protocol.extract_text(artifact)
  106. if txt:
  107. return txt
  108. return protocol.extract_text((result.get("status", {}) or {}).get("message") or result)
  109. _AUTH_ERR = "Error: peer '{agent}' rejected auth (HTTP {code}). Check the configured token."
  110. _HTTP_CALL_ERRORS = {401: _AUTH_ERR, 403: _AUTH_ERR, 429: "Error: peer '{agent}' rate limited us (HTTP 429). Retry later."}
  111. def a2a_discover(args: dict, **_: Any) -> str:
  112. """Fetch and summarize the Agent Card at ``url``."""
  113. url = str(args.get("url") or "").strip()
  114. if not url:
  115. return "Error: 'url' is required (e.g. http://localhost:9999)."
  116. try:
  117. card = _fetch_card(url, {}, _DEFAULT_TIMEOUT)
  118. except urllib.error.HTTPError as e:
  119. return f"Error: discovery failed — HTTP {e.code} from {url}."
  120. except Exception as e:
  121. return f"Error: could not reach {url} — {e}."
  122. caps = card.get("capabilities", {}) or {}
  123. skills = card.get("skills", []) or []
  124. auth = "yes" if card.get("security") else "no"
  125. proto = ", ".join(
  126. f"{i.get('protocolBinding', '?')} v{i.get('protocolVersion', '?')}"
  127. for i in (card.get("supportedInterfaces", []) or []) if isinstance(i, dict)
  128. ) or f"v{card.get('protocolVersion', '?')} (pre-1.0 card)"
  129. lines = [f"Agent: {card.get('name', '?')}", f"Description: {card.get('description', '')}", f"URL: {_rpc_url(url, card)}",
  130. f"Protocol: {proto}",
  131. f"Streaming: {bool(caps.get('streaming'))} Push: {bool(caps.get('pushNotifications'))} Auth required: {auth}",
  132. f"Skills ({len(skills)}):"]
  133. lines.extend(f" - {s.get('name', s.get('id', '?'))}: {s.get('description', '')}" for s in skills[:20])
  134. return "\n".join(lines)
  135. def a2a_call(args: dict, **_: Any) -> str:
  136. """Send a task to a peer (configured name or direct URL); ``context_id`` continues a prior exchange."""
  137. # Accept common aliases models reach for (observed live: 'agent_name').
  138. agent = str(args.get("agent") or args.get("agent_name") or args.get("name") or "").strip()
  139. message = str(args.get("message") or args.get("text") or args.get("task") or "").strip()
  140. context_id = str(args.get("context_id") or args.get("contextId") or "").strip()
  141. if not agent or not message:
  142. return "Error: both 'agent' and 'message' are required."
  143. peer = _resolve_peer(agent)
  144. if not peer or not peer.get("url"):
  145. return f"Error: unknown agent '{agent}'. Configure it under 'a2a_agents' in config.yaml or pass a full http(s):// URL."
  146. try:
  147. reply, reply_ctx, state = _send_task(agent, peer, message, context_id)
  148. except urllib.error.HTTPError as e:
  149. return _HTTP_CALL_ERRORS.get(e.code, "Error: call to '{agent}' failed — HTTP {code}.").format(agent=agent, code=e.code)
  150. except ValueError as e:
  151. return str(e)
  152. except Exception as e:
  153. return f"Error: call to '{agent}' failed — {e}."
  154. short_state = state.replace("TASK_STATE_", "").replace("_", "-").lower() # v0.3 states pass through
  155. header = f"[{agent} · context {reply_ctx}" + (f" · {short_state}" if state else "") + "]"
  156. body = reply or "(no text reply)"
  157. if state == protocol.STATE_INPUT_REQUIRED:
  158. body += f"\n\n(The peer needs more input — answer by calling a2a_call again with context_id '{reply_ctx}'.)"
  159. return f"{header}\n{body}"
  160. def a2a_list(args: dict | None = None, **_: Any) -> str:
  161. """List configured A2A peers, persisted conversations, and metrics."""
  162. peers = _configured_peers()
  163. lines = []
  164. if peers:
  165. lines.append(f"Configured peers ({len(peers)}):")
  166. for name, entry in peers.items():
  167. caps = entry.get("capabilities", [])
  168. lines.append(f" - {name}: {entry.get('url', '?')} (auth: {(entry.get('auth') or {}).get('type', 'none')})"
  169. + (f" caps: {', '.join(caps)}" if caps else ""))
  170. else:
  171. lines.append("No peers configured. Add them under 'a2a_agents' in config.yaml.")
  172. if convos := protocol.list_conversations():
  173. lines.append("")
  174. lines.append(f"Persisted conversations ({len(convos)}) — recall with a2a_history:")
  175. lines.extend(f" - {c}" for c in convos[:25])
  176. m = protocol.metrics.snapshot()
  177. lines.append("")
  178. lines.append(f"Metrics: {m['inbound_total']} in / {m['outbound_total']} out, {m['tasks_completed']} completed, "
  179. f"{m['tasks_failed']} failed, {m['streams_started']} streams, {m['push_sent']} push sent, "
  180. f"{m['anti_loop_triggers']} anti-loop, {m['rate_limit_triggers']} rate-limited, avg {m['avg_latency_ms']}ms")
  181. return "\n".join(lines)
  182. def a2a_history(args: dict, **_: Any) -> str:
  183. """Recall a persisted A2A conversation (survives compaction/restarts)."""
  184. context_id = str(args.get("context_id") or args.get("contextId") or "").strip()
  185. if not context_id:
  186. return "Error: 'context_id' is required (see a2a_list for known conversations)."
  187. limit = max(1, min(_coerce_int(args.get("limit") or 50, 50), 200))
  188. messages = protocol.load_conversation(context_id, limit=limit)
  189. if not messages:
  190. return f"No persisted conversation for context '{context_id}'."
  191. lines = [f"Conversation {context_id} (last {len(messages)} messages):"]
  192. for m in messages:
  193. text = (m.get("text") or "").strip()
  194. lines.append(f"[{m.get('role', '?')}] {text[:1000] + ' …[truncated]' if len(text) > 1000 else text}")
  195. return "\n".join(lines)
  196. def _match_peers_by_capability(capability: str) -> list[tuple[str, dict]]:
  197. """Configured peers that advertise the capability ('*' matches all)."""
  198. return [(name, entry) for name, entry in _configured_peers().items()
  199. if capability in (entry.get("capabilities", []) or []) or capability == "*"]
  200. def _call_peer_sync(agent_name: str, peer_entry: dict, message: str, context_id: str = "") -> tuple[str, str]:
  201. """Call a single peer synchronously -> (agent_name, reply_text)."""
  202. try:
  203. reply, _ctx, _state = _send_task(agent_name, _peer_from_entry(peer_entry), message, context_id)
  204. return (agent_name, reply or "(no reply)")
  205. except Exception as e:
  206. return (agent_name, f"Error: {e}")
  207. def a2a_orchestrate(args: dict, **_: Any) -> str:
  208. """Fan-out a task to peers matching a capability. Modes: ``all``, ``first`` (first successful),
  209. ``best`` (longest successful — coarse; use ``all`` to judge yourself)."""
  210. capability = str(args.get("capability") or "").strip()
  211. message = str(args.get("message") or args.get("task") or "").strip()
  212. mode = str(args.get("mode") or "all").strip().lower()
  213. mode = mode if mode in ("all", "first", "best") else "all"
  214. context_id = str(args.get("context_id") or "").strip()
  215. if not message:
  216. return "Error: 'message' is required."
  217. if not capability:
  218. return "Error: 'capability' is required (or use '*' for all peers)."
  219. if not (matches := _match_peers_by_capability(capability)):
  220. return f"Error: no configured peers advertise capability '{capability}'."
  221. results: list[tuple[str, str]] = []
  222. with ThreadPoolExecutor(max_workers=min(len(matches), _ORCHESTRATE_MAX_WORKERS)) as pool:
  223. futures = {pool.submit(_call_peer_sync, name, entry, message, context_id): name for name, entry in matches}
  224. for fut in as_completed(futures):
  225. name = futures[fut]
  226. try:
  227. results.append(fut.result())
  228. if mode == "first" and not results[-1][1].startswith("Error:"):
  229. for f in futures: # good reply; cancel peers that haven't started
  230. f.cancel()
  231. break
  232. except Exception as e:
  233. results.append((name, f"Error: {e}"))
  234. results.sort(key=lambda r: r[0]) # deterministic output
  235. successes = [(name, reply) for name, reply in results if not reply.startswith("Error:")]
  236. if mode in ("best", "first"):
  237. if not successes:
  238. return "\n".join(["All peers failed:"] + [f" {name}: {reply}" for name, reply in results])
  239. name, reply = max(successes, key=lambda r: len(r[1])) if mode == "best" else successes[0]
  240. return f"[{mode}: {name}]\n{reply}"
  241. return "\n".join([f"Orchestrated '{capability}' to {len(matches)} peer(s):"]
  242. + [line for name, reply in results for line in (f"\n--- {name} ---", reply)])
  243. def _str(description: str) -> dict:
  244. return {"type": "string", "description": description}
  245. # name -> (handler, description, properties, required)
  246. _TOOLS: dict[str, tuple[Any, str, dict, list[str]]] = {
  247. "a2a_discover": (a2a_discover,
  248. "Fetch a remote agent's A2A Agent Card (name, capabilities, skills) from a URL. "
  249. "Use this to find out what a remote agent can do before calling it.",
  250. {"url": _str("Base URL of the remote A2A agent, e.g. http://localhost:9999")}, ["url"]),
  251. "a2a_call": (a2a_call,
  252. "Send a natural-language task to a remote A2A agent and return its reply. The agent is a peer "
  253. "(any A2A-compliant framework), not a sub-agent you control. Pass 'context_id' from a previous "
  254. "reply to continue a multi-turn exchange.",
  255. {"agent": _str("Configured peer name (from a2a_agents) or a full http(s):// URL."),
  256. "message": _str("The task / message to send the peer, in natural language."),
  257. "context_id": _str("Optional: context id from a prior reply, to continue the conversation.")},
  258. ["agent", "message"]),
  259. "a2a_list": (a2a_list, "List configured A2A peer agents, persisted A2A conversations, and metrics.", {}, []),
  260. "a2a_history": (a2a_history,
  261. "Recall a persisted A2A conversation transcript by context_id. It survives restarts and "
  262. "context compaction; use a2a_list to see known context ids.",
  263. {"context_id": _str("Context id of the conversation to recall."),
  264. "limit": {"type": "integer", "description": "Max messages to return (default 50, max 200)."}},
  265. ["context_id"]),
  266. "a2a_orchestrate": (a2a_orchestrate,
  267. "Fan-out a task to multiple peer agents by capability. Peers are matched from config.yaml "
  268. "a2a_agents.*.capabilities. Modes: 'all' (return all replies), 'first' (first successful), "
  269. "'best' (longest successful reply).",
  270. {"capability": _str("Capability to match (e.g. 'research', 'code') or '*' for all peers."),
  271. "message": _str("The task to send to all matching peers."),
  272. "mode": {"type": "string", "enum": ["all", "first", "best"], "description": "How to aggregate results. Default: 'all'."},
  273. "context_id": _str("Optional: shared context id for all peers.")},
  274. ["capability", "message"]),
  275. }
  276. def _a2a_tools_available() -> bool:
  277. """check_fn: serve the client tools ONLY when the operator opted into A2A (peers under
  278. ``a2a_agents``, inbound platform enabled, or A2A_PORT set). Fail closed.
  279. Maintainer-directed (#95681): these registered unconditionally, so every session on every install paid
  280. ~561 tok/call for tools whose only possible output without config is 'no peers configured'. A2A is
  281. unrelated to Bot Mode (bots talk over gateway RPCs) — for most installs this toolset is foreign-agent
  282. plumbing they never enabled. Config adds mid-session surface at the next compaction (#97073).
  283. """
  284. cfg = {}
  285. with contextlib.suppress(Exception):
  286. cfg = _load_config()
  287. if cfg.get("a2a_agents"):
  288. return True
  289. try:
  290. # Scoped like the platform gate: os.environ is the launch profile's under multiplexing (#122126).
  291. if _get_scoped_secret("A2A_PORT"):
  292. return True
  293. a2a_cfg = (cfg.get("platforms") or {}).get("a2a") or {}
  294. return bool(isinstance(a2a_cfg, dict) and a2a_cfg.get("enabled"))
  295. except Exception:
  296. return False
  297. def register_tools(ctx) -> None:
  298. """Register the client tools in the ``a2a`` toolset (config-gated)."""
  299. for name, (handler, description, properties, required) in _TOOLS.items():
  300. parameters: dict[str, Any] = {"type": "object", "properties": properties}
  301. if required:
  302. parameters["required"] = required
  303. ctx.register_tool(name=name, toolset="a2a", handler=handler, description=description,
  304. schema={"name": name, "description": description, "parameters": parameters},
  305. emoji="\U0001f9e9", check_fn=_a2a_tools_available) # puzzle piece