文档中心

AgentKit

进阶入门：开发并部署 Agent

使用 VeADK 开发并部署 Agent

本文主要为您介绍，如何通过 VeADK 在本地开发、调试智能体（Agent），并通过 AgentKit 将其快速发布为智能体运行时（Agent Runtime）的完整流程。

背景信息

VeADK（Volcengine Agent Development Kit）是火山引擎提供的 Agent 开发框架，它将模型、工具、记忆、知识库等能力组合成可复用的组件，内置了工具调用、多轮对话、记忆管理等核心能力，并提供标准化的项目结构和本地调试工具，让您可以在不依赖云端环境的情况下完成 Agent 的全流程开发。了解更多

VeADK 与火山引擎生态深度集成，基于该框架构建的 Agent 还可借助 AgentKit 获得如下能力：

服务调用：调用 AgentKit 提供的 MCP、记忆库、知识库等各类服务，快速复用平台能力。

云端发布：通过 AgentKit 无缝发布至云端，降低本地开发与云端部署的适配成本。

持续优化：借助 AgentKit 的评测、观测等能力，持续优化 Agent 效果。

说明

使用智能 IDE 基于 VeADK 开发 Agent 时，还可为其配置 VeADK 提示词（llms.txt）。配置后，IDE 在开发过程中可以充分理解 VeADK 的功能特性和使用规范，提供更精准的代码补全、智能提示和开发建议，显著提升开发效率和质量。了解更多

构建和部署 Agent 工作流

前提条件

条件	要求
注册账号	已完成账号注册和实名认证。
开通服务	已开通 AgentKit 服务。若未开通，请登录 AgentKit 控制台，根据系统引导开通产品。说明首次登录 AgentKit 服务控制台，平台将默认勾选使用 AgentKit 基础功能的必备依赖产品（包含函数服务、API 网关、镜像仓库等），您也可以根据实际业务需求，勾选所需的其他产品，然后单击“批量开通并授权”按钮确认“AgentKit 依赖服务开通及跨服务授权”，允许 AgentKit 服务使用已选择的产品。
开通服务		已开通火山方舟模型服务。
获取调用密钥	已创建并获取用于火山方舟访问模型服务的 API Key。
获取调用密钥		已创建并获取用于调用火山引擎云资源的 API 访问密钥（Access Key ID 与 Secret Access Key）。了解更多

环境配置

推荐您使用uv工具管理 Python 环境，将 AgentKit 相关依赖放进独立虚拟环境，避免影响您终端内运行的其他 Python 项目。

登录您需要安装 VeADK 和 AgentKit SDK 的终端。

执行如下命令，确认其 Python 版本不低于 3.10。

python --version

执行如下命令，下载并安装 uv 工具。

使用 curl 工具
使用 wget 工具

curl -LsSf https://astral.sh/uv/install.sh | sh

执行如下命令，创建并激活 uv 环境。本文以创建并激活一个基于 Python 3.13 版本且名称为 .venv 的虚拟环境为例。

uv venv --python 3.13 .venv
source .venv/bin/activate

环境激活后，您可以看到您的命令行开头会有括号标注的虚拟环境名称。

执行如下命令，在已激活的虚拟环境中安装 VeADK 与 AgentKit SDK。

uv pip install -U veadk-python

执行如下命令，检测是否安装成功。

veadk --version

若回显类似如下信息，则表示安装成功。

开发 Agent

步骤一：初始化应用

（可选）若您退出了虚拟环境，请执行如下命令重新激活。否则，请跳过本步骤。

source .venv/bin/activate

执行如下命令，通过平台预置的项目模版生成 Agent。

veadk create

执行过程中，请根据提示填写如下信息。

自定义 Agent 项目名称，同时该名称也将会成为您的本地目录名称，如personal_assistant，按回车键确认。

输入数字1或2选择何时配置调用方舟模型服务的 API Key（本文选择 2 ），按回车键确认。

1：现在指定方舟 API Key。

2：跳过填写，后续手动填写到环境变量文件中，或自动通过火山引擎 AK/SK 获取。

输入完毕后，您本地的项目结构如下：

your_project
├── __init__.py # 模块导出文件
├── .env # 环境变量文件，需要在这里配置您所需的环境变量信息
└── agent.py # Agent 定义文件

步骤二：编写 Agent 代码

本示例以调用了 AgentKit 的“个人助手 Agent”为例，展示使用了多个核心组件的简单个人助手 Agent 构建流程。

说明

您可以参考 VeADK 文档，根据实际业务场景开发 Agent。复杂场景 Agent 可查看 Agent 示例与详细指导教程。

核心功能

创建一个简单的个人助手 Agent。

短期记忆：使用本地内存维护对话上下文。

长期记忆：支持会话记忆和用户历史记录存储，通过 Viking 向量数据库。

工具集成：支持代码执行工具和 MCP 工具集。

Agent 能力

