From f5472a9dcf11d4a807d4e72c91e7284ed11a2574 Mon Sep 17 00:00:00 2001 From: "fangyaozheng@bytedance.com" Date: Mon, 29 Dec 2025 10:26:14 +0800 Subject: [PATCH] chore(docs): format markdown docs --- docs/docs/agent/agent-to-agent.md | 111 ++++++++++------- docs/docs/agent/agent.md | 117 +++++++++--------- docs/docs/agent/responses-api.md | 2 +- .../auth/oauth2-user-federation-outbound.md | 6 +- docs/docs/auth/overview.md | 6 +- docs/docs/cli.md | 90 +++++++++----- docs/docs/ide/snippets.md | 13 -- .../best-practice-knowledgebase.md | 2 +- docs/docs/quickstart.md | 2 +- docs/docs/runner.md | 4 +- docs/docs/tools/builtin.md | 12 +- docs/mkdocs.yml | 3 +- 12 files changed, 203 insertions(+), 165 deletions(-) delete mode 100644 docs/docs/ide/snippets.md diff --git a/docs/docs/agent/agent-to-agent.md b/docs/docs/agent/agent-to-agent.md index 0999321c..3d3d4cc6 100644 --- a/docs/docs/agent/agent-to-agent.md +++ b/docs/docs/agent/agent-to-agent.md @@ -3,43 +3,49 @@ title: A2A Agent --- ## Agent-to-Agent 协议简介 + 对于复杂度较高的任务，往往无法依赖单个 Agent 独立完成，需要通过协同多个专用 Agent 共同解决。**Agent2Agent (A2A) 协议** 是用于在多个 Agent 之间进行通信的标准。 !!! note 参考链接 - [A2A 协议官方文档](https://a2a-protocol.org/latest/) ## 多 Agent 系统 + 多 Agent 系统架构通常有两种架构方式: **Local Sub-Agents** 和 **Remote Agents (A2A)** - **Local Sub-Agents**：这类 Agent 与主 Agent 在同一个应用进程中。它们更像内部模块或库，用于将代码组织为逻辑、可复用的组件。主 Agent 与 Local Sub-Agents 之间的通信直接发生在内存中，无需网络开销，因此速度非常快。 - **Remote Agents (A2A)**：这类 Agent 以独立服务形式运行，通过网络进行通信。A2A 为此类通信定义了标准协议。 -### 如何选择合适的 Agent 架构 + +### 如何选择合适的 Agent 架构 + 并不是所有场景都适合使用 A2A，需要您参考以下建议，结合实际使用场景和需求作出合适选择: #### 适合使用 A2A 的场景 -| 场景名称 | 说明 | -| --------------- | ----------------------------------------- | -| **集成第三方服务** | 需要交互的 Agent 是一个独立的、可单独运行的第三方服务(例如需要从外部金融数据服务获取实时交易信息) | -| **微服务架构** | 不同的 Agent 由不同的团队或组织维护, A2A 用于些服务跨网络边界相互通信 | -| **跨语言通信** | 要连接使用不同编程语言或 Agent 框架实现的 Agent, A2A 提供了标准化的通信层 | -| **严格的 API 契约** |为了保证兼容性与稳定性，需要为 Agent 之间的交互制定严格契约 | - - - -#### 不适用 A2A 的场景（更适合 Local Sub-Agents）： -| 场景名称 | 说明 | -| ----------- | ----------------------------------------- | -| **内部代码组织** | 您在单个 Agent 内将复杂任务拆分为更小、可管理的函数或模块，这类场景出于性能与简洁考虑，更适合作为本地子 | -| **性能关键的内部操作** | 某个 Sub Agent 负责与主 Agent 执行紧密耦合的高频、低延迟操作，这类场景由于需要低延迟响应，更适合作为本地Local Sub-Agents。 | -| **共享内存或上下文** | 当 Sub Agent 需要直接访问主 Agent 的内部状态或共享内存以提高效率时，A2A 的网络开销与序列化/反序列化会适得其反 | -| **简单的辅助函数** |对于无需独立部署或复杂状态管理的小型复用逻辑，直接在同一 Agent 中编写函数或类，通常比拆分为独立的 A2A Agent 更合适 | - -## VeADK 中的 A2A 工作流： + +| 场景名称 | 说明 | +| - | - | +| **集成第三方服务** | 需要交互的 Agent 是一个独立的、可单独运行的第三方服务(例如需要从外部金融数据服务获取实时交易信息) | +| **微服务架构** | 不同的 Agent 由不同的团队或组织维护, A2A 用于些服务跨网络边界相互通信 | +| **跨语言通信** | 要连接使用不同编程语言或 Agent 框架实现的 Agent, A2A 提供了标准化的通信层 | +| **严格的 API 契约** | 为了保证兼容性与稳定性，需要为 Agent 之间的交互制定严格契约 | + +#### 不适用 A2A 的场景（更适合 Local Sub-Agents） + +| 场景名称 | 说明 | +| - | - | +| **内部代码组织** | 您在单个 Agent 内将复杂任务拆分为更小、可管理的函数或模块，这类场景出于性能与简洁考虑，更适合作为本地子 | +| **性能关键的内部操作** | 某个 Sub Agent 负责与主 Agent 执行紧密耦合的高频、低延迟操作，这类场景由于需要低延迟响应，更适合作为本地Local Sub-Agents | +| **共享内存或上下文** | 当 Sub Agent 需要直接访问主 Agent 的内部状态或共享内存以提高效率时，A2A 的网络开销与序列化/反序列化会适得其反 | +| **简单的辅助函数** | 对于无需独立部署或复杂状态管理的小型复用逻辑，直接在同一 Agent 中编写函数或类，通常比拆分为独立的 A2A Agent 更合适 | + +## VeADK 中的 A2A 工作流 + **VeADK** 简化了基于 A2A 协议构建并连接 Agent 的过程。下面是一个直观的工作流概览： -1. **对 Agent 开放访问（Exposing）：** 从现有的 VeADK Agent 入手，将其转化为一个 A2AServer, 把它变成能让其他 Agent 可访问的形式。A2AServer 可以视作为 Agent 搭建的一个 Web 服务，其他 Agent 可以通过它向您的 Agent 发送请求。 +1. **对 Agent 开放访问（Exposing）：** 从现有的 VeADK Agent 入手，将其转化为一个 A2AServer，把它变成能让其他 Agent 可访问的形式。A2AServer 可以视作为 Agent 搭建的一个 Web 服务，其他 Agent 可以通过它向您的 Agent 发送请求。 2. **连接到开放访问的 Agent（Consuming）：**在另一个 Agent 中（可能运行于同一台机器，也可能运行于不同机器），可使用名为 `RemoteVeAgent` 的 VeADK 组件，作为客户端访问上一步创建的 A2AServer，`RemoteVeAgent` 会在后台处理网络通信、鉴权和数据格式等复杂问题。 **VeADK** 对网络层进行了抽象封装，使分布式多 Agent 系统使用体验接近本地系统, 下图展示了一个完整的 **A2A 系统拓扑**： + ```mermaid flowchart LR A[Root Agent
（需要访问其它 Agent）
] @@ -54,13 +60,16 @@ flowchart LR ``` ## 构建一个本地 A2A 项目 + 下面是一个利用 A2A 搭建的系统示例： ### 创建 A2A 服务器 + 1. 定义 Agent 工具和功能 -2. 使用 to_a2a() 函数将 Agent 转换为 A2AServer +2. 使用 `to_a2a(...)` 函数将 Agent 转换为 A2AServer 3. 配置服务器参数（端口、主机等） -=== "代码" + +=== "Python" ```python title="server.py" linenums="1" hl_lines="1 11" from google.adk.a2a.utils.agent_to_a2a import to_a2a @@ -75,13 +84,16 @@ agent = Agent( app = to_a2a(agent=agent) ``` + ### 客户端集成 -1. 导入 RemoteVeAgent 类 + +1. 导入 `RemoteVeAgent` 类 2. 配置远程 Agent 连接参数 3. 在 Root Agent 中添加 Remote Agent 作为 Sub Agent -=== "代码" -```python title="client.py" linenums="1" +=== "Python" + +```python title="client.py" linenums="1" hl_lines="15 24" from veadk import Agent, Runner from veadk.a2a.remote_ve_agent import RemoteVeAgent @@ -120,8 +132,11 @@ if __name__ == "__main__": response = asyncio.run(main("What is the weather like of Beijing?")) print(response) ``` + ### 交互流程 + 下图为示例对应的交互流程图 + ```mermaid sequenceDiagram participant User as 用户 @@ -149,13 +164,18 @@ sequenceDiagram Client-->>User: 显示天气信息 ``` -## A2A Client 鉴权参数 -VeADK 的 A2A 鉴权机制提供了灵活的认证选项，支持标准的 Bearer token 认证和查询参数认证两种常见模式，同时也支持无认证的公开服务场景，能够满足不同的安全需求 -### Querystring 方式 -- 将认证令牌作为 URL 查询参数 token={auth_token} 传递 -- 通过设置 auth_method 为 "querystring" 来启用 +## 身份认证与鉴权 + +VeADK 的 A2A 鉴权机制提供了灵活的认证选项，支持标准的 Bearer token 认证和查询参数认证两种常见模式，同时也支持无认证的公开服务场景，能够满足不同的安全需求。 + +### QueryString 方式 + +- 将认证令牌作为 URL 查询参数 `?token={auth_token}` 传递 +- 通过设置 `auth_method` 为 `querystring` 来启用 - 适用于某些特定的 API 网关或服务配置 -=== "代码" + +=== "Python" + ```python title="client.py" linenums="1" hl_lines="5" remote_agent = RemoteVeAgent( name="a2a_agent", @@ -166,10 +186,13 @@ VeADK 的 A2A 鉴权机制提供了灵活的认证选项，支持标准的 Beare ``` ### Header 方式 -- 使用 Authorization: Bearer {auth_token} 格式的 HTTP header 进行鉴权 -- 通过设置 auth_method="header" 来启用 + +- 使用 Authorization: Bearer {auth_token} 格式的 HTTP 请求头进行鉴权 +- 通过设置 `auth_method="header"` 来启用 - 适用于需要在 HTTP header 中传递认证信息的场景 -=== "代码" + +=== "Python" + ```python title="client.py" linenums="1" hl_lines="5" remote_agent = RemoteVeAgent( name="a2a_agent", @@ -179,13 +202,16 @@ VeADK 的 A2A 鉴权机制提供了灵活的认证选项，支持标准的 Beare ) ``` -??? note "火山引擎 veFaaS 采用的默认鉴权方式" +??? note "火山引擎 VeFaaS 采用的默认鉴权方式" - 当您使用火山引擎 veFaaS 作为您的 Agent runtime 时，默认使用 Querystring 方式进行认证鉴权，请参考以下截图中的 “我的应用”中可以查看您创建的资源对应的访问地址信息中携带的 Querystring 认证鉴权信息 ![火山 veFaaS 应用中的认证信息](../assets/images/agents/a2a_querystring.png) ### 自定义 HTTP 客户端 -在 VeADK中，主要通过 RemoteVeAgent 类来实现自定义 HTTP 客户端的配置，它提供了一个 httpx_client 参数，允许您传入预配置的 httpx.AsyncClient 实例。这使得您可以灵活地控制 HTTP 请求的各种参数，如代理设置、超时控制、连接池管理等，从而更好地适应不同的网络环境和需求。 -#### 您可以通过运参考以下示例代码设置创建自定义的 HTTP 客户端，可配置各种 HTTP 客户端参数，如： + +在 VeADK中，主要通过 `RemoteVeAgent` 类来实现自定义 HTTP 客户端的配置，它提供了一个 `httpx_client` 参数，允许您传入预配置的 `httpx.AsyncClient` 实例。这使得您可以灵活地控制 HTTP 请求的各种参数，如代理设置、超时控制、连接池管理等，从而更好地适应不同的网络环境和需求。 + +您可以通过运参考以下示例代码设置创建自定义的 HTTP 客户端，可配置各种 HTTP 客户端参数，如： + - 超时设置 - 代理配置 - 连接池大小 @@ -193,10 +219,11 @@ VeADK 的 A2A 鉴权机制提供了灵活的认证选项，支持标准的 Beare - 自定义请求头 - SSL 验证选项 -=== "代码" - ```python title="client.py" linenums="1" +=== "Python" + + ```python title="client.py" linenums="1" hl_lines="4 43" # <...code truncated...> - + # 创建自定义的 httpx.AsyncClient 实例 custom_client = httpx.AsyncClient( # 基础 URL 设置 @@ -242,7 +269,3 @@ VeADK 的 A2A 鉴权机制提供了灵活的认证选项，支持标准的 Beare # <...code truncated...> ``` - - - - diff --git a/docs/docs/agent/agent.md b/docs/docs/agent/agent.md index a6aa87f4..81142c13 100644 --- a/docs/docs/agent/agent.md +++ b/docs/docs/agent/agent.md @@ -90,7 +90,6 @@ } ``` - === "所需环境变量" 环境变量列表： @@ -126,17 +125,16 @@ ```golang title="agent.go" linenums="1" hl_lines="2-4" cfg := &veagent.Config{} - cfg.Name = "life_assistant" - cfg.Description = "生活助手" - cfg.Instruction = "你是一个生活助手，你可以回答用户的问题。" - - veAgent, err := veagent.New(cfg) - if err != nil { - fmt.Printf("NewVeAgent failed: %v", err) - return - } - ``` + cfg.Name = "life_assistant" + cfg.Description = "生活助手" + cfg.Instruction = "你是一个生活助手，你可以回答用户的问题。" + veAgent, err := veagent.New(cfg) + if err != nil { + fmt.Printf("NewVeAgent failed: %v", err) + return + } + ``` 其中，`name` 代表 Agent 的名称，`description` 是对 Agent 功能的简单描述（在Agent Tree中唯一标识某个Agent），`instruction` 是 Agent 的系统提示词，用于定义其行为和响应风格。 @@ -161,50 +159,56 @@ ```golang title="agent.go" linenums="1" hl_lines="2-4" cfg := &veagent.Config{ - ModelName: "...", - ModelAPIBase: "...", - ModelAPIKey: "...", - } + ModelName: "...", + ModelAPIBase: "...", + ModelAPIKey: "...", + } veAgent, err := veagent.New(cfg) - if err != nil { - fmt.Printf("NewVeAgent failed: %v", err) - return - } + if err != nil { + fmt.Printf("NewVeAgent failed: %v", err) + return + } ``` -由于 python VeADK 的 Agent 基于 [LiteLLM]() 实现，因此您可以使用 LiteLLM 支持的所有模型提供商。您可以查看 [LiteLLM 支持的模型提供商列表](https://docs.litellm.ai/docs/providers)来设置 `model_provider` 参数。 +VeADK Python 版本中的 Agent 推理模型基于 [LiteLLM](https://github.com/BerriAI/litellm) 实现，因此您可以使用 LiteLLM 支持的所有模型提供商。您可以查看 [LiteLLM 支持的模型提供商列表](https://docs.litellm.ai/docs/providers)来设置 `model_provider` 参数。 -基于 LiteLLM 的 [Fallbacks](https://docs.litellm.ai/docs/completion/reliable_completions) 容错机制，VeADK 实现了智能的模型切换能力。当目标模型经多次重试仍调用失败时，系统将自动切换至备选模型继续执行任务： +#### 模型容错 + +VeADK 为您提供了基于 LiteLLM 的 [Fallbacks](https://docs.litellm.ai/docs/completion/reliable_completions) 模型容错机制，能够在前序模型访问失败时进行模型自动切换。例如，当目标模型经多次重试仍调用失败时，系统将自动切换至备选模型来继续执行任务： === "Python" - ```python title="agent.py" linenums="1" hl_lines="4" + ```python title="agent.py" linenums="1" hl_lines="4-8" from veadk import Agent - + agent = Agent( - model_name=["doubao-seed-1-8-251215", "doubao-seed-1-6-251015", "doubao-seed-1.6-250615"] + model_name=[ + "doubao-seed-1-8-251215", + "doubao-seed-1-6-251015", + "doubao-seed-1.6-250615", + ] ) ``` -在上述配置中，VeADK 默认会首先尝试 doubao-seed-1-8-251215，如果失败再去尝试后续模型，直至成功。 - -golang 暂不支持 LiteLLM，因此 VeADK 的 Agent 基于 OpenAI 实现，因此您可以使用所有支持OpenAI协议的模型。 +在上述配置中，VeADK 默认会首先尝试 `doubao-seed-1-8-251215` 模型，如果失败后会尝试后续模型，直至成功。 -#### 设置模型客户端 +#### 自定义您的模型客户端 VeADK 支持您直接定义 LiteLLM 的客户端，来实现高度自定义的模型配置： -```python title="agent.py" linenums="1" hl_lines="5 8" -from google.adk.models.lite_llm import LiteLlm -from veadk import Agent +=== "Python" -# 自定义您的模型客户端 -llm = LiteLlm() + ```python title="agent.py" linenums="1" hl_lines="5 8" + from google.adk.models.lite_llm import LiteLlm + from veadk import Agent -# 直接将模型客户端传递给 Agent -agent = Agent(model=llm) -``` + # 自定义您的模型客户端 + llm = LiteLlm() + + # 直接将模型客户端传递给 Agent + agent = Agent(model=llm) + ``` #### 配置模型额外参数 @@ -236,21 +240,20 @@ agent = Agent(model=llm) ) veAgent, err := veagent.New(&veagent.Config{ - ModelExtraConfig: map[string]any{ - "extra_body": map[string]any{ - "thinking": map[string]string{ - "type": "disabled", - }, - }, - }, - }) - if err != nil { - fmt.Printf("NewVeAgent failed: %v", err) - return - } + ModelExtraConfig: map[string]any{ + "extra_body": map[string]any{ + "thinking": map[string]string{ + "type": "disabled", + }, + }, + }, + }) + if err != nil { + fmt.Printf("NewVeAgent failed: %v", err) + return + } ``` - ### 通过配置文件 在您构建 Agent 过程中，往往需要更加简洁的 Agent 定义方式与配置管理。为了方便这种场景，VeADK 提供了 YAML 文件定义方式。该方法以声明式语法描述智能体的全部元信息与行为结构。 @@ -265,7 +268,7 @@ root_agent: description: An intelligent_assistant which can provider weather information. instruction: Help user according to your tools. model_name: doubao-1-5-pro-32k-250115 - model_api_key: xxx # 您的模型API Key + model_api_key: ... # 您的模型API Key tools: - name: veadk.tools.demo_tools.get_city_weather # tool 所在的模块及函数名称 ``` @@ -297,14 +300,14 @@ response = asyncio.run(runner.run("今天北京天气如何？")) print(response) ``` -### 构建 Agent 的方法对比 +## 构建 Agent 的方法对比 **对比总结**： -| 特性 | 代码方式 | YAML 方式 | +| 特性 | 代码方式 | YAML 方式 | | ---- | ----- | ------- | -| 灵活性 | 高 | 中 | -| 可读性 | 中 | 高 | -| 可维护性 | 中 | 高 | -| 动态生成 | 支持 | 一般 | -| 适用场景 | 开发、生产 | 实验、配置化、生产 | +| 灵活性 | 高 | 中 | +| 可读性 | 中 | 高 | +| 可维护性 | 中 | 高 | +| 动态生成 | 支持 | 一般 | +| 适用场景 | 开发、生产 | 实验、配置化、生产 | diff --git a/docs/docs/agent/responses-api.md b/docs/docs/agent/responses-api.md index 7b6b19fc..33e66460 100644 --- a/docs/docs/agent/responses-api.md +++ b/docs/docs/agent/responses-api.md @@ -28,7 +28,7 @@ Responses API 是火山方舟最新推出的 API 接口，原生支持高效的 from veadk import Agent root_agent = Agent( - enable_responses=True, # 开启 Responses API + enable_responses=True, # 开启 Responses API ) ``` diff --git a/docs/docs/auth/oauth2-user-federation-outbound.md b/docs/docs/auth/oauth2-user-federation-outbound.md index 28f4dfcb..d99f649d 100644 --- a/docs/docs/auth/oauth2-user-federation-outbound.md +++ b/docs/docs/auth/oauth2-user-federation-outbound.md @@ -17,7 +17,7 @@ OAuth2 USER_FEDERATION 认证用于用户委托场景，应用代表用户访问 - Client ID - Client Secret -- 回调 URL（选择[回调地址](./4.oauth2-user-federation-outbound.md#回调地址)对应区域的地址） +- 回调 URL（选择[回调地址](#回调地址)对应区域的地址） ### 方式二：使用 OIDC 配置 @@ -27,7 +27,7 @@ OAuth2 USER_FEDERATION 认证用于用户委托场景，应用代表用户访问 - Client ID - Client Secret - 权限范围：至少包含 `openid` -- 回调 URL（选择[回调地址](./4.oauth2-user-federation-outbound.md#回调地址)对应区域的地址） +- 回调 URL（选择[回调地址](#回调地址)对应区域的地址） ### 方式三：使用自定义 OAuth2 配置 @@ -39,7 +39,7 @@ OAuth2 USER_FEDERATION 认证用于用户委托场景，应用代表用户访问 - Issuer - 授权端点 - 令牌端点 -- 回调 URL（选择[回调地址](./4.oauth2-user-federation-outbound.md#回调地址)对应区域的地址） +- 回调 URL（选择[回调地址](#回调地址)对应区域的地址） ## 回调地址 diff --git a/docs/docs/auth/overview.md b/docs/docs/auth/overview.md index 10d73c92..37744c19 100644 --- a/docs/docs/auth/overview.md +++ b/docs/docs/auth/overview.md @@ -73,9 +73,9 @@ 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) +- [使用 API Key 进行出站认证](./api-key-outbound.md) +- [使用 OAuth2 M2M 进行出站认证](./oauth2-m2m-outbound.md) +- [使用 OAuth2 USER_FEDERATION 进行出站认证](./oauth2-user-federation-outbound.md) ## 相关资源 diff --git a/docs/docs/cli.md b/docs/docs/cli.md index 9b047601..8b4271e5 100644 --- a/docs/docs/cli.md +++ b/docs/docs/cli.md @@ -43,17 +43,22 @@ VeADK 提供如下命令便捷您的操作： ### 使用示例 启动交互式初始化流程： + ```bash veadk init ``` + 执行以上命令后，您将被引导完成项目初始化流程。根据提示输入项目名称、本地目录名称、Volcengine FaaS 应用名称、Volcengine API Gateway 实例名称、服务名称、上游名称等信息，以默认项目名称`weather-reporter`为例： ![veadk_init](./assets/images/cli/cli_veadk_init.gif) 您也可以在初始化时直接指定使用 `web_template` 模板： + ```bash veadk init --vefaas-template-type web_template ``` + 执行完成之后，命令所生成的目录结构如下： -``` + +```bash weather-reporter/ ├────src # 智能体项目源代码目录 │ ├────weather_report # 天气预报智能体项目目录 @@ -94,27 +99,35 @@ weather-reporter/ ### 使用示例 启动交互式创建流程： + ```bash veadk create ``` + 您也直接指定智能体名称来创建，例如： + ```bash veadk create location-agent ``` + 在执行以上命令后，您将被引导完成智能体创建流程。首先，系统会提示您选择以何种方式提供 API Key，您可以选择直接输入或稍后配置。如下所示： ![veadk_create](./assets/images/cli/cli_veadk_create.gif) 您也可以在创建时同时提供 API Key： + ```bash veadk create location-agent --ark-api-key "xxxxxx" ``` + 该命令会创建一个包含 API Key 的 `.env` 文件。您可以稍后编辑此文件以更新 API Key。命令创建的完整目录结构如下： -``` + +```bash location-agent/ ├── .env # 包含 API key 的环境配置 ├── __init__.py # Python 包初始化文件 └── agent.py # 主要智能体定义文件 ``` -这时，您可以使用 `veadk web` 命令来运行示例`location-agent` 智能体，具体执行方式及参数说明请参考下一节：[Web 调试界面](#web-调试界面)。 + +这时，您可以使用 `veadk web` 命令来运行示例`location-agent` 智能体。 ## Web 调试界面 @@ -135,24 +148,27 @@ location-agent/ | `--log-level` | [debug\|info\|warning\|error] | 设置日志输出级别，默认值为 info | | `--help` | | 显示此帮助信息并退出 | -**长短期记忆机制** +**长短期记忆机制**： VeADK Web 调试界面支持智能体的短期记忆和长期记忆功能，这些机制通过以下方式传递到 Web 界面中： **短期记忆传递**： - - 智能体在交互过程中产生的对话历史会自动保存为短期记忆 - - Web 界面通过会话 ID 关联智能体的短期记忆数据 - - 每次对话都会加载对应的短期记忆上下文 + +- 智能体在交互过程中产生的对话历史会自动保存为短期记忆 +- Web 界面通过会话 ID 关联智能体的短期记忆数据 +- 每次对话都会加载对应的短期记忆上下文 **长期记忆传递**： - - 智能体的知识库配置信息会传递给 Web 界面 - - Web 界面支持基于长期记忆的智能体行为定制 - - 长期记忆数据通过智能体配置自动加载 + +- 智能体的知识库配置信息会传递给 Web 界面 +- Web 界面支持基于长期记忆的智能体行为定制 +- 长期记忆数据通过智能体配置自动加载 **记忆服务集成**： - - 自动检测并配置相应的记忆后端服务 - - 支持多种记忆存储类型（local、mysql、redis等） - - 记忆数据在 Web 界面中实时同步和更新 + +- 自动检测并配置相应的记忆后端服务 +- 支持多种记忆存储类型（local、mysql、redis等） +- 记忆数据在 Web 界面中实时同步和更新 ### 使用示例 @@ -167,14 +183,12 @@ veadk web --port 8080 该命令能够自动读取执行命令目录中的 `agent.py` 文件，并加载其中的 `root_agent` 全局变量。服务启动后，通常可以在 `http://127.0.0.1:8000` 访问。 - ### 使用示例 使用示例如下图示： ![veadk_web](./assets/images/cli/cli_veadk_web.gif) 在界面左上角的选择框中，您可以选择要调试的智能体。在本示例中，您可以看到您创建的`location-agent`智能体。 - ## 知识库 `veadk kb` 命令是用于管理 VeADK 知识库的命令集。 @@ -198,9 +212,9 @@ veadk web --port 8080 | 参数 | 类型 | 描述 | | :--- | :--- | :--- | -| `--backend` | [local\|opensearch\|viking\|redis] | **(必需)** 知识库后端类型。 | -| `--app_name` | TEXT | 用于组织和隔离知识库数据的应用标识符。 | -| `--index` | TEXT | 知识库索引标识符，在 `app_name` 内唯一。| +| `--backend` | [local\|opensearch\|viking\|redis] | **(必需)** 知识库后端类型 | +| `--app_name` | TEXT | 用于组织和隔离知识库数据的应用标识符 | +| `--index` | TEXT | 知识库索引标识符，在 `app_name` 内唯一 | | `--path` | TEXT | **(必需)** 要添加的知识内容的文件或目录路径。 | | `--help` | | 显示此帮助信息并退出。 | @@ -211,7 +225,7 @@ veadk web --port 8080 - **viking**: 火山引擎的托管向量数据库服务，为语义搜索和 RAG 应用优化。 - **redis**: 具有向量搜索功能的内存数据存储，适用于快速检索、较小的知识库。 -**注意** +**注意**： veadk kb add 命令需要将您的文档内容转换成向量，这个过程默认会使用一个嵌入模型（Embedding Model）服务，该服务会将文档内容转换为向量表示。您可以根据需要配置不同的嵌入模型，例如火山引擎的方舟大模型平台。 @@ -224,7 +238,8 @@ veadk kb add 命令需要将您的文档内容转换成向量，这个过程默 下面的示例将演示将单个文件添加到redis作为后端的知识库，并在后续的智能体调用中使用。 假设您在当前目录下有一个名为`qa.md`的文件，内容如下： -``` + +```markdown # 智能客服知识库 ## 1. 公司简介 @@ -272,10 +287,12 @@ A4: 知识库支持 **实时更新**，管理员提交后即可立即生效。 ``` 您可以使用以下命令将其添加到本地知识库： + ```bash veadk kb add --backend redis --app_name app --path ./qa.md ``` -**注意** + +**注意**： - 在本例中，我们选择的是redis后端。您需要事先在本地目录的`.env`文件中配置好`DATABASE_REDIS_HOST`,`DATABASE_REDIS_HOST`,`DATABASE_REDIS_PORT`,`DATABASE_REDIS_PASSWORD`(以及可选的`DATABASE_REDIS_USER`)等环境变量。 - 您需要确认您配置的redis服务是否正常运行，并且端口号是否与您在`.env`文件中配置的一致。 @@ -285,6 +302,7 @@ veadk kb add --backend redis --app_name app --path ./qa.md ![veadk_kb_add](./assets/images/cli/cli_veadk_kb_add.gif) 接下来，您可以通过如下代码来验证智能库是否添加成功： + ```python import asyncio @@ -317,9 +335,9 @@ response = asyncio.run( ) print(response) - ``` -**注意** + +**注意**： - 您需要确认您运行上述代码时，redis服务正常运行并已经开启向量搜索功能。同时，这段代码需要和上面的命令共享相同的环境变更配置（建议在相同目录下运行，这样可以共享相同的.env配置文件。） - 代码中的'app_name'需要与上面的命令中的'app_name'保持一致，在本 示例中为'app'。 @@ -345,7 +363,7 @@ print(response) | `--veapig-instance-name` | TEXT | (可选) 用于配置外部 API 访问的火山引擎 API 网关实例名称。 | | `--veapig-service-name` | TEXT | (可选) 火山引擎 API 网关服务名称。 | | `--veapig-upstream-name` | TEXT | (可选) 火山引擎 API 网关上游名称。 | -| `--short-term-memory-backend`| [local\|mysql] | 短期记忆存储的后端类型。默认为 `local`。 | +| `--short-term-memory-backend` | [local\|mysql] | 短期记忆存储的后端类型。默认为 `local`。 | | `--use-adk-web` | | 为部署的智能体启用 ADK Web 界面。 | | `--path` | TEXT | 包含要部署的 VeADK 项目的本地目录路径。默认为当前目录 `.`。 | | `--help` | | 显示此帮助信息并退出。 | @@ -353,6 +371,7 @@ print(response) ### 使用示例 在项目根目录下，执行部署（需要提供AK/SK和FaaS应用名）： + ```bash veadk deploy \ --vefaas-app-name my-cloud-app \ @@ -361,6 +380,7 @@ veadk deploy \ ``` 部署指定路径下的项目，并启用 Web 界面： + ```bash veadk deploy \ --path ./my-agent-project \ @@ -370,7 +390,7 @@ veadk deploy \ --secret-key "YOUR_SECRET_KEY" ``` -**注意** +**注意**： - 您也可以在项目根目录下的`.env`文件中设置 `VOLCENGINE_ACCESS_KEY` 和 `VOLCENGINE_SECRET_KEY` 环境变量，避免在命令行中明文暴露 AK/SK。 @@ -406,17 +426,22 @@ veadk deploy \ ```bash veadk prompt --path ./weather_reporter/agent.py --feedback "希望提示词能够更加具体明确" --api-key "YOUR_API_KEY" --workspace-id "YOUR_WORKSPACE_ID" ``` -** 注意 ** + +**注意**： - 您需要先在火山引擎[PromptPilot控制台](https://promptpilot.volcengine.com/)创建一个项目，并获取 API Key 和工作空间 ID。 - 您也可以在项目根目录下的`.env`文件中设置 `PROMPTPILOT_API_KEY` 环境变量，避免在命令行中明文暴露 API Key。 - 本命令会自动读取智能体代码中的`Agent`对象的`instruction` 内容，作为目标来进行提示词优化。本本例中，原始的`instruction`内容如下所示： -``` + +```text Once user ask you weather of a city, you need to provide the weather report for that city by calling `get_city_weather` ``` + 本命令运行的结果如下所示： -``` + +```text Optimized prompt for agent weather_reporter: + # Role You are a weather information provider. When the user asks about the weather of a city, your task is to offer an accurate weather report for that city. @@ -430,7 +455,6 @@ You are a weather information provider. When the user asks about the weather of - Ensure that the information provided is based on the data obtained from the `get_city_weather` function and is as accurate as possible. ``` - ## 评测 ### 简介 @@ -464,11 +488,12 @@ You are a weather information provider. When the user asks about the weather of - 必须提供 `--agent-dir` 或 `--agent-a2a-url` 两者之一。 - 如果两者都提供，`--agent-a2a-url` 优先。 -- 需要事先准备好评测数据集文件，您可以参考[评测](/observation/evaluation)中的说明，创建一个符合 Google ADK 格式的 JSON 文件。 +- 需要事先准备好评测数据集文件，您可以参考[评测](deploy/evaluation.md)中的说明，创建一个符合 Google ADK 格式的 JSON 文件。 ### 使用示例 -**本地评估示例:** +**本地评估示例**： + ```bash veadk eval \ --agent-dir ./my-agent \ @@ -476,7 +501,8 @@ veadk eval \ --evaluator adk ``` -**远程评估示例:** +**远程评估示例**： + ```bash veadk eval \ --agent-a2a-url http://my-agent-url.com/invoke \ diff --git a/docs/docs/ide/snippets.md b/docs/docs/ide/snippets.md deleted file mode 100644 index 10ee517a..00000000 --- a/docs/docs/ide/snippets.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: snippets.json ---- - -## snippets.json - -您可以直接下载下方 `snippets.json` 文件，并导入到 Trae 或 VsCode 等编辑器中，以获取 VeADK 相关的代码片段。 - -- 下载 `snippets.json` 文件：[snippets.json](../static/snippets.json){:download} - -```json title="snippets.json" -test -``` diff --git a/docs/docs/knowledgebase/best-practice-knowledgebase.md b/docs/docs/knowledgebase/best-practice-knowledgebase.md index c0fd526e..2a6e485e 100644 --- a/docs/docs/knowledgebase/best-practice-knowledgebase.md +++ b/docs/docs/knowledgebase/best-practice-knowledgebase.md @@ -1,4 +1,4 @@ -# 知识库最佳实践 +# 最佳实践 本文档介绍如何在企业级或生产环境中，将知识库与智能体深度结合，实现复杂、多步骤的知识驱动型应用。 diff --git a/docs/docs/quickstart.md b/docs/docs/quickstart.md index 13ce1a23..36921c41 100644 --- a/docs/docs/quickstart.md +++ b/docs/docs/quickstart.md @@ -142,4 +142,4 @@ veadk web 交互界面如图： -![veadk交互界面](../assets/images/overview/veadk-web.png) \ No newline at end of file +![veadk交互界面](./assets/images/overview/veadk-web.png) \ No newline at end of file diff --git a/docs/docs/runner.md b/docs/docs/runner.md index 1d8bd468..c32a933f 100644 --- a/docs/docs/runner.md +++ b/docs/docs/runner.md @@ -1,8 +1,8 @@ # 执行引擎 -`Runner` 是 ADK Runtime 中的一个核心组件，负责协调你定义的 Agents、Tools、Callbacks，使它们共同响应用户输入，同时管理信息流、状态变化，以及与外部服务（例如 LLM、Tools）或存储的交互。 +`Runner` 是 ADK Runtime 中的一个核心组件，负责协调你定义的 Agents、Tools、Callbacks 等外部组件，使它们共同响应用户输入，同时管理信息流、状态变化，以及与外部服务（例如 LLM、Tools）或存储的交互。 -VeADK 的执行引擎完全兼容 Google ADK Runner，更多`Runner`工作机制说明您可参考 [Google ADK Agent 运行时](https://google.github.io/adk-docs/runtime/)。 +VeADK 的执行引擎完全兼容 Google ADK Runner，关于 `Runner` 的完整工作机制与生命周期说明可参考 [Google ADK Agent 运行时](https://google.github.io/adk-docs/runtime/)。 --- diff --git a/docs/docs/tools/builtin.md b/docs/docs/tools/builtin.md index e022fd4f..6038d286 100644 --- a/docs/docs/tools/builtin.md +++ b/docs/docs/tools/builtin.md @@ -5,18 +5,18 @@ ## 使用方法 -1. **导入**：从 `veadk.tools.builtin_tools` 模块导入所需工具。 -2. **配置**：初始化工具并按需提供参数。 -3. **注册**：将工具实例添加至 Agent 的 `tools` 列表。 +1. **导入**：从 `veadk.tools.builtin_tools` 模块导入所需工具。 +2. **配置**：初始化工具并按需提供参数。 +3. **注册**：将工具实例添加至 Agent 的 `tools` 列表。 === "Python" ```python from veadk import Agent - from veadk.tools.builtin_tools.web_search import websearch + from veadk.tools.builtin_tools.web_search import web_search # 在 Agent 初始化时注册工具 - # Agent(tools=[websearch], other_params...) + agent = Agent(tools=[web_search]) ``` === "Golang" @@ -91,8 +91,6 @@ VeADK 集成了以下火山引擎工具： --8<-- "examples/tools/web_search/agent.go" ``` - - === "环境变量" 环境变量列表： diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index ef6bb73b..a4a7e266 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -59,7 +59,7 @@ nav: - 护栏工具: tools/guardrail.md - 连接数据源——知识库: - 基本使用: knowledgebase/overview.md - - 最佳实践（知识库相关）: knowledgebase/best-practice-knowledgebase.md + - 最佳实践: knowledgebase/best-practice-knowledgebase.md - 身份与权限: - 概述: auth/overview.md - 入站认证: auth/inbound.md @@ -90,6 +90,7 @@ nav: plugins: - search + - autorefs - mkdocs-video: is_video: True video_muted: True