.png)
1 day ago
1
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
