本文以使用VeADK框架为例，指导您如何使用VeADK和AgentKit快速上手智能体开发、部署到管理的全流程。 ## 背景信息 VeADK提供了`llms.txt`作为智能IDE可使用的关于VeADK的提示词，使智能IDE在开发过程中能充分理解VeADK的功能特性和使用规范，提供更精准的代码补全、智能提示和开发建议，显著提升基于VeADK的开发效率和质量。详细信息，请参见[系统提示词](https://volcengine.github.io/veadk-python/cn/docs/framework/community/ide-support/)。 ## 前提条件 * 请确认已完成[账号注册](https://www.volcengine.com/docs/6261/64925)和[实名认证](https://www.volcengine.com/docs/6261/64935)。 * 已开通AgentKit服务。若未开通，请登录[AgentKit控制台](https://console.volcengine.com/AgentKit)，根据系统引导开通产品。 > 首次登录AgentKit服务控制台，平台将默认勾选使用AgentKit基础功能的必备依赖产品（包含函数服务、API网关、镜像仓库等），您也可以根据实际业务需求，勾选所需的其他产品，然后单击“批量开通并授权”按钮确认“AgentKit依赖服务开通及跨服务授权”，允许AgentKit服务使用已选择的产品。 > ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_6a181e6e0aff566d7aeafd836dde4ebf.jpeg) * 已[开通火山方舟模型服务](https://console.volcengine.com/ark/openManagement)，并创建[API Key](https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey?apikey=%7B%7D)。 * 登录平台控制台[获取AK/SK](https://www.volcengine.com/docs/6291/65568)，进入[API访问密钥](https://console.volcengine.com/iam/keymanage/)页面，创建并获取**Access Key ID**和**Secret Access Key**。 ## 环境配置推荐您使用`uv`包管理工具来安装VeADK和AgentKit SDK，以确保VeADK和AgentKit SDK安装不会影响系统其他Python项目，也不会被其他项目的依赖影响。 1. 安装uv工具。 ```Python # 使用 curl 下载并安装 curl -LsSf https://astral.sh/uv/install.sh | sh # 或使用 wget 下载并安装 wget -qO- https://astral.sh/uv/install.sh | sh ``` 2. 创建并激活uv环境。环境激活后，您可以看到您的命令行开头会有括号标注的虚拟环境名称（通常为您的所在目录名称）。 ```Bash # 使用 `uv` 来创建一个基于 Python 3.12 版本的虚拟环境 uv venv --python 3.12 # 激活 `uv` 环境 source .venv/bin/activate ``` 3. 使用已经激活的虚拟环境来安装VeADK和AgentKit SDK。 ```Bash uv pip install -U veadk-python ``` 4. 检测是否安装成功。 ```Bash # 检查veadk是否安装成功 veadk --version ``` 若回显类似如下信息，则表示安装成功。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_0d10f2c01f3f1f4df97a6fd108ff1eb4.png) ## 开发智能体 ### **步骤一：初始化应用** 执行以下命令，生成一个预制好的Agent项目模板。 ```Bash veadk create ``` 您将被提示输入如下信息： * 项目名称（同时也将会成为您的本地目录名称，如`personal_assistant`） * 方舟平台API Key（可跳过，支持后续手动填写到环境变量文件中或自动通过火山引擎AK/SK获取）输入完毕后，您本地的项目结构如下： ```Bash your_project ├── __init__.py # 模块导出文件 ├── .env # 环境变量文件，需要在这里配置您所需的环境变量信息 └── agent.py # Agent 定义文件 ``` ### **步骤二：编写智能体代码** 参考[VeADK](https://volcengine.github.io/veadk-python/cn/docs/framework/)文档，根据您的业务场景开发智能体。复杂场景智能体可查看[智能体示例](https://github.com/volcengine/agentkit-samples/tree/main/02-use-cases)与[详细指导教程](https://github.com/volcengine/agentkit-samples/tree/main/01-tutorials)。本示例以调用了AgentKit的“个人助手智能体”为例，展示使用了多个核心组件的简单个人助手Agent构建流程。 #### **核心功能** * 创建一个简单的个人助手Agent。 * 短期记忆：使用本地内存维护对话上下文。 * 长期记忆：支持会话记忆和用户历史记录存储，通过Viking向量数据库。 * 工具集成：支持代码执行工具和MCP工具集。 #### **Agent能力** ```Plain Text 用户消息 ↓ AgentKit 运行时 ↓ 个人助手 Agent ├── VeADK Agent (对话引擎) ├── ShortTermMemory (短期记忆) ├── LongTermMemory (长期记忆) ├── KnowledgeBase (个人知识库) ├── run_code (代码执行工具) ├── mcp_router (MCP工具集) └── 火山方舟模型 (LLM) ``` #### **Agent代码** 1. 进入项目。 ```Bash cd <项目内容> ``` 2. 打开**agent.py文件**。 ```Bash vim agent.py ``` 3. 复制以下内容，替换**agent.py**内容。 ```Bash import asyncio import os from veadk import Agent, Runner # 导入veADK定义智能体的核心类和运行器 from veadk.knowledgebase import KnowledgeBase # 导入知识库组件，可以存储和检索文档知识 from veadk.memory import LongTermMemory, ShortTermMemory # 导入记忆组件 from veadk.tools.builtin_tools.run_code import run_code # 导入代码沙箱工具 from veadk.tools.builtin_tools.mcp_router import mcp_router # 导入MCP工具集 from google.adk.agents.callback_context import CallbackContext #导入call_back函数 from dotenv import load_dotenv load_dotenv() memory_name = os.getenv("DATABASE_VIKINGMEM_COLLECTION") if not memory_name: raise ValueError("DATABASE_VIKINGMEM_COLLECTION environment variable is not set") # 使用viking作为长期记忆存储，可按需切换 mem0 long_term_memory = LongTermMemory(backend="viking", index=memory_name) # 使用本地内存作为短期记忆，如需持久化backend可配置为mysql，需提前在火山创建数据库 short_term_memory = ShortTermMemory(backend="local") knowledge_name = os.getenv("DATABASE_VIKING_COLLECTION") if not knowledge_name: raise ValueError("DATABASE_VIKING_COLLECTION environment variable is not set") # 使用viking作为知识库存储 knowledgebase = KnowledgeBase(backend="viking", index=knowledge_name) # 定义异步回调函数，用于在代理执行完成后获取当前会话并将其添加到长期记忆存储中 async def after_agent_execution(callback_context: CallbackContext): session = callback_context._invocation_context.session await long_term_memory.add_session_to_memory(session) # 定义个人助手Agent personal_assistant = Agent( name="personal_assistant", description="一个智能个人助手，可以帮助用户管理日常事务和提供信息。", instruction="""你是一个友好的智能个人助手，请用简洁明了的语言回答用户的问题。如果用户询问与知识库相关的信息，请使用知识库检索。如果用户提到个人偏好或重要信息，请将其存储到长期记忆中。如果需要执行代码生成任务，请使用代码沙箱工具。如果需要执行其他任务，请选取合适的MCP工具。 """, short_term_memory=short_term_memory, long_term_memory=long_term_memory, knowledgebase=knowledgebase, tools=[run_code, mcp_router], after_agent_callback=after_agent_execution, ) # 使用veadk web进行调试 root_agent = personal_assistant async def main(): """运行个人助手的主函数""" print("欢迎使用智能个人助手！") print("输入 'exit' 或 'quit' 退出程序。") print("=" * 50) # 创建智能体运行器 runner = Runner( agent=personal_assistant, app_name="personal_assistant_demo", user_id="demo_user", short_term_memory=short_term_memory ) while True: user_input = input("请输入您的问题: ") if user_input.lower() in ["exit", "quit", "退出"]: print("再见！") break try: # 运行agent并获取响应 response = await runner.run(messages=user_input) print(f"助手: {response}") except Exception as e: print(f"发生错误: {e}") print("=" * 50) if __name__ == "__main__": asyncio.run(main()) ``` ### 步骤三：组件创建**与环境变量获取** #### **核心组件** |**组件** |描述 | |---|---| |**Agent 服务** |`agent.py` \- 主应用程序，定义Agent、记忆、知识库和工具组件。 | |**短期记忆** |使用本地内存存储会话上下文。 | |**长期记忆** |使用AgentKit记忆库中的Viking记忆库支持跨会话记忆存储和检索。

