feat: add invoke module with discover-first flow (v0.12.0) (#45)

New core/invoke.py consolidates agent invocation logic into a single
source of truth. CLI and MCP server now delegate here instead of
duplicating protocol payloads and HTTP handling.

Discover-first pattern: callers provide domain+name instead of raw
endpoint URLs. DNS discovery resolves the agent, agent card prefetch
validates the endpoint and retrieves metadata, then the call proceeds
through SDK (with telemetry) or raw httpx fallback.

Key fixes: hardcoded 30s future.result() timeout in _run_async,
empty error strings from SDK exceptions, missing type guards on
A2A response parsing, unhandled SDK exceptions in invoke path.

Signed-off-by: Igor Racic <iracic82@gmail.com>

Author: iracic82

CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to DNS-AID will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.12.0] - 2026-03-12
+
+### Added
+- **`core/invoke.py` module** — Single source of truth for agent invocation (A2A messaging + MCP tool calling). CLI and MCP server now delegate to `invoke.py` instead of duplicating protocol logic. Public API: `send_a2a_message()`, `call_mcp_tool()`, `list_mcp_tools()`, `resolve_a2a_endpoint()`.
+- **Discover-first invocation flow** — `send_a2a_message()` and MCP tools accept `domain` + `name` instead of requiring a raw endpoint URL. Resolution chain: DNS discovery → agent card fetch → invoke.
+- **Agent card prefetch** — Before invoking, fetches `/.well-known/agent-card.json` for canonical endpoint URL and metadata (name, description, skills). Includes host mismatch protection: if the agent card's `url` hostname differs from the DNS endpoint, the DNS endpoint is used and a warning is logged.
+- **`dns-aid message --domain --name` options** — Discover-first CLI flow: `dns-aid message --domain ai.infoblox.com --name security-analyzer "hello"`. Existing `--endpoint` option still supported for direct invocation.
+
+### Changed
+- **CLI commands delegate to `core/invoke.py`** — `dns-aid message`, `dns-aid call`, and `dns-aid list-tools` now call the shared invoke module instead of inlining httpx/SDK logic. Reduces code duplication and ensures consistent behavior across CLI and MCP server.
+- **MCP `send_a2a_message` tool enhanced** — Now accepts `domain` + `name` parameters for discover-first invocation from Claude Desktop, in addition to the existing `endpoint` parameter.
+
+### Fixed
+- **Hardcoded 30s timeout in `_run_async()`** — The thread pool wrapper used `future.result(timeout=30)`, which killed long-running requests regardless of the user-specified timeout. Now passes the actual timeout value through.
+- **Empty error strings in SDK path** — `InvokeResult.error` could be an empty string on failure. All exceptions are now wrapped in `InvokeResult` with meaningful error messages.
+- **Type guards on A2A response parsing** — Response body is now validated before accessing nested fields, preventing `KeyError` and `TypeError` on unexpected A2A responses.
+
 ## [0.11.0] - 2026-03-12
 
 ### Added
@@ -498,7 +515,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - [RFC 9460 - SVCB and HTTPS Resource Records](https://www.rfc-editor.org/rfc/rfc9460.html)
 - [RFC 4033-4035 - DNSSEC](https://www.rfc-editor.org/rfc/rfc4033.html)
 
-[Unreleased]: https://github.com/infobloxopen/dns-aid-core/compare/v0.10.0...HEAD
+[Unreleased]: https://github.com/infobloxopen/dns-aid-core/compare/v0.12.0...HEAD
+[0.12.0]: https://github.com/infobloxopen/dns-aid-core/compare/v0.11.0...v0.12.0
+[0.11.0]: https://github.com/infobloxopen/dns-aid-core/compare/v0.10.1...v0.11.0
+[0.10.1]: https://github.com/infobloxopen/dns-aid-core/compare/v0.10.0...v0.10.1
 [0.10.0]: https://github.com/infobloxopen/dns-aid-core/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/infobloxopen/dns-aid-core/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/infobloxopen/dns-aid-core/compare/v0.7.3...v0.8.0

CITATION.cff

@@ -8,7 +8,7 @@ repository-code: "https://github.com/infobloxopen/dns-aid-core"
 authors:
   - name: "The DNS-AID Authors"
 
-version: "0.11.0"
+version: "0.12.0"
 date-released: "2026-03-12"
 
 keywords:

README.md

@@ -184,21 +184,66 @@ dns-aid publish --name internal-bot --domain example.com --protocol mcp --no-upd
 # Agent Communication (talk to discovered agents)
 # =============================================================================
 
-# Send a message to an A2A agent (Google A2A protocol)
-dns-aid message https://security-analyzer.ai.infoblox.com "Analyze DNS-AID security posture"
+# Discover-first: find agent via DNS, fetch agent card, then invoke
+dns-aid message --domain ai.infoblox.com --name security-analyzer \
+    "Analyze security of _marketing._a2a._agents.ai.infoblox.com"
+
+# Direct endpoint (skip discovery)
+dns-aid message --endpoint https://security-analyzer.ai.infoblox.com \
+    "Analyze DNS-AID security posture"
 
 # Send a message with JSON output
-dns-aid message https://chat.example.com "Hello" --json
+dns-aid message --endpoint https://chat.example.com "Hello" --json
+
+# List tools on an MCP agent (discover-first)
+dns-aid list-tools --domain example.com --name network-specialist
 
-# List tools on an MCP agent
-dns-aid list-tools https://mcp.example.com/mcp
+# List tools via direct endpoint
+dns-aid list-tools --endpoint https://mcp.example.com/mcp
 
 # Call a specific tool on an MCP agent
-dns-aid call https://mcp.example.com/mcp search_flights \
+dns-aid call --endpoint https://mcp.example.com/mcp search_flights \
     --arguments '{"origin": "SFO", "destination": "JFK"}'
 
+# Note: discover-first flow fetches /.well-known/agent-card.json to resolve
+# the canonical endpoint URL and agent metadata before invoking. If the agent
+# card's url hostname differs from the DNS endpoint, DNS takes precedence.
 ```
 
+### Python SDK
+
+```python
+import asyncio
+from dns_aid.core.invoke import send_a2a_message, call_mcp_tool, list_mcp_tools
+
+async def main():
+    # Discover-first: find agent via DNS, fetch agent card, invoke
+    result = await send_a2a_message(
+        domain="ai.infoblox.com",
+        name="security-analyzer",
+        message="Analyze security of _marketing._a2a._agents.ai.infoblox.com",
+    )
+    print(result.data["response_text"])
+
+    # Direct endpoint invocation
+    result = await send_a2a_message(
+        endpoint="https://chat.example.com",
+        message="Hello",
+    )
+
+    # MCP tool calling
+    tools = await list_mcp_tools("https://mcp.example.com/mcp")
+    result = await call_mcp_tool(
+        "https://mcp.example.com/mcp",
+        "search_flights",
+        {"origin": "SFO", "destination": "JFK"},
+    )
+
+asyncio.run(main())
+```
+
+For advanced usage with telemetry, connection reuse, and ranking, see the [SDK documentation](docs/getting-started.md#sdk-agent-invocation--telemetry).
+
 ### Agent Index Records
 
 DNS-AID automatically maintains an index record at `_index._agents.{domain}` for efficient discovery:

docs/api-reference.md

@@ -30,6 +30,12 @@ Complete API documentation for DNS-AID - DNS-based Agent Identification and Disc
 - [Validation Utilities](#validation-utilities)
 - [CLI Reference](#cli-reference)
 - [MCP Server](#mcp-server)
+- [Invocation Module](#invocation-module-coreinvokepy)
+  - [send_a2a_message()](#send_a2a_message)
+  - [call_mcp_tool()](#call_mcp_tool)
+  - [list_mcp_tools()](#list_mcp_tools)
+  - [resolve_a2a_endpoint()](#resolve_a2a_endpoint)
+  - [InvokeResult](#invokeresult)
 - [SDK: Invocation & Telemetry](#sdk-invocation--telemetry)
   - [AgentClient](#agentclient)
   - [SDKConfig](#sdkconfig)
@@ -759,6 +765,48 @@ dns-aid index list example.com           # List agents in domain's index
 dns-aid index sync example.com           # Sync index with actual DNS records
 ```
 
+### Agent Communication Commands
+
+```bash
+# Send a message to an A2A agent (discover-first: DNS → agent card → invoke)
+dns-aid message --domain ai.infoblox.com --name security-analyzer \
+    "Analyze security of _marketing._a2a._agents.ai.infoblox.com"
+
+# Send a message to an A2A agent (direct endpoint)
+dns-aid message --endpoint https://security-analyzer.ai.infoblox.com \
+    "Analyze DNS-AID security posture"
+
+# JSON output
+dns-aid message --endpoint https://chat.example.com "Hello" --json
+
+# Custom timeout (seconds)
+dns-aid message --domain example.com --name chat "Hello" --timeout 60
+```
+
+| Option | Description |
+|--------|-------------|
+| `--domain` | Domain for DNS discovery (used with `--name`) |
+| `--name` | Agent name for DNS discovery (used with `--domain`) |
+| `--endpoint` | Direct endpoint URL (skips discovery) |
+| `--json` | Output raw JSON response |
+| `--timeout` | Request timeout in seconds (default: 30) |
+
+```bash
+# List tools on a remote MCP agent (discover-first)
+dns-aid list-tools --domain example.com --name network-specialist
+
+# List tools via direct endpoint
+dns-aid list-tools --endpoint https://mcp.example.com/mcp
+
+# Call a tool on a remote MCP agent
+dns-aid call --endpoint https://mcp.example.com/mcp search_flights \
+    --arguments '{"origin": "SFO", "destination": "JFK"}'
+
+# Call with discover-first
+dns-aid call --domain example.com --name network-specialist get_subnets \
+    --arguments '{"network": "10.0.0.0/8"}'
+```
+
 ### Environment Variables
 
 **General:**
@@ -838,6 +886,7 @@ dns-aid-mcp --transport http --host 0.0.0.0 --port 8000
 | `delete_agent_from_dns` | Delete an agent from DNS (auto-updates index) |
 | `list_agent_index` | List agents in domain's index |
 | `sync_agent_index` | Sync index with actual DNS records |
+| `send_a2a_message` | Send a message to an A2A agent. Accepts `domain` + `name` (discover-first) or `endpoint` (direct). |
 
 ### Health Endpoints (HTTP Transport)
 
@@ -887,6 +936,101 @@ except Exception as e:
 ```
 
 
+## Invocation Module (`core/invoke.py`)
+
+Single source of truth for agent invocation. Both CLI and MCP server delegate to these functions.
+
+### send_a2a_message()
+
+Send a message to an A2A agent using discover-first or direct endpoint.
+
+```python
+from dns_aid.core.invoke import send_a2a_message, InvokeResult
+
+# Discover-first (DNS → agent card → invoke)
+result: InvokeResult = await send_a2a_message(
+    message="Analyze DNS-AID security posture",
+    domain="ai.infoblox.com",
+    name="security-analyzer",
+    timeout=30.0,
+)
+
+# Direct endpoint (skip discovery)
+result = await send_a2a_message(
+    message="Hello",
+    endpoint="https://chat.example.com",
+)
+
+print(result.text)       # Extracted text response
+print(result.raw)        # Full JSON-RPC response dict
+print(result.error)      # Error message if failed (None on success)
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `message` | `str` | Yes | Message text to send |
+| `domain` | `str` | No | Domain for DNS discovery (used with `name`) |
+| `name` | `str` | No | Agent name for DNS discovery (used with `domain`) |
+| `endpoint` | `str` | No | Direct endpoint URL (skips discovery). Either `domain`+`name` or `endpoint` required. |
+| `timeout` | `float` | No | Request timeout in seconds (default: 30) |
+
+### call_mcp_tool()
+
+Call a tool on a remote MCP agent via JSON-RPC `tools/call`.
+
+```python
+from dns_aid.core.invoke import call_mcp_tool
+
+result = await call_mcp_tool(
+    endpoint="https://mcp.example.com/mcp",
+    tool_name="search_flights",
+    arguments={"origin": "SFO", "destination": "JFK"},
+)
+```
+
+### list_mcp_tools()
+
+List available tools on a remote MCP agent via JSON-RPC `tools/list`.
+
+```python
+from dns_aid.core.invoke import list_mcp_tools
+
+result = await list_mcp_tools(
+    endpoint="https://mcp.example.com/mcp",
+)
+```
+
+### resolve_a2a_endpoint()
+
+Resolve an A2A agent endpoint via DNS discovery and agent card fetch.
+
+```python
+from dns_aid.core.invoke import resolve_a2a_endpoint
+
+endpoint_url = await resolve_a2a_endpoint(
+    domain="ai.infoblox.com",
+    name="security-analyzer",
+)
+# Returns: "https://security-analyzer.ai.infoblox.com:443"
+```
+
+Resolution chain:
+1. DNS discovery (`discover(domain, protocol="a2a", name=name)`)
+2. Agent card fetch (`/.well-known/agent-card.json`) for canonical URL
+3. Host mismatch protection: if agent card URL hostname differs from DNS endpoint, DNS wins
+
+### InvokeResult
+
+Returned by all invocation functions.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `text` | `str \| None` | Extracted text from response |
+| `raw` | `dict \| None` | Full response payload |
+| `error` | `str \| None` | Error message if invocation failed |
+
+---
+
 ## SDK: Invocation & Telemetry
 
 The Tier 1 SDK provides agent invocation with automatic telemetry capture, and community-wide ranking queries.

docs/architecture.md

@@ -237,6 +237,87 @@ and gracefully skips hosts that don't serve `.well-known/agent-card.json`.
 
 ---
 
+## Invocation Layer (`core/invoke.py`)
+
+The invocation module is the single source of truth for agent communication.
+Both the CLI (`dns-aid message`, `dns-aid call`, `dns-aid list-tools`) and the
+MCP server (`send_a2a_message` tool) delegate to `core/invoke.py` instead of
+duplicating protocol logic.
+
+### Resolution Chain
+
+```
+send_a2a_message(domain="ai.infoblox.com", name="security-analyzer", message="...")
+│
+├─ 1. DNS Discovery
+│     discover(domain, protocol="a2a", name=name)
+│     → AgentRecord with endpoint_url
+│
+├─ 2. Agent Card Prefetch
+│     GET https://{endpoint_host}/.well-known/agent-card.json
+│     → canonical URL, name, description, skills
+│     │
+│     └─ Host mismatch check:
+│        card.url hostname != DNS endpoint hostname?
+│        YES → log warning, use DNS endpoint (DNS is authoritative)
+│        NO  → use agent card URL (may include path)
+│
+└─ 3. Invoke
+      POST {resolved_endpoint}
+      JSON-RPC 2.0: {"method": "message/send", "params": {...}}
+      → InvokeResult(text, raw, error)
+```
+
+### SDK vs Raw httpx Paths
+
+```
+invoke.py
+├─ SDK available? (dns_aid.sdk importable + AgentRecord available)
+│  YES → AgentClient.invoke(agent, method="message/send", ...)
+│         → telemetry capture, signal collection, ranking
+│         → InvokeResult from InvocationResult
+│
+└─ NO  → Raw httpx.AsyncClient POST
+          → JSON-RPC 2.0 envelope, manual response parsing
+          → InvokeResult from httpx.Response
+```
+
+The SDK path is preferred when available — it captures telemetry signals and
+feeds the ranking system. The raw httpx path exists as a fallback for minimal
+installations without the `[sdk]` extra.
+
+### Interface Delegation
+
+```
+┌──────────────────┐     ┌──────────────────┐
+│   CLI (Typer)    │     │   MCP Server     │
+│                  │     │                  │
+│ dns-aid message  │     │ send_a2a_message │
+│ dns-aid call     │     │ (MCP tool)       │
+│ dns-aid list-tools│    │                  │
+└────────┬─────────┘     └────────┬─────────┘
+         │                        │
+         └───────────┬────────────┘
+                     │
+              ┌──────▼──────┐
+              │ core/invoke │
+              │             │
+              │ send_a2a_message()    │
+              │ call_mcp_tool()      │
+              │ list_mcp_tools()     │
+              │ resolve_a2a_endpoint()│
+              └──────┬──────┘
+                     │
+         ┌───────────┴───────────┐
+         │                       │
+    ┌────▼─────┐          ┌──────▼──────┐
+    │ SDK path │          │ httpx path  │
+    │ (prefer) │          │ (fallback)  │
+    └──────────┘          └─────────────┘
+```
+
+---
+
 ## Community Rankings (Optional)
 
 The SDK can fetch community-wide telemetry rankings when a telemetry API is configured: