feat(ve_identity): Add Identity Service integration with OAuth2, API Key and Workload authentication (#263)

* feat(ve_identity): Add Identity Service integration with OAuth2, API Key, and Workload authentication

This commit introduces a comprehensive integration with Identity Service,
enabling ADK agents to securely manage authentication and credentials.

## Key Features

### 1. Unified Authentication Framework
- **Three Authentication Types**:
  - OAuth2 (M2M and USER_FEDERATION flows)
  - API Key authentication
  - Workload access token authentication

- **Flexible Configuration**: Simple factory functions (`api_key_auth()`, `oauth2_auth()`, `workload_auth()`)
  for easy setup

### 2. Tool Integration
- **VeIdentityFunctionTool**: Funtion tool wrapper with built-in Identity authentication
- **VeIdentityMcpTool**: MCP tool wrapper with built-in Identity authentication
- **VeIdentityMcpToolset**: Complete MCP toolset management with automatic credential handling

### 3. Authentication Processing
- **AuthRequestProcessor**: Handles OAuth2 flows in agent conversations with support for:
  - Custom OAuth2 auth pollers
  - Callback URL handling
  - Token polling with configurable timeout
  - Mock auth poller for testing

- **Auth Mixins**: Reusable authentication logic (`VeIdentityAuthMixin`, `ApiKeyAuthMixin`,
  `OAuth2AuthMixin`, `WorkloadAuthMixin`) to avoid code duplication

### 4. Token Management
- **WorkloadTokenManager**: Manages workload access tokens with:
  - Automatic caching in session state
  - Token expiration handling
  - Support for JWT, user ID, and workload-only authentication modes
  - Automatic token refresh

### 5. Identity Client
- **IdentityClient**: Low-level async client for VolcEngine Identity Service API with:
  - OAuth2 credential provider management
  - API key credential provider management
  - Workload token retrieval
  - OAuth2 token and API key fetching
  - Dynamic Client Registration (DCR) support

### 6. Data Models
- **OAuth2TokenResponse**: Structured response for OAuth2 token requests
- **WorkloadToken**: Workload token with expiration tracking
- **OAuth2AuthPoller**: Abstract base for custom token polling implementations
- **DCR Models**: Support for RFC 7591 Dynamic Client Registration Protocol
- **Authorization Server Metadata**: RFC 8414 compliant metadata handling

### 7. Utility Functions
- **is_pending_auth_event()**: Detect pending authentication requests in ADK events
- **get_function_call_id()**: Extract function call IDs from auth events
- **get_function_call_auth_config()**: Extract auth configuration from events
- **generate_headers()**: Convert credentials to HTTP authentication headers

* fix(identity): refactor imports to use absolute paths in ve_identity

- Fix Non-standard docstrings
- Remove veadk prefix in logger

* chore(identity):fix type hints for tool_context in auth mixins

* feat: add unit tests for ve_identity tools and improve credential refresh

Add unit tests for ve_identity auth_config, function_tool, mcp_tool, and mcp_toolset modules. Updated IdentityClient credential refresh logic to support fallback to VeFaaS IAM credentials if environment variables are not set, improving robustness in cloud environments.

* feat(ve_identity): Add Agent Identity authentication docs

Introduces documentation for Agent Identity authentication, including product overview, API Key outbound, OAuth2 M2M outbound, and OAuth2 USER_FEDERATION outbound.

* feat(identity): Integrate VeIdentity config and region support

Added VeIdentityConfig to global settings and improved region handling for Agent Identity authentication. Updated configuration files and environment variable documentation.

* chore(ve_identity): Make OAuth2 flow and scopes parameters optional

Updated OAuth2-related classes and functions to make 'auth_flow' and 'scopes' parameters optional, allowing control plane defaults to be used if not provided.

* chore(ve_identity): Remove redundant logging from identity and token modules

Eliminated unnecessary logger.info statements from IdentityClient and WorkloadTokenManager to reduce log verbosity and improve clarity. No changes to core logic or functionality.

* refactor(ve_identity): introduce BaseRunProcessor to decouple Agent Identity dependency

## Problem
Agent class had a hard dependency on Agent Identity's AuthRequestProcessor,
causing all agents to depend on Agent Identity even when authentication is
not needed. This violates the Dependency Inversion Principle and could
break existing agents.

## Solution
Introduce an abstract processor layer following the Dependency Inversion
Principle:

1. Created `veadk/processors/` package with:
   - `BaseRunProcessor`: Abstract base class for runtime processors
   - `NoOpRunProcessor`: Default no-op implementation

2. Modified `veadk/agent.py`:
   - Added `run_processor: Optional[BaseRunProcessor]` field
   - Changed dependency from AuthRequestProcessor to BaseRunProcessor
   - Initialize with NoOpRunProcessor by default
   - Updated `run()` method parameter from `auth_request_processor` to `run_processor`

3. Updated `veadk/integrations/ve_identity/auth_processor.py`:
   - Made AuthRequestProcessor inherit from BaseRunProcessor
   - Renamed main method from `with_auth_loop` to `process_run`

* chore(ve_identity): Remove unused _NoOpAuthProcessor import and cleanup

Eliminated the unused _NoOpAuthProcessor import and reference from ve_identity/__init__.py. Also removed a trailing blank line in processors/__init__.py and added a missing comma in NoOpRunProcessor's decorator signature for consistency.

Author: loveyana

docs/content/2.configurations/1.system.md

@@ -44,8 +44,8 @@ model:
     # api_key: 
 
 volcengine:
-  access_key: 
-  secret_key: 
+  access_key:
+  secret_key:
 
 observability:
   opentelemetry:
@@ -70,6 +70,11 @@ database:
     region: cn-beijing
     bucket: 
 
+veidentity:
+  # Agent Identity 服务区域
+  region: cn-beijing
+  # 可选：自定义 Agent Identity 服务端点，不提供时自动生成
+
 logging:
   # ERROR
   # WARNING

docs/content/2.configurations/2.envs.md

@@ -105,3 +105,20 @@ volcengine:
 | 环境变量名称 | 释义 |
 | :- | :- |
 | `PROMPT_PILOT_API_KEY` | Prompt Pilot 产品密钥 |
+
+## Agent Identity 身份认证
+
+统一前缀： `VEIDENTITY_`
+
+| 环境变量名称 | 释义 |
+| :- | :- |
+| `VEIDENTITY_REGION` | Agent Identity 服务区域，默认 cn-beijing |
+| `VEIDENTITY_ENDPOINT` | Agent Identity 服务端点（可选，不提供时自动生成） |
+
+对应 `yaml` 文件格式：
+
+```yaml [config.yaml]
+veidentity:
+  region: cn-beijing
+  endpoint:  # 可选，不提供时自动生成
+```

docs/content/91.auth/.navigation.yml

@@ -0,0 +1 @@
+title: 认证与授权

docs/content/91.auth/1.agent-identity-intro.md

@@ -0,0 +1,96 @@
+---
+title: Agent Identity 产品介绍
+description: Agent Identity 身份认证产品的开通流程和作用
+navigation:
+  icon: i-lucide-shield-check
+---
+
+Agent Identity 是火山引擎提供的一站式身份及权限管理平台，负责用户身份验证、权限控制，确保 Agent 出、入操作的安全性与合规性。
+
+## 核心功能
+
+- **用户身份管理**：支持用户池管理、企业 IdP（SAML/OIDC）及第三方身份联合
+- **工作负载身份管理**：为 Agent/工具分配唯一数字身份，维护属性标签
+- **第三方凭据托管**：加密托管 API Key 和 OAuth 令牌，杜绝明文凭据泄露
+- **权限管控**：基于属性和上下文的动态授权，实现细粒度权限控制
+
+## 开通流程
+
+### 1. 访问 Agent Identity 控制台
+
+访问 **[Agent Identity](https://console.volcengine.com/identity)** 服务开通页，勾选 **同意服务条款**, 点击 **开通并授权**。
+
+### 2. 创建出站凭据提供商
+
+根据使用场景创建相应的出站凭据提供商：
+
+| 认证方式 | 提供商类型 | 使用场景 |
+|---------|----------|--------|
+| API Key | API Key | 服务间通信 |
+| OAuth2 M2M | OAuth Client | 后端服务间认证 |
+| OAuth2 USER_FEDERATION | OAuth Client | 用户委托认证 |
+
+### 3. 配置凭证信息
+
+根据认证方式配置相应的凭证（如 API Key、Client ID、Client Secret、回调 URL 等）。
+
+### 4. 快速使用
+
+```python
+from veadk.integrations.ve_identity import (
+    VeIdentityFunctionTool,
+    api_key_auth,
+)
+
+auth_config = api_key_auth(provider_name="my-provider")
+tool = VeIdentityFunctionTool(
+    func=my_function,
+    auth_config=auth_config,
+    into="api_key",
+)
+```
+
+## 常见问题
+
+**Q: 如何选择认证方式？**
+
+A:
+- **API Key**：简单、固定凭证，适合简单场景
+- **OAuth2 M2M**：安全、支持令牌过期和刷新，适合生产环境
+- **OAuth2 USER_FEDERATION**：用户授权，适合需要用户同意的场景
+
+**Q: 凭证会被暴露吗？**
+
+A: 不会。Agent Identity 会：
+- 加密存储凭证
+- 支持凭证自动轮换
+- 不在代码中暴露凭证
+
+**Q: 如何处理凭证过期？**
+
+A: Agent Identity 会自动处理：
+- 令牌缓存和刷新
+- 凭证自动轮换
+- 过期前自动更新
+
+## 后续步骤
+
+- [使用 API Key 进行出站认证](./2.api-key-outbound.md)
+- [使用 OAuth2 M2M 进行出站认证](./3.oauth2-m2m-outbound.md)
+- [使用 OAuth2 USER_FEDERATION 进行出站认证](./4.oauth2-user-federation-outbound.md)
+
+## 相关资源
+
+### Agent Identity 官方文档
+- [Agent Identity API 参考](https://www.volcengine.com/docs/86848/1918752)
+
+### 外部资源
+- [OAuth2 规范](https://tools.ietf.org/html/rfc6749)
+- [OpenID Connect](https://openid.net/connect/)
+
+## 获取帮助
+
+如有问题，请：
+1. 查看相应文档的常见问题部分
+2. 查看 [Agent Identity 官方文档](https://www.volcengine.com/docs/86848/1913964)
+3. 联系火山引擎技术支持

docs/content/91.auth/2.api-key-outbound.md

@@ -0,0 +1,98 @@
+---
+title: 使用 API Key 进行出站认证
+description: 通过 API Key 认证访问外部服务
+navigation:
+  icon: i-lucide-key
+---
+
+API Key 认证是最简单的出站认证方式，适用于服务间通信和固定凭证场景。
+
+## 创建 API Key 凭据
+
+1. 登录火山引擎控制台，导航到 **Agent Identity** 服务
+2. 在左侧导航树中，选择 **身份认证 > 出站凭据托管**
+3. 点击 **新建 > 新建 API Key**，填写 API Key 名称
+4. 输入第三方服务提供的 API Key
+5. 配置 API Key 传递方式（Header 或 Query）并点击 **确定**
+
+## 使用方式
+
+### VeIdentityFunctionTool
+
+```python
+from veadk.integrations.ve_identity import VeIdentityFunctionTool, api_key_auth
+import aiohttp
+
+async def call_api(api_key: str, endpoint: str):
+    headers = {"Authorization": f"Bearer {api_key}"}
+    async with aiohttp.ClientSession() as session:
+        async with session.get(endpoint, headers=headers) as resp:
+            return await resp.json()
+
+auth_config = api_key_auth(provider_name="my-api-provider")
+tool = VeIdentityFunctionTool(
+    func=call_api,
+    auth_config=auth_config,
+    into="api_key",
+)
+```
+
+### VeIdentityMcpToolset
+
+```python
+from veadk.integrations.ve_identity import VeIdentityMcpToolset, api_key_auth
+from google.adk.agents.mcp import StdioServerParameters
+
+auth_config = api_key_auth(provider_name="my-api-provider")
+toolset = VeIdentityMcpToolset(
+    auth_config=auth_config,
+    connection_params=StdioServerParameters(
+        command="python",
+        args=["-m", "my_api_mcp_server"],
+    ),
+)
+```
+
+## 示例
+
+```python
+import asyncio
+from veadk import Agent, Runner
+from veadk.integrations.ve_identity import VeIdentityFunctionTool, api_key_auth
+import aiohttp
+
+async def query_api(api_key: str, user_id: str):
+    headers = {"Authorization": f"Bearer {api_key}"}
+    url = f"https://api.example.com/users/{user_id}"
+    async with aiohttp.ClientSession() as session:
+        async with session.get(url, headers=headers) as resp:
+            return await resp.json()
+
+tool = VeIdentityFunctionTool(
+    func=query_api,
+    auth_config=api_key_auth(provider_name="user-api"),
+    into="api_key",
+)
+
+agent = Agent(tools=[tool])
+runner = Runner(agent=agent)
+asyncio.run(runner.run(messages="查询用户 123"))
+```
+
+## 常见问题
+
+**Q: 如何更新 API Key？**
+
+A: 在 Agent Identity 控制台中编辑凭证即可。
+
+**Q: 如何处理 API 调用失败？**
+
+A: 实现错误处理和重试逻辑。
+
+## 相关资源
+
+- [Agent Identity 产品介绍](./1.agent-identity-intro.md)
+- [OAuth2 M2M 认证](./3.oauth2-m2m-outbound.md)
+- [OAuth2 USER_FEDERATION 认证](./4.oauth2-user-federation-outbound.md)
+- [Agent Identity API 参考](https://www.volcengine.com/docs/86848/1918752)
+

docs/content/91.auth/3.oauth2-m2m-outbound.md

@@ -0,0 +1,116 @@
+---
+title: 使用 OAuth2 M2M 进行出站认证
+description: 通过 OAuth2 M2M 认证进行机器对机器通信
+navigation:
+  icon: i-lucide-network
+---
+
+OAuth2 M2M（Machine to Machine）认证用于服务间通信，比 API Key 更安全且支持令牌刷新。
+
+## 创建 OAuth2 M2M 凭据
+
+### 基础步骤
+
+1. 登录火山引擎控制台，导航到 **Agent Identity** 服务
+2. 在左侧导航树中，选择 **身份认证 > 出站凭据托管 > OAuth Client**
+3. 点击 **新建 > 新建 OAuth Client**
+4. 在 **OAuth2 流程** 中选择 **机器对机器（M2M）**
+5. 点击 **确定** 完成创建
+
+### 方式一：使用内置 Vendor（推荐）
+
+选择提供商类型：**Lark**、**Coze**、**Google**、**GitHub** ，填写：
+- Client ID
+- Client Secret
+
+### 方式二：使用 OIDC 配置
+
+选择提供商类型为 **自定义**，填写：
+- 发行者 URL：OIDC 提供商的 Discovery URL（如 `https://accounts.google.com/.well-known/openid-configuration`）
+- Client ID
+- Client Secret
+- 权限范围：至少包含 `openid`
+
+### 方式三：使用自定义 OAuth2 配置
+
+选择提供商类型为 **自定义**，填写：
+- Client ID
+- Client Secret
+- 权限范围
+- Issuer
+- 授权端点
+- 令牌端点
+
+## 使用方式
+
+### VeIdentityFunctionTool
+
+```python
+from veadk.integrations.ve_identity import VeIdentityFunctionTool, oauth2_auth
+import aiohttp
+
+async def call_service(access_token: str, endpoint: str):
+    headers = {"Authorization": f"Bearer {access_token}"}
+    async with aiohttp.ClientSession() as session:
+        async with session.get(endpoint, headers=headers) as resp:
+            return await resp.json()
+
+auth_config = oauth2_auth(
+    provider_name="my-oauth2-m2m-provider",
+    scopes=["api://your-service/.default"],
+    auth_flow="M2M",
+)
+tool = VeIdentityFunctionTool(
+    func=call_service,
+    auth_config=auth_config,
+)
+```
+
+### VeIdentityMcpToolset
+
+```python
+from veadk.integrations.ve_identity import VeIdentityMcpToolset, oauth2_auth
+from google.adk.agents.mcp import StdioServerParameters
+
+auth_config = oauth2_auth(
+    provider_name="my-oauth2-m2m-provider",
+    scopes=["api://your-service/.default"],
+    auth_flow="M2M",
+)
+toolset = VeIdentityMcpToolset(
+    auth_config=auth_config,
+    connection_params=StdioServerParameters(
+        command="python",
+        args=["-m", "my_service_mcp_server"],
+    ),
+)
+```
+
+## 常见问题
+
+**Q: OAuth2 M2M 和 API Key 有什么区别？**
+
+A: API Key 简单固定，OAuth2 M2M 更安全且支持令牌刷新。
+
+**Q: 令牌过期了怎么办？**
+
+A: Agent Identity 会自动刷新令牌。
+
+**Q: 如何配置多个 Scopes？**
+
+A: 
+```python
+auth_config = oauth2_auth(
+    provider_name="my-provider",
+    scopes=["api://service1/.default", "api://service2/.default"],
+    auth_flow="M2M",
+)
+```
+
+## 相关资源
+
+- [Agent Identity 产品介绍](./1.agent-identity-intro.md)
+- [API Key 认证](./2.api-key-outbound.md)
+- [OAuth2 USER_FEDERATION 认证](./4.oauth2-user-federation-outbound.md)
+- [Agent Identity API 参考](https://www.volcengine.com/docs/86848/1918752)
+