说明

本文以Viking记忆库为例进行介绍，可按需更换使用Mem0类型记忆库。

| |**知识库** |使用AgentKit知识库作为个人知识库，支持上传自定义文件。 | |**沙箱工具** |使用AgentKit沙箱工具AIO Sandbox作为代码任务执行工具。 | |**MCP工具集** |使用AgentKit MCP工具集来自定义的MCP工具。 | |**环境变量配置** |`.env`维护所需环境变量。 | * 工具上述[Agent代码](https://www.volcengine.com/docs/86681/2155817#u5nJc2wH)中使用了`run_code`模块能力，用于执行代码。该模块对应AgentKit的沙箱工具组件，需提前创建对应组件并获取环境变量。 1. [创建工具](https://www.volcengine.com/docs/86681/1847934)。 2. 获取环境变量：工具创建完成后，在工具详情页的“集成代码”页签中，获取工具需配置的环境变量信息。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_1ad5ac45ac12ee2c4b6469abb03b0203.png) * 记忆库上述[Agent代码](https://www.volcengine.com/docs/86681/2155817#u5nJc2wH)中使用了LongTermMemory模块能力，用于存储和检索跨会话的记忆。该模块对应AgentKit的记忆库组件，需提前创建对应组件并获取环境变量。 1. [创建Viking记忆库](https://www.volcengine.com/docs/86681/1844843?lang=zh#24t8mgYO)或[导入Viking记忆库](https://www.volcengine.com/docs/86681/2205109)。 > 可按需更换为Mem0类型记忆库。 2. 获取环境变量：在目标记忆库详情页的“集成代码”页签中，获取记忆库需配置的环境变量信息。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_0340aa98a137135f802dad79238b235b.png) * 知识库上述[Agent代码](https://www.volcengine.com/docs/86681/2155817#u5nJc2wH)中使用了Knowledge模块能力，用于存储和检索知识。该模块对应AgentKit的知识库组件，需提前创建对应组件并获取环境变量。 1. [创建知识库](https://www.volcengine.com/docs/84313/1254463)：在向量数据库中创建Viking知识库并上传文件（可按个人需求上传新闻、个人笔记等材料，便于进行上述智能体的功能测试）。 2. [导入知识库](https://www.volcengine.com/docs/86681/1865671)：导入刚创建的知识库。 3. 获取环境变量：知识库创建完成后，单击知识库名称进入详情页面，选择“集成代码”，获取知识库需配置的环境变量信息。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_f18cbe4ace1159efd0ecfb0f5c79b153.png) * MCP工具集上述[Agent代码](https://www.volcengine.com/docs/86681/2155817#u5nJc2wH)中使用了`mcp_router`模块能力，用于通过语义搜索自动匹配与调用意图最相关的工具。该模块对应AgentKit的MCP工具集组件，需提前创建对应组件并获取环境变量。 1. [创建MCP服务](https://www.volcengine.com/docs/86681/1844857)：按照您的需要新建和导入MCP工具（如：Sequential Thinking MCP、地图MCP等）。 2. [创建MCP工具集](https://www.volcengine.com/docs/86681/1844858?lang=zh)：选择需要挂载在工具集中的MCP服务。 3. 获取环境变量：在MCP工具集详情页面获取访问域名url和入站身份认证的API Key。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_1f19f522b92d39a5f71bd9dcd5057849.png) ### 步骤四：配置环境变量 #### **环境变量介绍** | ** VeADK模块名称** |**对应AgentKit组件** |**对应环境变量** | |---|---|---| |run_code |沙箱工具—AIO Sandbox |```Bash```
```AGENTKIT_TOOL_ID=xxx #沙箱工具ID。```
```AGENTKIT_TOOL_REGION=xxx #非必传，默认为华北2（北京）地域cn-beijing。```

| |KnowledgeBase |知识库—Viking |```Python```
```DATABASE_VIKING_COLLECTION=xxx #知识库名称。```
```DATABASE_VIKING_PROJECT=xxx #非必填，默认为default项目。```
```DATABASE_VIKING_BASE_URL="" #内网访问域名，仅设置内网访问时需要传入。```
| |LongTermMemory |记忆库—Viking |```Python```
```DATABASE_VIKINGMEM_COLLECTION=xxx #记忆库名称。```
```DATABASE_VIKINGMEM_MEMORY_TYPE=xxx #配置的记忆策略，多个策略使用逗号分隔。```
```DATABASE_VIKINGMEM_BASE_URL="" #内网访问域名，仅设置内网访问时需要传入。```
```DATABASE_VIKINGMEM_PROJECT="default" #非必填，默认为default项目。```
| |LongTermMemory |记忆库—Mem0

说明

本示例未使用Mem0记忆库，可按需更换使用Mem0类型记忆库。

|```Python```
```DATABASE_MEM0_BASE_URL=xxx #记忆库的访问域名。```
```DATABASE_MEM0_API_KEY=xxx #记忆库入站身份认证的API Key。```
| |mcp_router |MCP工具集 |```Python```
```TOOL_MCP_ROUTER_URL=https://sd598mk9acju1mtc7****.apigateway-cn-beijing.volceapi.com/mcp #MCP工具集的访问域名url。```
```TOOL_MCP_ROUTER_API_KEY=xxx #MCP工具集入站身份认证的API Key。```
| #### **环境变量配置** * 在本地环境设置环境变量

注意

由于AK/SK属于高敏感凭据，直接写入.env等静态配置文件存在泄露风险，在本地开发环境中配置火山引擎AK/SK时，推荐通过终端会话级环境变量导出的方式管理。

```Bash export VOLCENGINE_ACCESS_KEY= export VOLCENGINE_SECRET_KEY= ``` * 在`.env`中配置其他环境变量上述智能体需配置的环境变量示例如下： ```Bash AGENTKIT_TOOL_ID=t-xxx #沙箱工具ID DATABASE_VIKINGMEM_COLLECTION=memory_xx #Viking记忆库名称 DATABASE_VIKINGMEM_MEMORY_TYPE=memory_summary_xxx #Viking记忆库记忆策略 DATABASE_VIKING_COLLECTION=xxx #Viking知识库名称 TOOL_MCP_ROUTER_URL=https://sd55xxxx.apigateway-cn-beijing.volceapi.com/mcp #MCP工具集访问域名url TOOL_MCP_ROUTER_API_KEY=1OtLoGxxxx #MCP工具集入站身份认证的API Key ``` ### 步骤五：本地调试 #### 使用VeADK Web调试界面 1. 进入项目目录的上级目录。 ```Bash cd .. ``` 2. 启动VeADK Web界面。 ```Bash veadk web ``` 3. 在浏览器访问：`http://127.0.0.1:8000`。左侧选择智能体（即项目名称，例如`personal_assistant`）后，先点击右侧“+ New Session”再发起会话，如下图所示： ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_37e9ee3d0f8e66bffbc1f388c98037c3.png) ## 部署智能体本地调试无问题后，可使用AgentKit提供的CLI工具将智能体快速部署到云上。 ### **初始化待部署项目** ```Bash cd <项目目录> #进入项目目录，目录名称为您veadk create时自定义的项目名称，例如personal_assistant。 agentkit init --from-agent ./agent.py #使用自研代码初始化应用，/后替换为您智能体文件名称，本示例为agent.py。 ``` 初始化会自动生成以下文件： * **agent.py** ：Agent应用入口文件。将自动将您的智能体封装成符合AgentKit标准的HTTP服务，默认将封装成AgentkitSimpleApp应用框架，如希望使用其他应用框架可参考[SDK概述](https://www.volcengine.com/docs/86681/2085106)。 * **requirements.txt**：Python依赖。 * **agentkit.yaml** ：配置文件。 * **.dockerignore**：构建Docker时需要忽略的文件或目录。 ### **发布智能体** ```Bash agentkit launch ```

说明

首次部署大约需要 2～3 分钟，请耐心等待。

当回显智能体运行时状态为**Ready**时，则表示创建成功。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_f4783a652b812fb95506d2c690deeaf1.png) 登录[AgentKit控制台](https://console.volcengine.com/agentkit)，可以查看已部署的智能体运行时实例及其详细信息。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_76cf1a5630454ae89960151dd6ffde79.png) ## 管理智能体 ### 在线测试智能体发布成功后，支持通过单击控制台的“在线测试”按钮或通过curl命令验证Agent是否正常工作。详情请参见[调试Agent](https://www.volcengine.com/docs/86681/2122004)。 ### 观测智能体调试成功后，您可以在“数据观测”页面查看Agent的运行时监控、会话分析、Trace分析、模型监控、日志分析。详情请参见[数据观测](https://www.volcengine.com/docs/86681/1873528)。 ### 评测智能体如需对发布的Agent进行系统化的能力评测，您可以在“评测 \> 实验”页面通过组合评测集、评测对象与评估器，自动执行评测，并根据结果在在效果、性能和成本方面对Agent进行优化。详情请参见[评测](https://www.volcengine.com/docs/86681/1873446)。 ### 更新智能体您可以通过控制台或OpenAPI更新已发布的智能体运行时配置，详情请参见[更新运行时](https://www.volcengine.com/docs/86681/2204794)或[ReleaseRuntime](https://www.volcengine.com/docs/86681/1923433)。