🧠 Arklex AI · 代理优先框架

---

🚀 5分钟快速入门

安装与设置

# 安装
pip install arklex

# 创建 .env 文件
echo "OPENAI_API_KEY=your_key_here" > .env

# 克隆仓库（如果你想运行示例/测试脚本则需要）
git clone https://github.com/arklexai/Agent-First-Organization.git
cd Agent-First-Organization
pip install -e .

# 测试你的API密钥（推荐）
python test_api_keys.py

# 创建你的第一个代理
# 当前的 `main` 分支并不包含顶层的 `create.py` 脚本，尽管一些旧的说明可能仍然会提到它。
# 如果你是初学者，请使用 `examples/` 下的预建示例，并用 `run.py` 来运行代理。

python create.py \
  --config ./examples/customer_service/customer_service_config.json \
  --output-dir ./examples/customer_service \
  --llm_provider openai \
  --model gpt-4o

# 运行代理
python run.py \
  --input-dir ./examples/customer_service \
  --llm_provider openai \
  --model gpt-4o

# 对于评估和测试，你也可以使用模型API服务器：
# 1. 启动模型API服务器（默认为OpenAI，使用“gpt-4o-mini”模型）：
python model_api.py --input-dir ./examples/customer_service

# 2. 在另一个终端中运行评估：
python eval.py --model_api http://127.0.0.1:8000/eval/chat \
  --config "examples/customer_service/customer_service_config.json" \
  --documents_dir "examples/customer_service" \
  --model "claude-3-haiku-20240307" \
  --llm_provider "anthropic" \
  --task "all"

---

📺 通过示例学习

▶️ 20分钟内构建一个客服代理

👉 探索完整教程： 客服代理教程

---

⚡ 核心特性

• 🚀 开发速度提升90% —— 数天内即可部署代理，而非数月
• 🧠 代理优先设计 —— 专为多代理编排而打造
• 🔌 模型无关 —— OpenAI、Anthropic、Gemini等
• 📊 内置评估 —— 全面的测试套件
• 🛡️ 企业级安全 —— 认证与速率限制
• ⚡ 生产就绪 —— 监控、日志记录、自动扩展

---

🏗️ 架构

graph TB
    A[任务图] --> B[编排器]
    B --> C[工作者]
    B --> D[工具]
    C --> E[RAG 工作者]
    C --> F[数据库工作者]
    C --> G[自定义工作者]
    D --> I[API 工具]
    D --> J[外部工具]

核心组件：

• 任务图 —— 声明式DAG工作流
• 编排器 —— 带状态管理的运行时引擎
• 工作者 —— RAG、数据库、网页自动化
• 工具 —— Shopify、HubSpot、Google Calendar集成

---

💡 使用场景

领域	能力
电商客服	RAG聊天机器人、工单路由、支持工作流
Shopify等电商平台销售与客户管理	订单管理、库存跟踪、推荐系统
业务流程	日程安排、CRM操作、文档处理

---

📚 示例

示例	描述	复杂度
客服	RAG驱动的支持	⭐⭐
Shopify集成	电商管理	⭐⭐⭐
HubSpot CRM	联系人管理	⭐⭐⭐
日历预约	日程安排系统	⭐⭐
人工介入	交互式工作流	⭐⭐⭐⭐

---

🔧 配置

要求： Python 3.10+，API密钥

# 必需：选择一个或多个LLM提供商
OPENAI_API_KEY=your_key_here
# 或 ANTHROPIC_API_KEY=your_key_here
# 或 GOOGLE_API_KEY=your_key_here

# 可选：增强功能
MILVUS_URI=your_milvus_uri
MYSQL_USERNAME=your_username
TAVILY_API_KEY=your_tavily_key

测试API密钥： 将你的API密钥添加到.env文件后，运行测试脚本以验证它们是否正常工作：

# 测试所有配置的API密钥
python test_api_keys.py

# 仅测试特定提供商
python test_api_keys.py --providers openai gemini
python test_api_keys.py --providers openai anthropic

---

📖 文档

• 📚 完整文档
• 🚀 快速入门
• 🛠️ API参考
• 🏗️ 架构
• 🚀 部署

---

🤝 社区

• 🐛 报告问题
• 💬 Discord
• 🐦 Twitter
• 💼 LinkedIn
• 📧 邮件支持

---

📄 许可证

Arklex AI 采用 MIT 许可证 发布。详情请参阅 LICENSE。

这意味着你可以：

• ✅ 将 Arklex AI 用于商业项目
• ✅ 修改并分发代码
• ✅ 在专有应用中使用
• ✅ 销售基于 Arklex AI 构建的应用程序

唯一的条件是，你需要包含原始许可证和版权声明。

---

🙏 致谢

感谢所有贡献者和开源社区，正是你们让这个项目成为可能！

🌟 贡献者

🤝 开源依赖

Arklex AI 站在巨人的肩膀上：

• LangChain — LLM 框架与工具
• FastAPI — 现代 Web 框架
• Pydantic — 数据验证
• SQLAlchemy — 数据库 ORM
• Milvus — 向量数据库
• 以及更多...

---

Arklex AI (Agent-First) 快速上手指南

Arklex AI 是一个企业级的智能体优先（Agent-First）框架，旨在帮助开发者快速构建、部署和扩展多智能体协作系统。本指南将帮助你在 5 分钟内完成环境搭建并运行第一个智能体示例。

1. 环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：3.10 或更高版本
• 依赖项：
  • pip (Python 包管理工具)
  • git (用于克隆代码仓库)
• API Key：你需要至少一个大语言模型提供商的 API Key（如 OpenAI, Anthropic, Google 等）。

提示：国内开发者若遇到 PyPI 下载缓慢问题，建议使用国内镜像源安装依赖（见下文安装步骤）。

2. 安装步骤

第一步：安装核心库

通过 pip 安装 arklex 核心包。

# 使用官方源
pip install arklex

# 【推荐】国内开发者使用清华镜像源加速安装
pip install arklex -i https://pypi.tuna.tsinghua.edu.cn/simple

第二步：配置 API 密钥

在项目根目录创建 .env 文件并填入你的 API Key。

# 创建 .env 文件并写入 OpenAI Key (替换为你自己的 key)
echo "OPENAI_API_KEY=your_key_here" > .env

# 如果使用其他模型，可追加写入，例如：
# echo "ANTHROPIC_API_KEY=your_key_here" >> .env

第三步：克隆仓库并安装开发依赖

为了运行示例脚本和测试工具，需要克隆源代码仓库并以编辑模式安装。

# 克隆仓库
git clone https://github.com/arklexai/Agent-First-Organization.git
cd Agent-First-Organization

# 以编辑模式安装本地依赖
pip install -e .

# 【可选】国内加速：若 git 克隆慢，可使用国内镜像
# git clone https://gitee.com/mirror/Agent-First-Organization.git (需确认是否有同步镜像)

第四步：验证配置

运行测试脚本确保 API Key 配置正确且网络通畅。

python test_api_keys.py

# 仅测试特定提供商（例如只测 OpenAI 和 Gemini）
python test_api_keys.py --providers openai gemini

3. 基本使用

本框架推荐使用预置的示例配置来快速启动智能体。以下以“客户服务智能体”为例。

启动智能体

使用 run.py 脚本加载示例配置并启动服务。请确保当前位于项目根目录。

python run.py \
  --input-dir ./examples/customer_service \
  --llm_provider openai \
  --model gpt-4o

• --input-dir: 指定包含配置文件和文档的示例目录。
• --llm_provider: 指定大模型提供商（如 openai, anthropic）。
• --model: 指定具体模型名称（如 gpt-4o, claude-3-haiku-20240307）。

（可选）运行评估测试

如果你需要对智能体进行自动化评估，可以先启动模型 API 服务器，然后运行评估脚本。

终端 1：启动 API 服务器

python model_api.py --input-dir ./examples/customer_service

终端 2：运行评估

python eval.py --model_api http://127.0.0.1:8000/eval/chat \
  --config "examples/customer_service/customer_service_config.json" \
  --documents_dir "examples/customer_service" \
  --model "claude-3-haiku-20240307" \
  --llm_provider "anthropic" \
  --task "all"

---

下一步学习： 成功运行后，你可以查看 examples/ 目录下的更多场景（如 Shopify 集成、CRM 管理等），或访问 官方文档 深入学习架构设计与自定义开发。