## File: README.md

[](https://nexent.tech)
[](README.md)
[](README_CN.md)
[](https://modelengine-group.github.io/nexent)
[](https://hub.docker.com/repositories/nexent)
[](https://codecov.io/gh/ModelEngine-Group/nexent)

Nexent is a zero-code platform for auto-generating production-grade AI agents, built on **Harness Engineering** principles. It provides unified tools, skills, memory, and orchestration with built-in constraints, feedback loops, and control planes — no orchestration, no complex drag-and-drop required, using pure language to develop any agent you want.

> One prompt. Endless reach.

<video controls width="100%" style="max-width: 800px;">
  
  [Watch the demo video](https://github.com/user-attachments/assets/db6b7f5a-9ee8-4327-ae6f-c5af896126b4)
</video>

# 🚀 Get Started Now

> ⭐ Before you get started, please star us on [GitHub](https://github.com/ModelEngine-Group/nexent) — your support drives us forward!

## Deploy on Your Own

If you need to run Nexent locally or in your private infrastructure, we offer two deployment options:

### System Requirements

| Resource | Docker | Kubernetes |
|----------|--------|-------------|
| **CPU** | 4 cores (min) / 8 cores (rec.) | 4 cores (min) / 8 cores (rec.) |
| **Memory** | 8 GiB (min) / 16 GiB (rec.) | 16 GiB (min) / 64 GiB (rec.) |
| **Disk** | 40 GiB (min) / 100 GiB (rec.) | 100 GiB (min) / 200 GiB (rec.) |
| **Architecture** | x86_64 / ARM64 | x86_64 / ARM64 |
| **Software** | Docker 24+, Docker Compose v2+ | Kubernetes 1.24+, Helm 3+ |

> **Note:** Recommended configurations ensure optimal performance in production environments.

### Docker Deployment (Recommended for Individuals/Small Teams)

Quick and straightforward for most users. Prerequisites: Docker 24+ and Docker Compose v2+:

```bash
git clone https://github.com/ModelEngine-Group/nexent.git
cd nexent
bash deploy.sh docker
```

The root `deploy.sh` only forwards to the target deploy script; the native Docker implementation is `bash deploy/docker/deploy.sh`. The Docker and Kubernetes deploy scripts share the same deployment configuration model. Interactive runs show Bash TUI menus for component selection, port policy, and image source. `infrastructure` is required; `application`, `data-process`, and `supabase` are selected by default and can be disabled when you want a smaller deployment. Use `b`/Backspace to return to the previous TUI step and `q` to quit. Use `--defaults` to skip the TUI and deploy with saved `deploy.options` or built-in defaults. Non-interactive runs can also pass the same choices with `--version`, `--components`, `--port-policy development|production`, and `--image-source general|mainland|local-latest`. Successful deployments save non-sensitive choices to each deploy directory's `deploy.options` for reuse on the next run.

Docker and Kubernetes both use `deploy/env/.env` as the runtime configuration file. Existing `deploy/env/.env` is kept as-is. If it does not exist, the deploy scripts first reuse `docker/.env`, then fall back to `deploy/env/.env.example`. Monitoring-specific settings are generated from `deploy/env/monitoring.env.example` into `deploy/env/monitoring.env`.

Docker uninstall is handled by `bash uninstall.sh docker`. It can preserve or delete data volumes: run it interactively, pass `--delete-volumes true|false`, or use `bash uninstall.sh docker delete-all` to remove containers and persistent data.

Offline image packages can be built with `bash build.sh --package --target docker --compress true` or `bash deploy/offline/build_offline_package.sh --target docker --compress true`. The package includes image tar files, `load-images.sh`, `push-images.sh`, root deploy/uninstall entrypoints, deployment scripts, SQL files, `manifest.yaml`, and `checksums.txt`. Package deploys use saved `deploy.options` or built-in defaults without opening the TUI; add `--config` to configure interactively. Deploy with `bash deploy.sh --load-images docker ...` on the target host, or use `bash deploy.sh --push-images --image-registry-prefix registry.example.com/nexent docker ...` to push loaded images to an internal registry and deploy with that image prefix. When `--push-images` is used without a prefix, `deploy.sh` asks for it before `push-images.sh` prompts for the registry username and password.

For detailed deployment instructions, see [Docker Installation](https://modelengine-group.github.io/nexent/en/quick-start/installation.html).

### Kubernetes Deployment (For Enterprise Production)

Ideal for enterprise scenarios requiring high availability and elastic scaling. Prerequisites: Kubernetes 1.24+ and Helm 3+:

```bash
git clone https://github.com/ModelEngine-Group/nexent.git
cd nexent
bash deploy.sh k8s
```

The native Kubernetes implementation is `bash deploy/k8s/deploy.sh`. It reads the same `deploy/env/.env` as Docker and renders explicit values into Helm ConfigMap and Secret overrides. Use `--persistence-mode local|dynamic|existing`, `--storage-class`/`--sc`, `--local-path`, `--local-node-name`, and `--existing-claim-prefix` to control PVC behavior. Local mode renders `hostPath` PVs and does not require node affinity.

Kubernetes uninstall is handled by `bash uninstall.sh k8s`. It removes the Helm release first, then can optionally delete the namespace and local PV data. Use `--delete-namespace true|false`, `--delete-local-data true|false`, or `bash uninstall.sh k8s delete-all`; pass `--keep-local-data` with `delete-all` to preserve local volume contents.

Kubernetes offline packages use the same builder with `--target k8s` or `--target all`. Run `load-images.sh` on every cluster node that needs the images, or use `--push-images --image-registry-prefix registry.example.com/nexent` to push the images to an internal registry before deploying with the same version, image source, and image registry prefix.

For detailed deployment instructions, see [Kubernetes Installation](https://modelengine-group.github.io/nexent/en/quick-start/kubernetes-installation.html).

# ✨ Core Features

Nexent provides a comprehensive feature set for building powerful AI agents:

| Feature | Description |
|---------|-------------|
| **⚙️ Multi-Model Integration** | OpenAI-compatible with any provider, full LLM/Embedding/VLM/STT/TTS coverage, supports domestic model switching |
| **🤖 Zero-Code Agent Generation** | Describe requirements in natural language, generate executable agents instantly, what you think is what you get |
| **🤝 A2A Agent Collaboration** | Agent-to-Agent protocol enables seamless multi-agent cooperation and distributed workflows |
| **🧠 Layered Memory Mechanism** | Two-tier memory (user-level + user-agent-level) for persistent context across conversations |
| **📝 Progressive Skill Disclosure** | Dynamically loads Skill into context, maximizing context window efficiency |
| **🗄️ Personal-Grade Knowledge Base** | Real-time import and intelligent retrieval for 20+ document formats, auto summaries, fine-grained access control |
| **🔧 MCP Tool Ecosystem** | Plug-and-play extension system with custom development and third-party MCP service support |
| **🌐 Internet Knowledge Integration** | Multi-source search blending real-time information with private data |
| **🔍 Knowledge-Level Traceability** | Precise citations and source verification, full transparency for every fact |
| **🎭 Multimodal Interaction** | Voice, text, images, files — comprehensive natural dialogue |
| **🔢 Agent Version Management** | Version iteration and history rollback, safe and controllable |
| **🏪 Agent Marketplace** | Official and community curated agents, one-click install and use |
| **👥 Multi-Tenancy & RBAC** | Multi-tenant isolation, role-based access control, fine-grained resource management |

# 🤝 Join Our Community

> *If you want to go fast, go alone; if you want to go far, go together.*

We have released **Nexent v2.0**! A comprehensive upgrade from v1.0, featuring A2A protocol support, progressive Skill disclosure, layered memory mechanism, user management with multi-tenancy, agent version management, agent marketplace, and more.

- **🗺️ Check our [Feature Map](https://github.com/orgs/ModelEngine-Group/projects/6)** to explore current and upcoming features.
- **🔍 Try the current build** and leave ideas or bugs in the [Issues](https://github.com/ModelEngine-Group/nexent/issues) tab.

> *Rome wasn't built in a day.*

If our vision speaks to you, jump in via the **[Contribution Guide](https://modelengine-group.github.io/nexent/en/contributing)** and shape Nexent with us.

Early contributors won't go unnoticed: from special badges and swag to other tangible rewards, we're committed to thanking the pioneers who help bring Nexent to life.

Most of all, we need visibility. Star ⭐ and watch the repo, share it with friends, and help more developers discover Nexent — your click brings new hands to the project and keeps the momentum growing.

# 📖 What's Next

Ready to dive deeper? Here are the main documentation entry points:

- **[Quick Start](https://modelengine-group.github.io/nexent/en/quick-start/installation.html)** — System requirements and deployment guide
- **[Core Features](https://modelengine-group.github.io/nexent/en/getting-started/features.html)** — Comprehensive feature documentation
- **[User Guide](https://modelengine-group.github.io/nexent/en/user-guide/home-page.html)** — Agent development and usage
- **[Developer Guide](https://modelengine-group.github.io/nexent/en/developer-guide/overview)** — Build from source and customization
- **[FAQ](https://modelengine-group.github.io/nexent/en/quick-start/faq.html)** — Common questions and troubleshooting

# 📄 License

Nexent is licensed under the [MIT License](LICENSE).

---

## File: sdk/nexent/core/tools/README.md

# Nexent 工具开发规范

[](README_EN.md)

本文档基于对现有工具的分析，总结了 Nexent SDK 中工具开发的完整规范和最佳实践。

## 工具分类

当前 SDK 包含以下工具类型：

### 搜索工具
- **EXASearchTool**: 基于 EXA API 的网络搜索工具
- **TavilySearchTool**: 基于 Tavily API 的网络搜索工具  
- **LinkupSearchTool**: 基于 Linkup API 的网络搜索工具
- **KnowledgeBaseSearchTool**: 本地知识库搜索工具

### 通信工具
- **GetEmailTool**: 邮件获取工具
- **SendEmailTool**: 邮件发送工具

## 工具共性特征

### 1. 基础架构
- **基类继承**: 所有工具必须继承自 `smolagents.tools.Tool`
- **参数管理**: 使用 `pydantic.Field` 进行参数定义和验证
- **流式输出**: 集成 `MessageObserver` 支持实时消息传递
- **多语言支持**: 内置中英文双语提示信息

### 2. 核心属性
每个工具类必须包含以下类属性：

```python
class ToolExample(Tool):
    name = "tool_name"                    # 工具唯一标识符
    description = "工具功能描述"          # 详细功能说明
    inputs = {                           # 输入参数定义
        "param": {"type": "string", "description": "参数描述"}
    }
    output_type = "string"               # 输出类型
    tool_sign = "x"                      # 工具标识符（可选）
```

### 3. 消息处理机制
- **ProcessType 枚举**: 使用不同类型区分消息（TOOL, CARD, SEARCH_CONTENT, PICTURE_WEB 等）
- **Observer 模式**: 通过 MessageObserver 实现实时消息推送
- **JSON 格式**: 所有消息内容使用 JSON 格式确保一致性

### 4. 异常处理策略
- **统一异常**: 使用 Exception 抛出错误信息
- **错误日志**: 使用 logging 模块记录详细错误信息
- **优雅降级**: 在可能的情况下提供备选方案

## 命名规范

### 文件命名
- **格式**: `{功能名}_tool.py`
- **风格**: 小写字母，单词间用下划线连接
- **示例**: `exa_search_tool.py`, `knowledge_base_search_tool.py`

### 类命名
- **格式**: `{功能名}Tool`
- **风格**: 大驼峰命名法（PascalCase）
- **示例**: `ExaSearchTool`, `KnowledgeBaseSearchTool`

### 属性和方法命名
- **格式**: 小写字母，单词间用下划线连接
- **私有方法**: 以单下划线开头（如 `_filter_images`）
- **示例**: `max_results`, `running_prompt_en`, `_decode_subject`

### 工具标识符规范
- **tool_sign**: 单字母标识符，用于区分工具来源
- **分配规则**:
  - `a`: 知识库搜索 (KnowledgeBaseSearchTool)
  - `b`: 网络搜索 (ExaSearchTool, TavilySearchTool)
  - `l`: Linkup搜索 (LinkupSearchTool)
  - 其他字母按功能类型分配

## 代码结构模板

### 基础模板

```
/* Detailed source-code truncated for AI context efficiency. */
```

### 搜索工具模板

```
/* Detailed source-code truncated for AI context efficiency. */
```

## 开发流程规范

### 1. 开发前准备
- 确定工具功能和适用场景
- 选择合适的工具分类和标识符
- 检查是否与现有工具功能重复

### 2. 实现步骤
1. **创建工具文件**: 按命名规范创建 `{name}_tool.py`
2. **定义类结构**: 继承 Tool 基类，定义必要属性
3. **实现构造函数**: 使用 pydantic Field 定义参数
4. **实现 forward 方法**: 核心功能逻辑
5. **添加私有方法**: 将复杂逻辑拆分为私有方法
6. **集成消息观察者**: 支持流式输出和多语言
7. **异常处理**: 完善的错误处理和日志记录

### 3. 测试和集成
1. **单元测试**: 测试各种输入情况和边界条件
2. **集成测试**: 与 CoreAgent 集成测试
3. **更新导出**: 在 `__init__.py` 中添加工具导出
4. **文档更新**: 更新相关文档和示例

## 最佳实践

### 1. 性能优化
- **异步处理**: 对于耗时操作使用异步处理
- **连接池**: 复用网络连接减少延迟
- **缓存机制**: 适当使用缓存提升响应速度
- **并发控制**: 使用 Semaphore 控制并发请求数

### 2. 安全性
- **输入验证**: 严格验证输入参数
- **敏感信息**: API密钥等敏感信息不应出现在日志中
- **错误信息**: 避免在错误信息中泄露敏感信息
- **超时控制**: 设置合理的超时时间防止阻塞

### 3. 可维护性
- **模块化设计**: 将复杂功能拆分为多个方法
- **清晰注释**: 为复杂逻辑添加详细注释
- **类型注解**: 使用完整的类型注解
- **文档字符串**: 为所有公共方法添加文档字符串

### 4. 用户体验
- **多语言支持**: 提供中英文双语提示
- **进度反馈**: 通过 MessageObserver 提供实时反馈
- **错误提示**: 提供清晰的错误信息和解决建议
- **参数验证**: 在执行前验证参数有效性

## 注意事项

1. **版本兼容**: 确保工具与不同版本的依赖库兼容
2. **资源清理**: 及时释放网络连接、文件句柄等资源
3. **日志级别**: 合理设置日志级别，避免过多调试信息
4. **配置管理**: 支持通过环境变量配置关键参数
5. **错误恢复**: 在可能的情况下提供错误恢复机制

通过遵循这些规范，可以确保新开发的工具与现有工具保持一致性，并具备良好的可维护性和可扩展性。