VeighNa Agent (vnag) 是一款专为AI Agent开发而设计的Python框架，致力于为开发者提供简洁、强大且易于扩展的Agent构建工具。秉承"Your Agent, Your Data"的理念，vnag让您能够完全掌控自己的AI Agent和数据流程。
vnag是VeighNa团队推出的全新AI Agent开发框架，旨在降低AI Agent开发的门槛，让更多开发者能够快速构建属于自己的智能助手。
- 🤖 可定制智能体: 轻松创建和管理多个智能体，每个都可拥有独立的角色（系统提示词）、能力（工具集）和行为模式（模型参数）。
- 🔧 双核工具体系: 同时支持简单易用的本地函数工具和功能强大的 MCP 远程工具。
- 🧠 技能系统: 两级加载机制，让智能体按需加载专业操作指南，避免上下文膨胀。
- 🔌 统一API接口：支持OpenAI兼容的各种大模型API
- 🎨 现代化UI：基于PySide6的图形化界面，不仅是聊天窗口，更是强大的智能体调试和管理工具。
- ⌨️ 命令行界面：基于Prompt Toolkit的CLI交互界面，适合终端环境下使用。
- 📝 智能对话：支持Markdown渲染的聊天界面
- 💾 数据管控：本地化的对话历史和配置管理
- 🧩 易于扩展：清晰的模块化架构，便于二次开发
- AI聊天机器人开发
- 智能客服系统
- 知识问答助手
- 个人AI助理
- 企业内部智能工具
git clone https://github.com/vnpy/vnag.git
cd vnag为了保持项目依赖的隔离，强烈建议您使用 Python 虚拟环境。
# 创建虚拟环境
python -m venv venv
# 激活虚拟环境 (Windows)
.\venv\Scripts\activate
# 激活虚拟环境 (macOS/Linux)
source venv/bin/activate# 从源码安装项目及其依赖
pip install -e .跟随以下三个步骤，您将在3分钟内启动一个功能完备的聊天机器人UI。
第1步：安装依赖
如果您已经完成了上一章节 "环境准备与安装" 的操作，那么依赖已经安装完毕，可以跳过此步。
第2步：配置API密钥
vnag 需要 API 密钥来与大模型服务进行通信。
- 请参考 "配置" 章节的说明，在
.vnag目录下创建一个connect_xxx.json文件（如connect_openai.json、connect_deepseek.json等）。 - 打开该文件，填入对应服务的 API Key 和 Base URL。
- 您也可以通过UI界面【菜单栏-功能-AI服务配置】可视化配置API服务。
第3步：运行聊天UI
一切准备就绪！在项目根目录下运行以下命令：
python examples/ui/run_chat_ui.py现在，您应该能看到一个美观的聊天窗口了！恭喜您成功运行了第一个 Agent！
运行后，您将看到一个完整的 Agent 管理界面。在这里，您可以创建和配置自己的智能体（Agent），定义它的系统提示词（System Prompt）、选择需要使用的工具、并调整模型参数（如温度）等。
vnag 0.2.0 引入了 TaskAgent 和 Profile 的概念，让您可以轻松定义和管理多个具有不同功能和行为的智能体。
核心概念:
- Agent (智能体): 一个独立的智能体实例，拥有自己的对话历史和配置。
- Profile (配置): 定义了 Agent 行为的配置模板，包括：
- 系统提示词 (Prompt): 设定 Agent 的角色和行为准则。
- 工具集 (Tools): 从本地工具和MCP工具中选择 Agent 可以使用的工具。
- 模型参数: 如
temperature,max_tokens等，用于控制模型的生成行为。需要注意的是，部分模型会固定使用1.0或忽略自定义温度。
两种方式来自定义 Agent:
-
通过UI界面（推荐）: 运行
python examples/ui/run_chat_ui.py启动图形化界面。在界面中，您可以直观地创建和管理 Profile，然后基于选定的 Profile 创建 Agent 实例进行对话。 -
通过代码:
examples/agent/run_task_agent.py脚本详细演示了如何通过代码来创建Profile对象，并使用AgentEngine来创建一个TaskAgent实例。这为您提供了更大的灵活性，可以将 vnag 集成到您自己的应用程序中。
examples 目录提供了丰富的示例脚本，帮助您快速了解和掌握 vnag 框架的各项功能。所有示例均可在项目根目录下直接运行。
| 功能模块 | 示例脚本 | 说明 |
|---|---|---|
| Gateway 网关 |
run_completion_gateway.pyrun_anthropic_gateway.pyrun_dashscope_gateway.pyrun_ollama_gateway.py |
测试与不同大模型提供商的 API 连接 |
| Segmenter 分段器 |
run_simple_segmenter.pyrun_markdown_segmenter.pyrun_python_segmenter.pyrun_cpp_segmenter.py |
将不同类型的文档切分为结构化数据段 |
| Vector 向量库 |
run_chromadb_demo.pyrun_qdrant_demo.pyrun_duckdb_demo.py |
文本向量化存储和相似度搜索 |
| RAG | run_ctp_rag.py |
完整的 RAG 流程：分段、入库、检索生成 |
| Tool 工具 |
run_local_tool.pyrun_mcp_tool.py |
本地工具和 MCP 远程工具调用 |
| Agent 智能体 |
run_task_agent.pyrun_agent_tool.py |
通过代码创建和配置 TaskAgent |
| UI 界面 |
run_chat_ui.py |
图形化智能体管理和调试界面 |
运行示例：
# 示例：测试 OpenAI Gateway
python examples/gateway/run_completion_gateway.py
# 示例：运行聊天 UI
python examples/ui/run_chat_ui.py
# 其他示例类似，将对应路径和文件名替换即可vnag 采用统一的配置文件管理机制，所有配置文件都存放在名为 .vnag 的隐藏目录中。
- 优先加载当前目录：程序启动时，会首先检查当前工作路径下是否存在
.vnag目录。如果存在，则会直接加载该目录下的所有配置文件。 - 备选用户主目录：如果当前工作路径下没有
.vnag目录，程序会自动在您的系统用户主目录（Home Directory）下寻找并使用.vnag目录。如果该目录不存在，程序会自动创建。
通过这种方式，您可以为不同的项目设置独立的本地配置，或者配置一个全局共享的配置。
每个网关对应一个 connect_{gateway_name}.json 文件，存放在 .vnag/ 目录下。
// connect_openai.json（OpenAI 及兼容接口）
{
"api_key": "sk-YourOpenAIKey",
"base_url": "https://api.openai.com/v1"
}// connect_deepseek.json（DeepSeek，支持思维链推理）
{
"api_key": "sk-YourDeepSeekKey",
"base_url": "https://api.deepseek.com"
}支持的网关：OpenAI、Anthropic、Dashscope、Ollama、DeepSeek、智谱、火山引擎、Moonshot、MiniMax、百炼、OpenRouter、LiteLLM、Bedrock、Gemini。各网关的完整配置示例请参考 Gateway 文档。
MCP 工具通过 .vnag/mcp_config.json 配置，依赖本地 Node.js 环境：
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
}
}
}vnag/
├── vnag/ # 核心框架
│ ├── agent.py # 智能体（TaskAgent / AgentTool）
│ ├── engine.py # 智能体引擎
│ ├── skill.py # 技能系统
│ ├── gateways/ # 大模型网关（15 种）
│ ├── tools/ # 内置本地工具（9 类）
│ ├── segmenters/ # RAG 分段器
│ ├── embedders/ # RAG 嵌入器
│ ├── vectors/ # RAG 向量库
│ ├── ui/ # GUI 图形界面
│ └── cli/ # CLI 命令行界面
├── examples/ # 功能示例脚本
├── skills/ # 技能文件目录
└── docs/ # 项目文档
vnag 内置了日期时间、文件系统、网络、终端与系统、代码执行、Web、联网搜索、待办管理、交互提问等 9 类本地工具，开箱即用。其中文件系统工具支持全文读取、带行号分段读取、字符串替换与按行块替换，适合代码编辑与自动化修订场景；交互工具支持模型在 GUI 或 CLI 中主动向用户提问并等待回答。完整的工具列表和使用说明请参考 Tool 文档。
| 模块 | 说明 |
|---|---|
| Agent 引擎 | ReAct 循环编排、多轮对话、Profile 配置、技能系统、执行追踪 |
| LLM 网关 | OpenAI、Anthropic、Dashscope、Ollama、DeepSeek、智谱、火山引擎、Moonshot、MiniMax、百炼、OpenRouter、LiteLLM、Bedrock、Gemini，支持流式输出和思维链 |
| 工具系统 | 本地函数工具、MCP 远程工具、9 类内置工具，支持交互式提问工具 |
| RAG | 4 种分段器（Simple / Markdown / Python / C++）、3 种嵌入器（OpenAI / Dashscope / SentenceTransformers）、3 种向量库（ChromaDB / Qdrant / DuckDB） |
| 图形界面 | 基于 PySide6 的聊天 UI，支持 Profile 管理、多智能体切换、Markdown 渲染、Thinking 显示和交互式工具提问 |
| 命令行界面 | 基于 Prompt Toolkit 的 CLI，支持自动补全、Markdown 终端渲染和交互式工具提问 |
详细的功能更新记录请参考 CHANGELOG。
我们欢迎所有形式的贡献！无论是bug报告、功能建议还是代码贡献。
- Fork 本项目：点击 GitHub 页面右上角的 Fork 按钮
- 克隆到本地：
git clone https://github.com/your-username/vnag.git - 创建功能分支：
git checkout -b feature/AmazingFeature - 进行开发：编写代码、添加测试、更新文档
- 提交更改：
git commit -m 'Add some AmazingFeature' - 推送到远程：
git push origin feature/AmazingFeature - 提交 Pull Request：在 GitHub 上创建 PR，详细描述您的更改
项目使用以下工具确保代码质量：
- Ruff：代码格式化和 linting
- MyPy：静态类型检查
在提交代码前，请运行：
# 代码检查
ruff check .
# 类型检查
mypy vnag
# 运行测试
python -m unittest discover -s tests -p "test_*.py" -v如果您遇到任何问题或有建议，请通过以下方式联系我们：
- 在GitHub上提交Issue
- 发送邮件至：contact@mail.vnpy.com
本项目采用MIT开源协议，详情请参阅LICENSE文件。
立即开始您的AI Agent开发之旅！🚀