[Feature] Semantic Agent Discovery — Search API + MCP Tool

[madhuv30]

Summary

Add semantic/hybrid search capability to the A2A agent registry with two access patterns:

1. REST API — search endpoint for UI, scripts, and direct API consumers
2. MCP tool — so any MCP-connected agent or app can discover agents as part of its tool chain

Problem

Current agent discovery is limited to:

• GET /v1/agents — returns full list, requires manual scanning
• GET /a2a/{agent_id}/.well-known/agent-card.json — requires knowing the exact agent ID

As the number of registered agents grows, finding the right agent becomes increasingly difficult. There is no way to search by capability, skill description, or intent.

For agentic workflows this is a bigger gap — an orchestrator agent has no programmatic way to ask "which agent can help with X?" before routing a task.

---

Proposed Solution

1. REST Endpoint

Hybrid search (semantic + keyword) over agent metadata — names, descriptions, skills, tags, input/output modes.

Sample endpoint and response below — schema is illustrative and can be extended based on implementation needs.

GET /v1/agents/search?q=translate+a+PDF+document&limit=5

{
  "results": [
    {
      "agent_id": "abc-123",
      "agent_name": "clinical-summarizer",
      "description": "Summarizes clinical trial protocols and results",
      "score": 0.92,
      "matching_skills": ["protocol-summary", "results-extraction"]
    }
  ]
}

2. MCP Tool — search_agents

Expose the same search as an MCP tool so any MCP-connected agent or application can discover agents programmatically.

Sample tool definition below — schema is illustrative and can be extended based on implementation needs.

{
  "name": "search_agents",
  "description": "Search registered A2A agents by natural language query.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "Natural language search query" },
      "limit": { "type": "integer", "default": 5 }
    },
    "required": ["query"]
  }
}

This enables patterns like:

• An orchestrator uses search_agents as a planning step before delegating sub-tasks
• The UI calls the MCP tool for its search bar
• A coding assistant finds a "code review" agent, then calls it via A2A

---

Reference Implementation

AWS Bedrock AgentCore Agent Registry provides search and MCP access:

• Hybrid search (semantic + keyword): https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/registry-key-capabilities.html#registry-hybrid-search
• Search API: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/registry-searching.html
• MCP endpoint: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/registry-key-capabilities.html#registry-mcp-endpoint

---

Scope

• Hybrid search backend (semantic + keyword) over agent card fields
• ACL-aware — search results filtered by caller's agent permissions
• Results ranked by relevance score
• Two access patterns (REST + MCP) sharing the same search backend

Impact

• Improves agent discoverability as the registry scales
• Enables agentic orchestration patterns (agents finding other agents)
• Aligns with AWS Agent Registry search + MCP capabilities