使用说明

AgentX

Open-source, local-first, multi-modal AI agent for your desktop.
File system access · Shell execution · Extensible toolkits · Multi-provider

Download Latest Release · Features · Quick Start · Architecture · Contributing · License

截图

下载

从下载最新版本发布页面:

平台	文件
macOS （苹果硅）	`AgentX-x.x.x-arm64.dmg`
macOS （英特尔）	`AgentX-x.x.x-x64.dmg`

注： AgentX目前仅支持macOS。不支持Windows和Linux。

打开 .dmg 并按照安装程序进行操作。首次启动时，请转到 设置>提供者 以添加您的API密钥。

什么是AgentX？

AgentX是一个 本地优先、通用的人工智能代理 它作为本机桌面应用程序运行。与仅支持云的助手不同，AgentX直接在您的机器上运行——读取和写入文件、执行shell命令，并通过基于回合的推理循环自主完成多步任务。

它支持多个LLM提供者、一个可插拔的工具包系统和智能上下文窗口管理，所有这些都封装在一个干净、现代的UI中。

特性

本地工具执行

文件系统访问 --读取、创建和重写计算机上任何位置的文件，并将其沙盒到您的工作区。
Shell 命令 --使用完整的stdout/stderr捕获执行任意shell命令和脚本。
无云中继 --工具在您的操作系统上本地运行。除了LLM API调用之外，没有任何东西离开您的计算机。

多提供商支持

连接您自己的API密钥。AgentX支持：

提供者	默认模型	注释
OpenAI	`gpt-4o`	还与Azure、OpenRouter、vLLM兼容
Anthropic	`claude-sonnet-4-20250514`	原生Anthropic SDK
谷歌双子座	`gemini-2.0-flash`	谷歌人工智能工作室
自定义	--	任何与OpenAI兼容的端点

随时在提供商之间切换。每个对话都会记住其提供者上下文。

自主代理循环

AgentX使用 基于回合的代理循环 --LLM进行推理、调用工具、观察结果，并持续到任务完成：

User message
  → LLM reasoning
    → Tool calls (parallel or sequential)
      → Tool results
        → LLM reasoning (next turn)
          → ... repeat until task complete

多达 50转 每次调用（可配置）
并行工具执行 具有并发控制
流媒体响应 实时UI更新
中止任何时候任何正在运行的任务
驾驶代理通过注入消息来中止执行
跟进队列 --在代理仍在运行时发送新消息

智能上下文管理

长对话会自动优化以适应代币预算：

工具结果压缩 --长输出被截断（头+尾）
梯度压缩 --旧的工具调用组将逐步删除
LLM总结 --旧的历史被浓缩成一个摘要
回退截断 --当其他一切都失败时，优雅的退化

默认上下文预算： 100000个代币，保持最近5圈未压缩。

可扩展工具包

工具和提示在中定义 YAML，无需接触代码即可轻松添加新功能：

resources/toolkit/
├── prompts/         # System prompt templates (i18n-ready)
├── capabilities/    # Tool groups (file, shell, ...)
│   └── desktop/
│       ├── file/    # file_read, file_create, file_rewrite
│       └── shell/   # Shell execution tools
├── skills/          # High-level skill bundles
└── config/          # Global variables

每种能力包括：

工具定义 --名称、描述、输入模式（JSON模式）
提示规则 --在系统提示中注入上下文指南
处理器 --实现工具逻辑的TypeScript函数

中间件系统

使用自定义中间件挂钩扩展代理循环：

interface AgentMiddleware {
  beforeModelCall?: (ctx) => Promise<LLMMessage[] | void>;
  afterModelCall?: (ctx) => Promise<boolean | void>; // return true to stop
  beforeToolExecution?: (ctx) => Promise<Record<string, unknown> | void>;
  afterToolExecution?: (ctx) => Promise<void>;
}

内置： createContextMiddleware() 用于自动上下文优化。

MCP服务器集成

连接外部模型上下文协议服务器，以使用其他工具和资源（数据库、API、自定义服务等）扩展代理。

知识库

添加注入到每个对话中的持久上下文条目（事实、偏好、项目约定）。代理人始终可以访问您最重要的信息。

桌面体验

本机应用程序 macOS
使用自动分类图标进行对话管理
带有打字指示器的实时流媒体
消息操作（复制、编辑、重新生成）
深色主题经过优化，可延长使用时间
轻量级——采用Tauri v2+React 19构建

macOS系统权限

在macOS上，AgentX可以请求系统权限以解锁高级功能：

无障碍 --控制您的计算机并与应用程序交互
屏幕录制 --捕获屏幕内容以获取视觉上下文
麦克风/摄像头 --语音和视觉输入
完全磁盘访问 --在整个系统中读写文件
自动化 --通过AppleScript控制其他应用程序
通知 --桌面通知

首选 设置>权限 直接从应用程序授予每个权限。

快速开始

先决条件

Node.js >= 20
pnpm 10.4.1+

安装并运行

# Clone
git clone https://github.com/axelulu/agentx.git
cd agentx

# Install dependencies
pnpm install

# Start development mode
pnpm dev

应用程序将自动打开。在中添加您的LLM提供程序API密钥设置开始聊天。

为生产而建

pnpm --filter agentx dist:mac

构建工件输出到 packages/agentx/src-tauri/target/release/bundle/.

