feat(agent): modernize headless_agent_auth sample for a2a-sdk v0.3.x

[williamsmt]

This PR updates the headless_agent_auth sample to align with the latest a2a-sdk (v0.3.x) standards and improves agent observability.

Key Changes:

• Modernized Security: Refactored AgentCard to use the new security and security_schemes fields, replacing the deprecated authentication object.
• Enhanced Streaming: Updated agent.py to use updates stream mode, providing better visibility into intermediate tool steps and structured responses.
• Improved Test Client: Overhauled test_client.py with robust OAuth2 token resolution, improved timeout handling, and cleaner output for streaming events.
• SDK Alignment: Upgraded a2a-sdk dependency to v0.3.23 with the [http-server] extra and updated middleware to support the new well-known/agent-card.json endpoint.

• Follow the CONTRIBUTING Guide.

Fixes #409 🦕

[gemini-code-assist]

Summary of Changes

Hello @williamsmt, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request modernizes the headless_agent_auth sample to be fully compatible with a2a-sdk v0.3.x. The changes primarily focus on updating the agent's security configuration to use the new security_schemes model, enhancing the streaming capabilities for better real-time observability, and refining the test client for improved token resolution and stream handling. These updates ensure the sample leverages the latest SDK features and provides a more robust and informative user experience.

Highlights

• Modernized Security Configuration: The AgentCard now utilizes the new security and security_schemes fields, replacing the deprecated authentication object for defining OAuth2 client credentials flows. This aligns the sample with the latest a2a-sdk standards.
• Enhanced Streaming for Agent Observability: The agent's streaming mechanism has been updated to use the updates stream mode, providing more granular visibility into intermediate tool steps and structured responses during task execution. This allows for real-time feedback on the agent's thought process.
• Improved Test Client Functionality: The test_client.py has been significantly refactored to robustly resolve OAuth2 tokens from the new security_schemes structure, handle streaming events with clearer output, and implement a more resilient HTTPX timeout configuration for long-running streams.
• SDK Dependency Alignment and Middleware Update: The a2a-sdk dependency has been upgraded to v0.3.23 and now includes the [http-server] extra. The OAuth2 middleware has been updated to support the new /.well-known/agent-card.json endpoint, ensuring proper agent discovery.

Changelog

• samples/python/agents/headless_agent_auth/main.py
  • Removed deprecated AgentAuthentication import and related code.
  • Updated AgentCard instantiation to use a dictionary-based configuration with security_schemes and security fields.
  • Added /.well-known/agent-card.json to the OAuth2 middleware's public paths.
• samples/python/agents/headless_agent_auth/agent.py
  • Changed astream method's stream_mode from values to updates.
  • Implemented new logic to process stream chunks, distinguishing between AIMessage, ToolMessage, and structured response nodes for improved output.
• samples/python/agents/headless_agent_auth/agent_executor.py
  • Modified TaskStatusUpdateEvent to include the agent's text message within the status object.
• samples/python/agents/headless_agent_auth/oauth2_middleware.py
  • Refactored the middleware's initialization to parse security and security_schemes from the AgentCard instead of the deprecated authentication field.
• samples/python/agents/headless_agent_auth/pyproject.toml
  • Updated the a2a-sdk dependency to include the [http-server] extra.
• samples/python/agents/headless_agent_auth/test_client.py
  • Rewrote the auth_flow method to correctly extract token_url from the new security_schemes structure.
  • Configured httpx.AsyncClient with a robust timeout, allowing streams to remain open indefinitely.
  • Improved stream event processing in complete_task to capture task_id and extract meaningful text from various event types.
  • Made task_id an optional parameter in cli and complete_task functions.
• samples/python/agents/headless_agent_auth/uv.lock
  • Updated a2a-sdk to version 0.3.23 and added the http-server extra.
  • Removed opentelemetry-sdk and opentelemetry-semantic-conventions dependencies.
  • Updated sse-starlette to version 3.0.3.
  • Adjusted Python version markers for langchain-core, langgraph, langgraph-prebuilt, and langgraph-sdk from < '4.0' to < '4'.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request does an excellent job of modernizing the headless_agent_auth sample to align with a2a-sdk v0.3.x. The transition from the deprecated authentication field to the new security and security_schemes in the AgentCard is well-executed. The updates to the streaming implementation in both agent.py and test_client.py are significant improvements, enhancing robustness and observability by leveraging the updates stream mode and properly handling intermediate steps. The dependency upgrades and middleware adjustments are also correctly implemented. I have a few minor suggestions to enhance code cleanliness and consistency, but overall, this is a high-quality and valuable update.