Feature: Add Agent-to-Agent (A2A) Protocol Support with AgentCardBuilder

[Kunmeer-SyedMohamedHyder]

Summary

This PR adds comprehensive support for the Agent-to-Agent (A2A) protocol by introducing the AgentCardBuilder class and associated documentation. This implementation serves as the foundational boilerplate code for all future A2A integrations within the OpenAI Agents SDK, providing a standardized way for agents to describe their capabilities and participate in agent-to-agent communication protocols.

The AgentCardBuilder enables agents to generate standardized agent cards that describe their capabilities, skills, and metadata for interoperability with A2A servers and other agent systems, establishing the core infrastructure needed for broader A2A ecosystem integration.

Key features:

• AgentCardBuilder: A builder class that converts Agent configurations into structured AgentCard objects
• Comprehensive skill extraction: Automatically extracts skills from agent tools, handoffs, and orchestration capabilities
• A2A protocol compliance: Generates cards compatible with A2A server well-known paths (/.well-known/agent.json)
• Hierarchical agent support: Handles complex agent hierarchies with proper skill deduplication and circular dependency protection
• Configurable capabilities: Supports custom agent capabilities, input/output modes, and metadata
• Foundation for future A2A features: Provides the base infrastructure for expanding A2A protocol support

Test plan

• Comprehensive test suite: All 30 existing tests in test_agent_card_builder.py pass
• Integration testing: Verified agent card creation with real agents containing tools and handoffs
• A2A protocol testing: Confirmed integration with a2a.utils constants for well-known paths
• Type safety: All mypy type checks pass
• Code quality: All ruff linting checks pass
• Dependency management: Tested optional a2a dependency installation and usage

The functionality has been tested with:

• Simple agents with tools
• Complex agent hierarchies with handoffs
• Various capability configurations
• Serialization and protocol compliance
• Integration with A2A server paths

Checks

• I've added new tests (if relevant) - 30 comprehensive tests already exist and pass
• I've added/updated the relevant documentation - Added complete a2a.md documentation and updated agents.md
• I've run make lint and make format - All ruff and mypy checks pass
• I've made sure tests pass - All 30 tests pass successfully

Changes Made

Core Implementation:

• Added AgentCardBuilder class in src/agents/agent_card_builder.py as foundational A2A infrastructure
• Supports tool skill extraction, handoff capabilities, and orchestration skill generation
• Handles complex agent hierarchies with circular dependency protection
• Automatic skill deduplication across agent networks

Documentation:

• Created comprehensive docs/a2a.md with A2A protocol documentation
• Added installation instructions for optional a2a dependency
• Included basic usage, advanced configuration, and integration examples
• Updated docs/agents.md with A2A protocol reference
• Added a2a.md to navigation in mkdocs.yml

Dependencies:

• Added a2a = ["a2a-sdk>=0.2.16; python_version >= '3.10'"] optional dependency in pyproject.toml
• Supports Python 3.10+ for A2A features while maintaining 3.9+ compatibility for core framework

Features:

• Tool Skills: Direct mapping from agent tools to AgentSkill objects
• Handoff Skills: Extraction of capabilities from handoff agents
• Orchestration Skills: High-level coordination capability descriptions
• Capability Configuration: Support for custom input/output modes and streaming
• A2A Protocol Compliance: Integration with well-known paths for agent discovery
• Async Operations: All card building operations are async for performance
• Extensible Architecture: Designed as the foundation for future

[seratch]

Hi @Kunmeer-SyedMohamedHyder, thanks for sending this pull request. However, we don't have immediate plans to add A2A support to this SDK. We can't say if or when we'll review it. For future major contributions, it would be appreciated if you could start with an issue for discussion first.

[Kunmeer-SyedMohamedHyder]

Hey @seratch ! Sure thing. I have been using it in my local for quite a time. Thought to push it. It can be marked as draft. However will start a discussion around it and community can participate. Thank you for the input!