Agent 代码

在创建了 Agent 的虚拟环境中执行如下命令，进入项目根目录。

执行如下命令，打开 agent.py 文件。

vim agent.py

按i键进入编辑模式，复制如下内容并替换 agent.py 文件原有内容。

import asyncio
import os

from veadk import Agent, Runner # 导入 VeADK 定义 Agent 的核心类和运行器
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 # 导入 Google ADK 回调上下文类，用于在 after_agent_callback 中获取当前会话并写入长期记忆
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())

按esc键退出编辑模式，输入:wq保存并退出文件。

步骤三：创建组件并获取环境变量

核心组件

组件	描述
Agent 服务	agent.py - 主应用程序，定义 Agent、记忆、知识库和工具组件。
短期记忆	使用本地内存存储会话上下文。
长期记忆	使用 AgentKit 记忆库中的 Viking 记忆库支持跨会话记忆存储和检索。说明本文以 Viking 记忆库为例进行介绍，可按需更换使用 Mem0 类型记忆库。
知识库	使用 AgentKit 知识库作为个人知识库，支持上传自定义文件。
沙箱模板	使用 AgentKit 沙箱模板 AIO Sandbox 作为代码任务执行工具。
MCP 工具集	使用 AgentKit MCP 工具集来自定义的 MCP 工具。
环境变量配置	.env维护所需环境变量。

获取环境变量

工具

上述 Agent 代码中使用了run_code模块能力，用于执行代码。该模块对应 AgentKit 的沙箱模板组件，需提前创建对应组件并获取环境变量。

创建工具。

获取环境变量：工具创建完成后，在工具详情页的“集成代码”页签中，获取工具需配置的环境变量信息。

记忆库

上述 Agent 代码中使用了 LongTermMemory 模块能力，用于存储和检索跨会话的记忆。该模块对应 AgentKit 的记忆库组件，需提前创建对应组件并获取环境变量。

创建 Viking 记忆库或导入 Viking 记忆库。

可按需更换为 Mem0 类型记忆库。

获取环境变量：在目标记忆库详情页的“集成代码”页签中，获取记忆库需配置的环境变量信息。

知识库

上述 Agent 代码中使用了 Knowledge 模块能力，用于存储和检索知识。该模块对应 AgentKit 的知识库组件，需提前创建对应组件并获取环境变量。

创建知识库：在向量数据库中创建 Viking 知识库并上传文件（可按个人需求上传新闻、个人笔记等材料，便于进行上述 Agent 的功能测试）。

导入知识库：导入刚创建的知识库。

获取环境变量：知识库创建完成后，单击知识库名称进入详情页面，选择“集成代码”，获取知识库需配置的环境变量信息。

MCP 工具集

上述 Agent 代码中使用了mcp_router模块能力，用于通过语义搜索自动匹配与调用意图最相关的工具。该模块对应 AgentKit 的 MCP 工具集组件，需提前创建对应组件并获取环境变量。

创建 MCP 服务：按照您的需要新建和导入MCP工具（如：Sequential Thinking MCP、地图 MCP 等）。

创建 MCP 工具集：选择需要挂载在工具集中的MCP服务。

获取环境变量：在 MCP 工具集详情页面获取访问域名 url 和入站身份认证的 API Key。

步骤四：配置环境变量

环境变量介绍

VeADK模块名称	对应AgentKit组件	对应环境变量
run_code	沙箱模板—AIO Sandbox	AGENTKIT_TOOL_ID=xxx #沙箱模板 ID。 AGENTKIT_TOOL_REGION=xxx #非必传，默认为华北2（北京）地域 cn-beijing。
KnowledgeBase	知识库—Viking	DATABASE_VIKING_COLLECTION=xxx #知识库名称。 DATABASE_VIKING_PROJECT=xxx #非必填，默认为 default 项目。 DATABASE_VIKING_BASE_URL="<PrivateLink URL for VPC access only, possibly starts with http://>" #内网访问域名，仅设置内网访问时需要传入。
LongTermMemory	记忆库—Viking	DATABASE_VIKINGMEM_COLLECTION=xxx #记忆库名称。 DATABASE_VIKINGMEM_MEMORY_TYPE=xxx #配置的记忆策略，多个策略使用逗号分隔。 DATABASE_VIKINGMEM_BASE_URL="<PrivateLink URL for VPC access only, possibly starts with http://>" #内网访问域名，仅设置内网访问时需要传入。 DATABASE_VIKINGMEM_PROJECT="default" #非必填，默认为 default 项目。
LongTermMemory	记忆库—Mem0 说明本示例未使用Mem0记忆库，可按需更换使用Mem0类型记忆库。	DATABASE_MEM0_BASE_URL=xxx #记忆库的访问域名。 DATABASE_MEM0_API_KEY=xxx #记忆库入站身份认证的 API Key。
mcp_router	MCP工具集	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 时，推荐通过终端会话级环境变量导出的方式管理。

export VOLCENGINE_ACCESS_KEY=<your_access_key>
export VOLCENGINE_SECRET_KEY=<your_secret_key>

在.env中配置其他环境变量

在创建了 Agent 的虚拟环境中执行如下命令，进入项目根目录。

执行如下命令，打开.env文件。

vim .env

按i键进入编辑模式，填写 Agent 需配置的环境变量。

AGENTKIT_TOOL_ID=t-xxx #沙箱模板 ID
AGENTKIT_TOOL_REGION=xxx #非必传，默认为华北2（北京）地域 cn-beijing。
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

按esc键退出编辑模式，输入:wq保存并退出文件。

步骤五：本地调试

使用 VeADK Web 调试界面

cd ..

（可选）若您退出了虚拟环境，请执行如下命令重新激活。否则，请跳过本步骤。

source .venv/bin/activate

启动 VeADK Web 界面。

veadk web

回显如下所示时，表示已成功启动 VeADK Web 界面，请根据界面提示获取访问 Web 界面的链接。

在您项目所在终端的本地浏览器中，访问上一步获取 VeADK Web 界面访问地址，本文为http://127.0.0.1:8000。

进入页面后，按如下顺序进行验证。

在左侧下拉列表中选择目标 Agent（即项目名称，例如personal_assistant）。

在底部对话框中发送一条消息，例如“介绍下你自己”。

确认目标 Agent 可以正常回复。

部署 Agent

本地调试无问题后，可使用 AgentKit 提供的 CLI 工具将 Agent 快速部署到云上。

步骤一：初始化待部署项目

（可选）若您退出了虚拟环境，请执行如下命令重新激活。否则，请跳过本步骤。

source .venv/bin/activate

执行如下命令，初始化 Agent 应用。

说明

请将 agent.py 替换为您 Agent 的定义文件名称。了解更多

agentkit init --from-agent ./agent.py

初始化会自动生成以下文件：

agentkit-agent.py ：Agent 应用入口文件。将自动将您的 Agent 封装成符合 AgentKit 标准的 HTTP 服务，默认将封装成 AgentkitSimpleApp 应用框架，如希望使用其他应用框架可参考 SDK概述。

requirements.txt：Python 依赖。

agentkit.yaml ：配置文件。

.dockerignore：构建 Docker 时需要忽略的文件或目录。

步骤二：发布 Agent

（可选）若您退出了虚拟环境，请执行如下命令重新激活。否则，请跳过本步骤。

source .venv/bin/activate

执行如下命令，发布 Agent。

agentkit launch

说明

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

当回显如下所示时，表示已成功将本地 Agent 发布为 Agentkit 智能体运行时。

在线测试 Agent

发布成功后，您可以前往智能体运行时控制台在线测试 Agent。

在左侧导航树中，选择“基础组件 > 智能体运行时”。

单击目标 Agent 右侧“操作”列的“在线测试”按钮。

在 Body 类型模块中，选择 raw 并输入测试参数（本文调整 Prompt 为“介绍下自己，看看你有哪些MCP工具可用”），单击“调试”按钮发起 POST 请求。更多调试参数详情，请参见调用 Agent。

在调试结果模块，确认状态码为 200，并验证返回内容符合预期。

观测与评测 Agent

Agent 发布并完成在线测试后，建议您继续通过 AgentKit 提供的观测和评测能力验证其运行状态与实际效果，逐步完成“是否稳定可用”到“足够好、值得上线”的优化。

观测 Agent

观测用于查看 Agent 在真实调用过程中的运行表现，帮助您发现链路异常、模型调用异常、日志报错或性能瓶颈。开启数据观测后，AgentKit 与 VeADK SDK 会基于 OpenTelemetry 自动采集各环节（例如模型调用、工具执行、记忆库检索等）的 Trace（调用链）与 Metrics（指标）的 Trace（调用链）与 Metrics（指标），并将数据投递至观测平台。

您可以在“数据观测”页面查看 Agent 的运行时监控、会话分析、Trace 分析、模型监控、日志分析。了解更多

评测 Agent

评测用于通过标准化实验衡量 Agent 在效果、性能和成本三个维度的表现，帮助您判断当前版本是否满足预期，并为后续优化迭代及上线提供依据。

评测机制通常由三部分组成：评测集、评估器和实验。其中，评测集用于提供标准化输入与参考答案；评估器可以基于 LLM 或 Code 按既定规则打分；实验则负责组合执行、聚合结果指标，并支持多实验之间的对比分析。了解更多

后续操作

Agent 上线后，您还可以在控制台中随时更新其实例规格、自定义镜像、模型、环境变量等配置。了解更多

注意

更新智能体运行时配置后，需重新发布使新配置生效。了解更多

最近更新时间：2026.08.21 14:19:06

这个页面对您有帮助吗？

有用

无用