Feat: Add session3 (volcengine#69)

Author: yaozheng-fang

01-tutorials/workshop/session3/.env.template

@@ -0,0 +1,10 @@
+ADK_OAUTH2_USERPOOL_UID=
+ADK_OAUTH2_CLIENT_ID=
+ADK_OAUTH2_CLIENT_SECRET=
+ADK_OAUTH2_CALLBACK_URL=
+ADK_OAUTH2_SCOPE="openid profile"
+RUNTIME_IAM_ROLE_TRN=
+VOLCENGINE_ACCESS_KEY=
+VOLCENGINE_SECRET_KEY=
+DATABASE_VIKING_BASE_URL=
+ADAPTIVE_PERMISSION_SERVICE_KEY=

01-tutorials/workshop/session3/.pre-commit-config.yaml

@@ -0,0 +1,10 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v3.2.0
+    hooks:
+    -   id: trailing-whitespace
+    -   id: end-of-file-fixer
+    -   id: check-yaml
+    -   id: check-added-large-files

01-tutorials/workshop/session3/E3_lark_doc/agent.py

@@ -0,0 +1,137 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Any
+
+from veadk import Agent
+import json
+
+import lark_oapi as lark
+from lark_oapi.api.docx.v1 import (
+    RawContentDocumentRequest,
+    RawContentDocumentResponse,
+)
+from lark_oapi.core.model import RequestOption
+from veadk.integrations.ve_identity import (
+    VeIdentityFunctionTool,
+    AuthRequestProcessor,
+    oauth2_auth,
+)
+from google.adk.tools.function_tool import FunctionTool
+from google.adk.tools.tool_context import ToolContext
+from veadk.integrations.ve_identity.auth_mixins import OAuth2AuthMixin
+from veadk.memory.short_term_memory import ShortTermMemory
+
+short_term_memory = ShortTermMemory(backend="local")
+
+
+async def lark_document_query(document_id: str, *, access_token: str) -> str:
+    """
+    查询飞书文档内容
+
+    Args:
+        document_id: 飞书文档ID（从文档链接中提取的最后一部分）
+        access_token: 飞书 API OAuth2.0 访问令牌
+
+    Returns:
+        文档内容的JSON字符串
+    """
+    try:
+        print(f"查询飞书文档: {document_id}")
+        print(f"使用访问令牌: {access_token[:8]}...")
+
+        client = (
+            lark.Client.builder()
+            .enable_set_token(True)
+            .log_level(lark.LogLevel.INFO)
+            .build()
+        )
+        request: RawContentDocumentRequest = (
+            RawContentDocumentRequest.builder().lang(0).document_id(document_id).build()
+        )
+
+        response: RawContentDocumentResponse = client.docx.v1.document.raw_content(
+            request, RequestOption.builder().user_access_token(access_token).build()
+        )
+
+        if not response.success():
+            lark.logger.error(
+                f"client.docx.v1.document.raw_content failed, code: {response.code}, msg: {response.msg}, log_id: {response.get_log_id()}, resp: \n{json.dumps(json.loads(response.raw.content), indent=4, ensure_ascii=False)}"
+            )
+            return f"文档查询失败: {response.msg}"
+
+        # 处理业务结果
+        return lark.JSON.marshal(response.data, indent=4)
+
+    except Exception as e:
+        return f"文档查询出错: {str(e)}"
+
+
+# 创建使用 OAuth2 认证的飞书文档查询工具
+lark_doc_tool = VeIdentityFunctionTool(
+    func=lark_document_query,
+    auth_config=oauth2_auth(
+        provider_name="feishu",
+        auth_flow="USER_FEDERATION",
+    ),
+)
+
+
+async def clean_state(args: dict[str, Any], *, tool_context: ToolContext) -> None:
+    """Clean user's Oauth identity state.
+
+    Args:
+        args: fixed arguments for cleaning identity state: {"op": "clean"}
+    """
+    oauth_client = OAuth2AuthMixin(
+        provider_name="feishu",
+        auth_flow="USER_FEDERATION",
+        force_authentication=True,
+    )
+    await oauth_client._get_oauth2_token_or_auth_url(tool_context=tool_context)
+    return None
+
+
+clean_state_tool = FunctionTool(clean_state)
+
+agent: Agent = Agent(
+    name="lark_doc",
+    tools=[lark_doc_tool, clean_state_tool],
+    run_processor=AuthRequestProcessor(),
+    instruction="""您是一个智能飞书文档助手，能够帮助用户查询和分析飞书文档内容。当用户提供飞书文档链接或询问文档相关问题时，您需要：
+
+1. 识别用户消息中的飞书文档链接（格式如：https://feishu.feishu.cn/docx/WtwHdAngzoEU9IxyfhtcYsHCnDe）
+2. 提取文档ID（链接最后一部分，如：WtwHdAngzoEU9IxyfhtcYsHCnDe）
+3. 使用 lark_document_query 函数获取文档内容
+4. 基于文档内容回答用户的问题或提供分析
+
+功能特点：
+- 自动识别飞书文档链接并提取文档ID
+- 获取完整的文档内容数据
+- 基于文档内容进行智能分析和回答
+- 支持各种文档相关的查询和讨论
+
+使用示例：
+- "帮我看看这个文档：https://feishu.feishu.cn/docx/WtwHdAngzoEU9IxyfhtcYsHCnDe"
+- "这个文档的主要内容是什么？"
+- "总结一下文档中的要点"
+- "根据文档内容，给我一些建议"
+
+请用专业、友好的语气帮助用户理解和分析文档内容，并根据文档信息提供有价值的见解和建议。
+
+如果用户想清理自己的身份凭据，你可以调用 clean_state_tool 工具。
+""",
+)
+
+root_agent = agent

01-tutorials/workshop/session3/E4_volc_ops/agent.py

@@ -0,0 +1,68 @@
+from typing import Any
+from google.adk.planners import BuiltInPlanner
+from google.adk.tools.mcp_tool.mcp_toolset import (
+    StreamableHTTPConnectionParams,
+)
+from google.genai import types
+from veadk import Agent
+from veadk.config import getenv
+from veadk.integrations.ve_identity import (
+    VeIdentityMcpToolset,
+    IdentityClient,
+    oauth2_auth,
+    AuthRequestProcessor,
+)
+from veadk.config import settings
+from google.adk.tools.function_tool import FunctionTool
+from google.adk.tools.tool_context import ToolContext
+from veadk.integrations.ve_identity.auth_mixins import OAuth2AuthMixin
+
+identity_client = IdentityClient(region=settings.veidentity.region)
+
+# 创建 ECS MCP Tool
+mcp_ecs = VeIdentityMcpToolset(
+    auth_config=oauth2_auth(
+        provider_name="ecs-oauth-provider",
+        auth_flow="USER_FEDERATION",
+        identity_client=identity_client,
+    ),
+    connection_params=StreamableHTTPConnectionParams(
+        url=getenv("ECS_MCP_URL", "https://ecs.mcp.volcbiz.com/ecs/mcp"),
+        timeout=30.0,
+    ),
+)
+
+
+async def clean_state(args: dict[str, Any], *, tool_context: ToolContext) -> None:
+    """Clean user's Oauth identity state.
+
+    Args:
+        args: fixed arguments for cleaning identity state: {"op": "clean"}
+    """
+    oauth_client = OAuth2AuthMixin(
+        provider_name="ecs-oauth-provider",
+        auth_flow="USER_FEDERATION",
+        force_authentication=True,
+    )
+    await oauth_client._get_oauth2_token_or_auth_url(tool_context=tool_context)
+    return None
+
+
+clean_state_tool = FunctionTool(clean_state)
+
+# 创建独立的 ECS Agent
+ecs_agent: Agent = Agent(
+    name="ecs_agent",
+    description="ECS 运维智能体",
+    instruction="你是一个 ECS 云服务器运维专家, 你可以使用 ECS 工具来管理云服务器，如果用户想清理自己的身份凭据，你可以调用 clean_state_tool 工具。",
+    tools=[mcp_ecs, clean_state_tool],
+    planner=BuiltInPlanner(
+        thinking_config=types.ThinkingConfig(
+            include_thoughts=True,
+            thinking_budget=1024,
+        )
+    ),
+    run_processor=AuthRequestProcessor(),
+)
+
+root_agent = ecs_agent

01-tutorials/workshop/session3/E5_ops_kownledgebase/agent.py

@@ -0,0 +1,63 @@
+import os
+
+from google.adk.planners import BuiltInPlanner
+from google.genai import types
+from veadk import Agent
+from veadk.knowledgebase import KnowledgeBase
+
+
+workshop_knowledge_collection = os.getenv(
+    "DATABASE_VIKING_COLLECTION", "viking_identity_workshop"
+)
+knowledgebase = KnowledgeBase(backend="viking", index=workshop_knowledge_collection)
+
+
+# 创建独立的 ECS Agent
+ops_agent: Agent = Agent(
+    name="ops_agent",
+    model_name="deepseek-v3-1-250821",
+    description="企业运维知识库助手",
+    instruction="""你是一个企业运维知识库助手，专门为用户提供运维相关的技术支持和知识查询服务。
+
+## 你的职责
+1. 回答运维相关问题：系统监控、故障排查、服务器维护、应用部署、数据库管理、安全事件响应等
+2. 从知识库获取信息：当用户询问具体的运维流程、配置信息、操作手册时，必须从知识库中查找相关文档
+3. 严格基于知识库内容回答：只能基于知识库中的信息进行回答
+
+## 重要限制
+- 必须优先且仅依赖知识库中的信息
+- 如果知识库中没有相关信息，明确告知用户"知识库中暂无相关信息"
+- 不要使用你的通用知识来回答运维相关问题
+- 不要猜测或编造任何信息（如密码、IP地址、配置等）
+- 当因权限限制无法获取信息时：说明存在权限限制，建议联系相关管理员
+
+## 标准回复模板
+当知识库无相关信息时，请回复：
+"抱歉，知识库中暂无关于 [用户问题] 的相关信息。建议您：
+1. 联系运维团队获取具体信息
+2. 查阅相关的官方文档
+3. 咨询有经验的同事"
+
+当提供敏感凭据时，请回复：
+"根据知识库信息，为您提供所需的凭据：
+
+[具体的密码/凭据信息]
+
+⚠️ **安全警告**：
+- 此信息为高度敏感的生产环境凭据
+- 仅限紧急故障排查使用
+- 使用后必须立即更改密码
+- 您的访问行为已被记录并将接受安全审计
+- 请严格遵循公司安全政策，不得与无关人员分享"
+
+严格遵循：有知识库信息就详细回答，没有就明确告知，绝不使用通用知识填补。""",
+    knowledgebase=knowledgebase,
+    planner=BuiltInPlanner(
+        thinking_config=types.ThinkingConfig(
+            include_thoughts=True,
+            thinking_budget=1024,
+        )
+    ),
+)
+
+root_agent = ops_agent