feat(a2a): Add A2A authentication middleware with TIP token propagation support (#304)

* feat: add run_processor support for Agent Runner

1. **Runner run_processor support**
   - Add `run_processor` parameter to Runner.__init__() and Runner.run()
   - Support multiple sources with priority: run() arg > __init__ arg > agent.run_processor > NoOpRunProcessor

2. **Fix IdentityClient region initialization**
   - Change default region from hardcoded "cn-beijing" to None in WorkloadTokenManager
   - Auto-detect region using _get_default_region() when not specified
   - Import _get_default_region from auth_config module

Changes:
- veadk/runner.py: Add run_processor support with priority chain
- veadk/integrations/ve_identity/token_manager.py: Fix region initialization
- veadk/integrations/ve_identity/auth_mixins.py: Minor formatting fix

* feat(a2a): add credential service and auto auth token injection

This commit introduces comprehensive authentication support for A2A (Agent-to-Agent)
communication, enabling secure credential management and automatic token injection.

Key Changes:

1. **VeCredentialStore** (veadk/a2a/credentials.py)
   - Implement custom credential store with user ID and session ID support
   - Support both synchronous and asynchronous credential operations
   - Prioritize user ID over session ID for credential retrieval

2. **AuthenticatedA2ARequestConverter** (veadk/a2a/ve_request_converter.py)
   - Extract JWT tokens from Authorization headers
   - Parse user ID from JWT payload (sub field)

3. **RemoteVeAgent** (veadk/a2a/remote_ve_agent.py)
   - Add credential_service parameter to constructor
   - Implement _run_async_impl with automatic auth token injection
   - Inject Bearer tokens into httpx client headers before requests
   - Add comprehensive error handling and logging

4. **VeA2AServer** (veadk/a2a/ve_a2a_server.py)
   - Add credential_service parameter to constructor
   - Integrate with AuthenticatedA2ARequestConverter

5. **Unit Tests** (tests/)
   - Add comprehensive test coverage for VeCredentialStore
   - Add tests for AuthenticatedA2ARequestConverter
   - All tests passing with proper fixtures and mocking

Benefits:
- Seamless authentication for remote agent calls
- Automatic credential propagation across agent boundaries
- Support for both session-based and user-based authentication
- Clean separation of concerns with dedicated credential service

Breaking Changes:
- None (backward compatible - credential_service is optional)

Related: A2A authentication and secure agent communication

* revert

* revert

* feat: Add A2A authentication middleware with TIP token propagation support

- Add A2AAuthMiddleware for extracting auth tokens from requests
- Support both Authorization header and query string authentication methods
- Implement TIP (Trust Identity Propagation) token exchange via IdentityClient
- Add VeCredentialService integration for credential storage and retrieval
- Support workload token generation and propagation in request scope
- Add RemoteVeAgent with automatic credential injection from context
- Enhance credential service with ADK BaseCredentialService interface
- Add comprehensive test coverage for middleware and credential service

Key features:
* Extract JWT tokens and delegation chains from incoming requests
* Exchange TIP tokens for workload access tokens using IdentityClient
* Store credentials in credential service with app_name and user_id scoping
* Inject authentication tokens into remote agent HTTP clients at runtime
* Support multiple authentication methods (header/querystring)

This enables secure A2A communication with automatic credential propagation
across the Volcengine Agent runtimes.

* feat(identity): add unit test for middleware and credential service

* fix tests

* Update test_ve_a2a_middlewares.py

* Make credential_service parameter optional

Updated the VeA2AServer constructor and init_app function to allow credential_service to be optional by defaulting it to None. This increases flexibility for cases where credentials are not required.

* Fix example class name in docstrings

Replaces incorrect 'VeA2ACredentialService' with 'VeCredentialService' in usage examples within docstrings to ensure accuracy and prevent confusion for users.

* Initialize token variable in A2AAuthMiddleware

Added explicit initialization of the 'token' variable to None in the _extract_token method to ensure it is always defined before use.

* Update docstring examples to use lowercase type values

Changed the example values for 'Type' in the docstring of the permission check method to use lowercase (e.g., 'user', 'action', 'agent') for consistency and clarity.

* Fix type annotation for _identity_client in auth config

Updated the type annotation for _identity_client to use Optional["IdentityClient"] for better type clarity. Also removed unnecessary whitespace in ve_middlewares.py.

* Add VeADK A2A auth switch and utility enhancements

Introduces a new `to_a2a` utility in `veadk.a2a.utils.agent_to_a2a` to wrap Google ADK's A2A conversion with optional VeADK authentication and credential service integration. Adds comprehensive tests for the auth switch, refactors `RemoteVeAgent` to ensure pre-run initialization/auth logic always executes, and renames `credential_service.py` to `ve_credential_service.py` for clarity.

* Remove unused test and fix import formatting

Deleted test_to_a2a_auth_switch.py as it is no longer needed. Fixed import formatting in several files for consistency by removing extra spaces. Also removed an unused import in identity_client.py.

* Update A2A agent docs with authentication instructions

Added detailed instructions for enabling and configuring authentication in VeADK A2A Server, including server and client usage, supported authentication methods, and new parameters for the to_a2a function.

Author: loveyana

docs/content/3.agent/2.a2a-agent.md

@@ -18,7 +18,7 @@ navigation:
 我们将借助 Google ADK 的工具函数来便捷地创建一个 A2A Server：
 
 ```python [server_agent.py]
-from google.adk.a2a.utils.agent_to_a2a import to_a2a
+from veadk.a2a.utils.agent_to_a2a import to_a2a
 from veadk import Agent
 from veadk.tools.demo_tools import get_city_weather
 
@@ -27,6 +27,10 @@ agent = Agent(name="weather_reporter", tools=[get_city_weather])
 app = to_a2a(agent)
 ```
 
+::callout{icon="i-lucide-info"}
+默认情况下，A2A Server 不启用认证功能。如果需要启用 VeADK 的认证和凭据管理功能，请参考下面的 [启用认证功能](#启用认证功能) 章节。
+::
+
 ### 本地启动 A2A Server
 
 ```bash [Terminal]
@@ -51,8 +55,51 @@ print(response) # 北京天气晴朗，气温25°C。
 
 ::
 
+## 启用认证功能
+
+VeADK 提供了内置的认证和凭据管理功能，可以在 A2A Server 和 Client 之间进行安全的身份验证和凭据传递。
+
+### Server 侧启用认证
+
+在创建 A2A Server 时，通过设置 `enable_auth=True` 来启用认证功能：
+
+```python [server_agent.py]
+from veadk.a2a.utils.agent_to_a2a import to_a2a
+from veadk import Agent
+from veadk.tools.demo_tools import get_city_weather
+
+agent = Agent(name="weather_reporter", tools=[get_city_weather])
+
+# 启用 VeADK 认证功能
+app = to_a2a(agent, enable_auth=True)
+```
+
+启用认证后，Server 会：
+- 自动创建 `VeCredentialService` 来管理凭据
+- 添加认证中间件来验证请求中的 token
+- 支持凭据在 Server 和 Client 之间的安全传递
+
+### 认证方式
+
+`to_a2a` 支持两种认证方式，通过 `auth_method` 参数指定：
+
+```python
+# 方式 1: 从 HTTP Header 中提取 token (默认)
+app = to_a2a(agent, enable_auth=True, auth_method="header")
+
+# 方式 2: 从 Query String 中提取 token
+app = to_a2a(agent, enable_auth=True, auth_method="querystring")
+```
+
+
+### Client 侧使用认证
+
+当 Server 启用认证后，Client 侧的 `RemoteVeAgent` 会**自动处理认证**
+
 ## 初始化选项
 
+### RemoteVeAgent 参数
+
 ::field-group
   ::field{name="name" type="string"}
   智能体的名称
@@ -62,3 +109,41 @@ print(response) # 北京天气晴朗，气温25°C。
   远程智能体的访问端点
   ::
 ::
+
+### to_a2a 参数
+
+::field-group
+  ::field{name="agent" type="BaseAgent" required}
+  要转换为 A2A Server 的智能体实例
+  ::
+
+  ::field{name="host" type="string" default="localhost"}
+  A2A Server 的主机地址
+  ::
+
+  ::field{name="port" type="int" default="8000"}
+  A2A Server 的端口号
+  ::
+
+  ::field{name="protocol" type="string" default="http"}
+  A2A Server 的协议（http 或 https）
+  ::
+
+  ::field{name="agent_card" type="AgentCard | string"}
+  可选的智能体卡片对象或 JSON 文件路径。如果不提供，将自动从智能体生成
+  ::
+
+  ::field{name="runner" type="Runner"}
+  可选的 Runner 对象。如果不提供，将自动创建默认 Runner
+  ::
+
+  ::field{name="enable_auth" type="bool" default="false"}
+  是否启用 VeADK 认证功能。启用后会添加凭据服务和认证中间件
+  ::
+
+  ::field{name="auth_method" type="'header' | 'querystring'" default="header"}
+  认证方式。仅在 `enable_auth=True` 时有效
+  - `header`: 从 Authorization header 中提取 token
+  - `querystring`: 从 query parameter 中提取 token
+  ::
+::