建筑

AgentX是一个模块化 pnpm单回购 明确区分关注点：

agentx/
├── packages/
│   └── agentx/                  # Tauri v2 desktop app
│       ├── src-tauri/           #   Rust backend (Tauri commands)
│       ├── src/                 #   React UI (Redux, Tailwind)
│       └── resources/toolkit/   #   YAML prompt & tool definitions
│
├── packages/
│   ├── agent/                   # Core agent loop (stateless)
│   │   ├── agent-loop.ts        #   Turn-based reasoning loop
│   │   ├── agent.ts             #   Stateful wrapper class
│   │   ├── tool-executor.ts     #   Parallel/sequential tool runner
│   │   └── middleware.ts        #   Composable middleware system
│   │
│   ├── toolkit/                 # YAML-driven prompt & tool system
│   │   ├── toolkit.ts           #   Main facade
│   │   ├── prompt-service.ts    #   Template parsing + variable substitution
│   │   ├── tool-service.ts      #   Tool definition registry
│   │   └── capability-registry/ #   Capability/skill scanner
│   │
│   ├── context/                 # Context window optimization
│   │   ├── context-manager.ts   #   Orchestrator
│   │   └── compression/         #   Tool compression, gradient, summarization
│   │
│   ├── desktop/                 # Desktop-specific runtime
│   │   ├── runtime.ts           #   DesktopRuntime facade
│   │   ├── providers/           #   OpenAI, Anthropic, Gemini adapters
│   │   ├── conversations/       #   JSON file persistence
│   │   ├── sessions/            #   Session runner (agent + events)
│   │   └── handlers/            #   File & shell tool implementations
│   │
│   ├── l10n/                    # Internationalization framework
│   └── l10n-cli/                # Translation CLI

数据流

┌──────────────┐     IPC      ┌──────────────────┐
│   Renderer   │ ◄──────────► │   Main Process   │
│  (React UI)  │   events     │  (IPC handlers)  │
└──────────────┘              └────────┬─────────┘
                                       │
                              ┌────────▼─────────┐
                              │  DesktopRuntime   │
                              │  ┌─────────────┐  │
                              │  │   Toolkit    │  │  YAML prompts + tools
                              │  ├─────────────┤  │
                              │  │   Agent      │  │  Turn-based loop
                              │  │   Loop       │──┤──► Tool Executor
                              │  ├─────────────┤  │
                              │  │  Context     │  │  Token optimization
                              │  │  Manager     │  │
                              │  ├─────────────┤  │
                              │  │  Provider    │──┤──► OpenAI / Anthropic / Gemini
                              │  │  Manager     │  │
                              │  └─────────────┘  │
                              └───────────────────┘

配置

LLM提供商

打开 设置>提供者 在应用程序中添加您的API密钥。您可以配置多个提供程序并在它们之间切换。

对于自定义的OpenAI兼容端点（Ollama、vLLM、LM Studio等），请使用 自定义 提供程序类型与您的本地基本URL。

工具包功能

该工具包会自动发现中的功能 resources/toolkit/capabilities/每个功能都是一个目录，其中包含：

# capabilities/desktop/file/tools/prompts/en.yaml
meta:
  name: File Tools
  version: "1.0"
tools:
  - name: file_read
    description: "Read entire file content"
    category: desktop
    input_schema:
      type: object
      properties:
        file_path:
          type: string
          description: "Absolute path to the file"
      required: [file_path]

要添加新工具，请执行以下操作：

在下面创建一个目录 capabilities/
添加 tools/prompts/en.yaml 使用工具定义
添加 prompts/en/rules.yaml 使用指南
在中注册处理程序 packages/desktop/src/handlers/

代理参数

参数	默认值	说明
`maxTurns`	50	每次调用的最大推理次数
`maxTokens`	8192	每个LLM响应的最大令牌数
`temperature`	0.7	取样温度
`maxContextTokens`	100000	上下文窗口预算
`recentTurnsToKeep`	5	最近未压缩的转弯
`toolChoice`	`auto`	`auto`, `required`，或 `none`

技术栈

层	技术
桌面	Tauri v2、Vite、Rust
用户界面	React 19、Redux工具包、顺风CSS 4、Radix UI
代理	带有流式EventStream的自定义回合循环
LLM	OpenAI SDK 5（也用于Anthropic/Gemini适配器）
构建	pnpm工作区、Turborepo、TypeScript 5.7
测试	Vitest 4
CI/CD	GitHub操作（lint、类型检查、测试、macOS构建）

项目命令

pnpm dev              # Start app in development mode
pnpm build            # Build all packages
pnpm build:prod       # Production build
pnpm lint             # Lint all packages
pnpm type-check       # TypeScript type checking
pnpm test             # Run tests
pnpm format           # Format with Prettier
pnpm clean            # Remove build artifacts

贡献

欢迎投稿！请遵循现有的代码约定：

分叉存储库
创建分支 从 main
进行更改 --该项目使用常规提交(feat:, fix:, docs:等等）
运行检查 — pnpm lint && pnpm type-check && pnpm test
打开拉取请求

该项目使用：

哈士奇 + 皮棉上演 用于预提交挂钩
承诺用于常规提交消息
更漂亮 用于代码格式化
ESLint 对于linting

许可证

阿帕奇-2.0