[FEATURE]: Implement vendor-specific adapters for A2A Agent Types (OpenAI, Anthropic) with UI interactive help

[crivetimihai]

Summary

The A2A Agent catalog currently shows "Agent Type" options (Generic, OpenAI, Anthropic, Custom) in the Admin UI, but selecting OpenAI or Anthropic does not actually work - no vendor-specific API translation is implemented.

Current Behavior

The agent_type field only controls whether JSONRPC or a custom A2A envelope is used:

# mcpgateway/services/a2a_service.py:1437-1442
if agent_type in ["generic", "jsonrpc"] or agent_endpoint_url.endswith("/"):
    request_data = {"jsonrpc": "2.0", "method": "message/send", ...}
else:
    request_data = {"interaction_type": ..., "parameters": ..., "protocol_version": ...}

agent_type	Request Format	Vendor-Specific Mapping
generic	JSONRPC 2.0	None
openai	Custom A2A	None (broken!)
anthropic	Custom A2A	None (broken!)
custom	Custom A2A	None

Problem: Selecting openai or anthropic sends a custom A2A envelope that OpenAI/Anthropic APIs will reject with 4xx errors.

Expected Behavior

When agent_type=openai, the gateway should translate to OpenAI Chat Completions API format:

{
  "model": "gpt-4",
  "messages": [{"role": "user", "content": "..."}]
}

When agent_type=anthropic, the gateway should translate to Anthropic Messages API format:

{
  "model": "claude-sonnet-4-20250514",
  "messages": [{"role": "user", "content": "..."}]
}

Proposed Solution

Implement an adapter pattern for agent types:

Backend Changes

• Create AgentType enum to constrain valid values
• Create adapter interface (mcpgateway/services/adapters/base.py)
• Implement OpenAIAdapter - translates to/from Chat Completions API
• Implement AnthropicAdapter - translates to/from Messages API
• Implement GenericAdapter - current JSONRPC behavior
• Implement CustomAdapter - current custom A2A behavior
• Update a2a_service.py and tool_service.py to use adapters
• Update Pydantic schemas to use enum with validation

UI Changes

• Add descriptions/tooltips explaining each agent type
• Add conditional fields based on agent type (e.g., model selection for OpenAI/Anthropic)
• Show expected endpoint format for each type
• Add validation feedback for incomplete configurations

Documentation

• Update docs/docs/using/agents/a2a.md with accurate capabilities
• Add configuration examples for each agent type

Tests

• Unit tests for each adapter
• Integration tests with mock vendor APIs

Context

• agent_type is a ContextForge-specific extension, not part of the A2A spec
• Investigation details: todo/a2a-investigation.md
• Related files:
  • mcpgateway/services/a2a_service.py:1437-1442
  • mcpgateway/services/tool_service.py:4108-4132
  • mcpgateway/templates/admin.html:6646-6649
  • mcpgateway/schemas.py:4181
  • mcpgateway/db.py:4474

Alternatives Considered

Option B: Remove unsupported options - Remove OpenAI/Anthropic from UI, keep only Generic/Custom. Simpler but reduces functionality.

Option C: Plugin system - Make adapters pluggable for extensibility. More complex but future-proof.

Labels

enhancement, a2a, admin-ui