diff --git a/docs/docs/agent/agent-to-agent.md b/docs/docs/agent/agent-to-agent.md index 959c43ed..0999321c 100644 --- a/docs/docs/agent/agent-to-agent.md +++ b/docs/docs/agent/agent-to-agent.md @@ -33,13 +33,13 @@ title: A2A Agent | **共享内存或上下文** | 当 Sub Agent 需要直接访问主 Agent 的内部状态或共享内存以提高效率时，A2A 的网络开销与序列化/反序列化会适得其反 | | **简单的辅助函数** |对于无需独立部署或复杂状态管理的小型复用逻辑，直接在同一 Agent 中编写函数或类，通常比拆分为独立的 A2A Agent 更合适 | -## veADK 中的 A2A 工作流： -**veADK** 简化了基于 A2A 协议构建并连接 Agent 的过程。下面是一个直观的工作流概览： +## VeADK 中的 A2A 工作流： +**VeADK** 简化了基于 A2A 协议构建并连接 Agent 的过程。下面是一个直观的工作流概览： -1. **对 Agent 开放访问（Exposing）：** 从现有的 veADK Agent 入手，将其转化为一个 A2AServer, 把它变成能让其他 Agent 可访问的形式。A2AServer 可以视作为 Agent 搭建的一个 Web 服务，其他 Agent 可以通过它向您的 Agent 发送请求。 -2. **连接到开放访问的 Agent（Consuming）：**在另一个 Agent 中（可能运行于同一台机器，也可能运行于不同机器），可使用名为 `RemoteVeAgent` 的 veADK 组件，作为客户端访问上一步创建的 A2AServer，`RemoteVeAgent` 会在后台处理网络通信、鉴权和数据格式等复杂问题。 +1. **对 Agent 开放访问（Exposing）：** 从现有的 VeADK Agent 入手，将其转化为一个 A2AServer, 把它变成能让其他 Agent 可访问的形式。A2AServer 可以视作为 Agent 搭建的一个 Web 服务，其他 Agent 可以通过它向您的 Agent 发送请求。 +2. **连接到开放访问的 Agent（Consuming）：**在另一个 Agent 中（可能运行于同一台机器，也可能运行于不同机器），可使用名为 `RemoteVeAgent` 的 VeADK 组件，作为客户端访问上一步创建的 A2AServer，`RemoteVeAgent` 会在后台处理网络通信、鉴权和数据格式等复杂问题。 -**veADK** 对网络层进行了抽象封装，使分布式多 Agent 系统使用体验接近本地系统, 下图展示了一个完整的 **A2A 系统拓扑**： +**VeADK** 对网络层进行了抽象封装，使分布式多 Agent 系统使用体验接近本地系统, 下图展示了一个完整的 **A2A 系统拓扑**： ```mermaid flowchart LR A[Root Agent
（需要访问其它 Agent）
] @@ -48,7 +48,7 @@ flowchart LR end A <-->RemoteVeAgent B[您的 Agent 代码
（开放访问）
] - C[A2A Server
（veADK 组件）
] + C[A2A Server
（VeADK 组件）
] C -->B RemoteVeAgent <-->|网络请求交互|C ``` @@ -150,7 +150,7 @@ sequenceDiagram ``` ## A2A Client 鉴权参数 -veADK 的 A2A 鉴权机制提供了灵活的认证选项，支持标准的 Bearer token 认证和查询参数认证两种常见模式，同时也支持无认证的公开服务场景，能够满足不同的安全需求 +VeADK 的 A2A 鉴权机制提供了灵活的认证选项，支持标准的 Bearer token 认证和查询参数认证两种常见模式，同时也支持无认证的公开服务场景，能够满足不同的安全需求 ### Querystring 方式 - 将认证令牌作为 URL 查询参数 token={auth_token} 传递 - 通过设置 auth_method 为 "querystring" 来启用 @@ -184,7 +184,7 @@ veADK 的 A2A 鉴权机制提供了灵活的认证选项，支持标准的 Beare ![火山 veFaaS 应用中的认证信息](../assets/images/agents/a2a_querystring.png) ### 自定义 HTTP 客户端 -在 veADK中，主要通过 RemoteVeAgent 类来实现自定义 HTTP 客户端的配置，它提供了一个 httpx_client 参数，允许您传入预配置的 httpx.AsyncClient 实例。这使得您可以灵活地控制 HTTP 请求的各种参数，如代理设置、超时控制、连接池管理等，从而更好地适应不同的网络环境和需求。 +在 VeADK中，主要通过 RemoteVeAgent 类来实现自定义 HTTP 客户端的配置，它提供了一个 httpx_client 参数，允许您传入预配置的 httpx.AsyncClient 实例。这使得您可以灵活地控制 HTTP 请求的各种参数，如代理设置、超时控制、连接池管理等，从而更好地适应不同的网络环境和需求。 #### 您可以通过运参考以下示例代码设置创建自定义的 HTTP 客户端，可配置各种 HTTP 客户端参数，如： - 超时设置 - 代理配置 diff --git a/docs/docs/assets/images/uv_demo.jpeg b/docs/docs/assets/images/uv_demo.jpeg new file mode 100644 index 00000000..5bb01aef Binary files /dev/null and b/docs/docs/assets/images/uv_demo.jpeg differ diff --git a/docs/docs/deploy/deploy-agentkit.md b/docs/docs/deploy/deploy-agentkit.md new file mode 100644 index 00000000..9c32e450 --- /dev/null +++ b/docs/docs/deploy/deploy-agentkit.md @@ -0,0 +1,5 @@ +--- +title: 部署到 AgentKit +--- + +详见 [部署到 AgentKit 平台](https://volcengine.github.io/agentkit-sdk-python/content/2.agentkit-cli/1.overview.html#%E4%B8%89%E7%A7%8D%E9%83%A8%E7%BD%B2%E6%A8%A1%E5%BC%8F) diff --git a/docs/docs/deploy.md b/docs/docs/deploy/deploy-vefaas.md similarity index 87% rename from docs/docs/deploy.md rename to docs/docs/deploy/deploy-vefaas.md index 06750cb5..a259d67e 100644 --- a/docs/docs/deploy.md +++ b/docs/docs/deploy/deploy-vefaas.md @@ -1,33 +1,39 @@ --- -title: 部署到火山引擎 +title: 部署到 VeFaaS --- +本教程将介绍如何将您的 Agent 部署到火山引擎 VeFaaS 函数服务。 + ## 前置准备 + 在开始部署之前，请确保你已完成以下准备工作： -1. **创建火山引擎账号**：你首先需要一个有效的火山引擎账号。 -2. **开通相关云服务**：为了成功部署和访问 Veadk 应用，你需要在火山引擎控制台中激活以下服务。这些通常是首次访问服务时根据引导完成的一次性操作。 - * [**函数服务 (veFaaS)**](https://console.volcengine.com/vefaas)：用于托管和运行你的 Agent 应用代码。 - * [**API 网关 (API Gateway)**](https://console.volcengine.com/veapig)：用于创建和管理 API，使你的 Agent 应用能够从外部访问。 +1. **创建火山引擎账号**：你首先需要一个有效的火山引擎账号。 +2. **开通相关云服务**：为了成功部署和访问 Veadk 应用，你需要在火山引擎控制台中激活以下服务。这些通常是首次访问服务时根据引导完成的一次性操作。 + * [**函数服务 (veFaaS)**](https://console.volcengine.com/vefaas)：用于托管和运行你的 Agent 应用代码。 + * [**API 网关 (API Gateway)**](https://console.volcengine.com/veapig)：用于创建和管理 API，使你的 Agent 应用能够从外部访问。 + 在部署到火山引擎前，你需要提前在火山引擎控制台开通 [函数服务](https://console.volcengine.com/vefaas) 和 [API网关](https://console.volcengine.com/veapig) 服务。如果你事先已开通过服务，可以忽略该环节。 ### 首次开通服务授权 如果你是首次使用上述服务，控制台会引导你完成必要的 IAM (Identity and Access Management) 角色授权。 -1. 访问 [函数服务](https://console.volcengine.com/vefaas) 或 [API 网关](https://console.volcengine.com/veapig) 的控制台页面。 -2. 在页面弹出的授权提示中，单击 **立即授权**。 -3. 授权成功后，系统会自动跳转至对应服务的控制台主页，表明服务已成功开通。 +1. 访问 [函数服务](https://console.volcengine.com/vefaas) 或 [API 网关](https://console.volcengine.com/veapig) 的控制台页面。 +2. 在页面弹出的授权提示中，单击 **立即授权**。 +3. 授权成功后，系统会自动跳转至对应服务的控制台主页，表明服务已成功开通。 > ⚠️ **注意**：此授权步骤是必需的，它授予函数服务和 API 网关访问其他云资源的权限，以确保应用能够正常部署和运行。 - ### 函数服务 + 1. 首次进入 [函数服务](https://console.volcengine.com/vefaas) 页面，控制台将会提醒你进行IAM角色的开通，请点击【立即授权】同意角色开通。 ![IAM 角色开通](./assets/images/deploy/vefaas_attach_role.png) 2. 点击后，控制台将会显示你已完成授权。几秒后将会自动跳转会 [函数服务](https://console.volcengine.com/vefaas) 控制台。当展示如下页面时，[函数服务](https://console.volcengine.com/vefaas) 服务即开通成功。 ![IAM 角色开通](./assets/images/deploy/vefaas_index.png) + ### API网关 + 1. 首次进入 [API网关](https://console.volcengine.com/veapig) 页面，控制台将会提醒你进行IAM角色的开通，请点击【立即授权】同意角色开通。 ![IAM 角色开通](./assets/images/deploy/veapig_attach_role.png) 2. 点击后，控制台将会显示你已完成授权。几秒后将会自动跳转会 [API网关](https://console.volcengine.com/veapig) 控制台。当展示如下页面时，[API网关](https://console.volcengine.com/veapig) 服务即开通成功。 @@ -37,9 +43,9 @@ title: 部署到火山引擎 Veadk 提供多种部署方式以适应不同的开发工作流： -* **通过命令行工具 (CLI) 部署**：最快捷的方式，适合快速创建、部署和迭代 Agent 应用。 -* **通过 Python SDK 部署**：允许你通过编写代码以编程方式管理部署流程，适合集成到自动化脚本或现有项目中。 -* **设置持续交付 (CI/CD)**：与代码仓库（如 GitHub）集成，实现代码提交后自动构建和部署，是团队协作和生产环境的最佳实践。 +* **通过命令行工具 (CLI) 部署**：最快捷的方式，适合快速创建、部署和迭代 Agent 应用。 +* **通过 Python SDK 部署**：允许你通过编写代码以编程方式管理部署流程，适合集成到自动化脚本或现有项目中。 +* **设置持续交付 (CI/CD)**：与代码仓库（如 GitHub）集成，实现代码提交后自动构建和部署，是团队协作和生产环境的最佳实践。 接下来，我们将详细介绍每种部署方式的操作步骤。 @@ -81,16 +87,17 @@ Run python `deploy.py` for deployment on Volcengine FaaS platform. **参数说明**： -* **Local directory name**：项目在本地创建的目录名称。 -* **Volcengine FaaS application name**：你的应用在火山引擎函数服务平台的名称。**注意**：名称中不能包含下划线 `_`。 -* **Volcengine API Gateway ...**：API 网关相关的实例、服务和上游名称。这些为**可选**参数。如果留空，Veadk 会在部署时自动创建和关联相应的网关资源。 -* **Choose a deploy mode**：选择部署模式。 - * `A2A/MCP Server`：标准的后端 Agent 服务模式。 - * `VeADK Web / Google ADK Web`：如果你需要一个 Web 交互界面，请选择此项。 +* **Local directory name**：项目在本地创建的目录名称。 +* **Volcengine FaaS application name**：你的应用在火山引擎函数服务平台的名称。**注意**：名称中不能包含下划线 `_`。 +* **Volcengine API Gateway ...**：API 网关相关的实例、服务和上游名称。这些为**可选**参数。如果留空，Veadk 会在部署时自动创建和关联相应的网关资源。 +* **Choose a deploy mode**：选择部署模式。 + * `A2A/MCP Server`：标准的后端 Agent 服务模式。 + * `VeADK Web / Google ADK Web`：如果你需要一个 Web 交互界面，请选择此项。 项目初始化完成后，你可以在生成的 `deploy.py` 文件中随时修改这些配置。 生成后的项目结构如下： + ```shell veadk-cloud-proj ├── __init__.py @@ -112,9 +119,9 @@ veadk-cloud-proj 部署前，你需要配置必要的环境变量，特别是访问火山引擎所需的身份凭证。 -1. 在项目根目录下，将 `config.yaml.example` 文件复制一份并重命名为 `config.yaml`。 -2. 编辑 `config.yaml` 文件，填入你的火山引擎访问密钥 (Access Key 和 Secret Key)。 -3. 如果是新建的火山账号，还需确认是否已经授权给`ServerlessApplicationRole`角色。进入[创建应用页面](https://console.volcengine.com/vefaas/region:vefaas+cn-beijing/application/create?templateId=67f7b4678af5a6000850556c)点击[一键授权]即可。 +1. 在项目根目录下，将 `config.yaml.example` 文件复制一份并重命名为 `config.yaml`。 +2. 编辑 `config.yaml` 文件，填入你的火山引擎访问密钥 (Access Key 和 Secret Key)。 +3. 如果是新建的火山账号，还需确认是否已经授权给`ServerlessApplicationRole`角色。进入[创建应用页面](https://console.volcengine.com/vefaas/region:vefaas+cn-beijing/application/create)点击[一键授权]即可。 ![一键授权](./assets/images/deploy/add_permission.png) ```yaml @@ -141,13 +148,15 @@ Test message: How is the weather like in Beijing? ``` ### 方式二：部署现有项目 + 如果你已经有一个本地开发的 Agent 项目，可以使用 `veadk deploy` 命令将其快速部署到火山引擎函数服务平台。 #### 1. 项目准备 + 在执行部署前，请确保你的项目满足以下结构要求： -* 项目根目录下必须包含一个 `agent.py` 文件，且该文件中定义了一个全局变量 `root_agent`。 -* 项目根目录下必须包含一个 `__init__.py` 文件，且该文件中包含了 `from . import agent` 语句。 +* 项目根目录下必须包含一个 `agent.py` 文件，且该文件中定义了一个全局变量 `root_agent`。 +* 项目根目录下必须包含一个 `__init__.py` 文件，且该文件中包含了 `from . import agent` 语句。 #### 2. 执行部署 @@ -173,8 +182,8 @@ veadk deploy --vefaas-app-name 「YourAgentAppName} | --use-adk-web | FLAG | 设置后将会在云端启动 web，否则为 A2A / MCP 模式 | | ---path | 字符串 | 本地项目路径，默认为当前目录 | - ## 通过 Python SDK 部署 + 对于希望将部署流程集成到自动化脚本或现有代码库中的开发者，Veadk 提供了强大的 Python SDK。你可以通过 `CloudAgentEngine` 类以编程方式完成应用的部署、更新和删除。 ### 1. 部署 Agent 应用 @@ -265,8 +274,10 @@ print(f"Agent response: {response}") ``` #### 更新应用代码 + 当你本地的 Agent 代码有更新时，可以使用 `update_function_code` 方法来更新已部署的应用，而无需重新创建一个新应用。 > ⚠️ **注意**：此操作只会更新函数的代码和配置，应用原有的访问端点 (Endpoint) 会保持不变。 + ```python from veadk.cloud.cloud_agent_engine import CloudAgentEngine @@ -279,8 +290,8 @@ updated_cloud_app = engine.update_function_code( ) # 可以使用updated_cloud_app.vefaas_endpoint访问您的项目 - ``` + #### 删除应用 如果你需要下线并删除一个已部署的应用，可以使用 `remove` 方法。 @@ -304,17 +315,19 @@ engine.remove(app_name="my-python-agent") Confirm delete cloud app my-python-agent? (y/N): y ``` - ## 验证与调用应用 + 应用部署成功后，你可以通过火山引擎控制台验证部署状态，并使用不同协议与你的 Agent 服务进行交互。 ### 在控制台验证部署 + 1. 登录 [火山引擎函数服务 (veFaaS) 控制台](https://console.volcengine.com/vefaas)。 2. 在左侧导航栏中，选择 **我的应用**。 -1. 在应用列表中，你应该能看到你刚刚部署的应用。你可以单击应用名称进入详情页，查看其配置、日志、监控和访问端点等信息。 +3. 在应用列表中，你应该能看到你刚刚部署的应用。你可以单击应用名称进入详情页，查看其配置、日志、监控和访问端点等信息。 ![部署完成](./assets/images/deploy/deploy_agent.png) ### 调用方法 + 部署完成后，Veadk Agent 服务支持通过两种标准协议进行调用：A2A (Agent-to-Agent) 和 MCP (Meta-protocol for Calling Plugins)。 > **关于 API 网关认证**： @@ -324,9 +337,9 @@ Confirm delete cloud app my-python-agent? (y/N): y #### 1. 获取认证凭证 (Key Auth Token) -1. 登录 [API 网关控制台](https://console.volcengine.com/veapig)。 -2. 在左侧导航栏中，选择 **消费者管理**。 -3. 找到与你的应用关联的消费者，并复制其 **Key Auth Token**。 +1. 登录 [API 网关控制台](https://console.volcengine.com/veapig)。 +2. 在左侧导航栏中，选择 **消费者管理**。 +3. 找到与你的应用关联的消费者，并复制其 **Key Auth Token**。 #### 2. 通过 A2A 协议调用 diff --git a/docs/docs/evaluation.md b/docs/docs/deploy/evaluation.md similarity index 100% rename from docs/docs/evaluation.md rename to docs/docs/deploy/evaluation.md diff --git a/docs/docs/optimization.md b/docs/docs/deploy/optimization.md similarity index 99% rename from docs/docs/optimization.md rename to docs/docs/deploy/optimization.md index 48a9b797..be3d330b 100644 --- a/docs/docs/optimization.md +++ b/docs/docs/deploy/optimization.md @@ -130,6 +130,7 @@ veadk rl run --platform lightning --server #### 原理说明 生成后的项目结构如下，其中核心文件包括： + - agent_client: `examples/*/*_agent.py` 中定义了agent的rollout逻辑和reward规则 - training_server: `examples/*/train.py` 定义了训练相关参数,用于启动训练服务器 diff --git a/docs/docs/observation/ve-tracing.md b/docs/docs/observation/ve-tracing.md index 1dde4b99..5b2e6b46 100644 --- a/docs/docs/observation/ve-tracing.md +++ b/docs/docs/observation/ve-tracing.md @@ -164,7 +164,7 @@ python agent.py ### 准备工作 -#### veADK代码中创建tracing project和实例 +#### VeADK代码中创建tracing project和实例 ```yaml title="config.yaml" model: diff --git a/docs/docs/quickstart.md b/docs/docs/quickstart.md index 47d09746..13ce1a23 100644 --- a/docs/docs/quickstart.md +++ b/docs/docs/quickstart.md @@ -4,11 +4,35 @@ title: 快速开始 ## 安装 -您可以从 PyPI 中安装最新版的 VeADK： +=== "✨ 使用 UV 安装" -```bash -pip install veadk-python -``` + 我们推荐您使用 `uv` 包管理工具来安装 VeADK，您可以遵循以下步骤： + + ```bash + # 使用 `uv` 来创建一个基于 Python 3.10 版本的虚拟环境 + uv venv --python 3.10 + + # 激活 `uv` 环境 + source .venv/bin/activate + ``` + + 环境激活后，您可以看到您的命令行开头会有括号标注的虚拟环境名称（通常为您的所在目录名称）： + + ![img](./assets/images/uv_demo.jpeg) + + 您可以使用已经激活的虚拟环境来安装 VeADK： + + ```bash + uv pip install veadk-python + ``` + +=== "使用 PIP 安装" + + 您可以直接使用 `pip` 命令从 PyPI 中安装最新版的 VeADK： + + ```bash + pip install veadk-python + ``` 您可以通过运行如下命令来检测您的 VeADK 是否安装成功： diff --git a/docs/docs/tools/builtin.md b/docs/docs/tools/builtin.md index e6428206..fa700378 100644 --- a/docs/docs/tools/builtin.md +++ b/docs/docs/tools/builtin.md @@ -1,7 +1,7 @@ # 内置工具使用指南 -本文档旨在说明如何有效利用 veADK 内置工具（BuiltinTools）。这些工具提供了即用型功能（如网页搜索或代码执行器），赋予 Agent 通用能力。例如，需要从网络检索信息的 Agent 可直接使用 **web_search** 工具，无需额外配置。 +本文档旨在说明如何有效利用 VeADK 内置工具（BuiltinTools）。这些工具提供了即用型功能（如网页搜索或代码执行器），赋予 Agent 通用能力。例如，需要从网络检索信息的 Agent 可直接使用 **web_search** 工具，无需额外配置。 ## 使用方法 @@ -56,7 +56,7 @@ ## 工具列表 -veADK 集成了以下火山引擎工具： +VeADK 集成了以下火山引擎工具： | 工具名称 | 功能说明 | 导入路径 | | :--- | :--- | :--- | @@ -606,7 +606,7 @@ veADK 集成了以下火山引擎工具： ### AgentKit 沙箱工具（Tools） - AgentKit 沙箱工具提供了多种智能体在执行任务中需要的运行环境工具，支持快速集成与便捷调用，同时veADK提供了更多内置工具。 + AgentKit 沙箱工具提供了多种智能体在执行任务中需要的运行环境工具，支持快速集成与便捷调用，同时VeADK提供了更多内置工具。 一体化工具集包含 Browser、Terminal、Code 运行环境，支持自动根据任务切换。 **创建沙箱** 按以下步骤操作： diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 05ace43d..6ab96c06 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -71,9 +71,10 @@ nav: - 在火山引擎观测: observation/ve-tracing.md - 埋点与字段规范: observation/span-attributes.md - 部署与持续优化: - - 部署到火山引擎: deploy.md - - 评测: evaluation.md - - 持续优化: optimization.md + - 部署到 AgentKit: deploy/deploy-agentkit.md + - 部署到 VeFaaS: deploy/deploy-vefaas.md + - 评测: deploy/evaluation.md + - 持续优化: deploy/optimization.md - 命令行工具: cli.md - 参考: - API References: references/api.md @@ -121,6 +122,10 @@ plugins: - memory/long-term-memory.md - observation/tracing.md - observation/ve-tracing.md + - deploy/deploy-vefaas.md + - deploy/deploy-agentkit.md + - deploy/evaluation.md + - deploy/optimization.md extra: social: