AI-Zen Agents

AI-Zen Agents is a modular LLM Agent framework, organized as a monorepo via pnpm workspace. It provides layered capabilities from "conversation runtime" to "business capability pipeline", to be consumed directly by upper-layer applications such as CLI / Desktop.

• License: MIT
• npm package: @ai-zen/agents-workspace (workspace root, private); public subpackages are @ai-zen/agents-core and @ai-zen/agents-sdk
• Current versions: workspace 2.0.0; @ai-zen/agents-core 4.1.0; @ai-zen/agents-sdk 0.9.1

What this is

The framework is designed around two layers:

1. @ai-zen/agents-core — A plugin-driven Agent runtime. It runs directly on the official openai SDK and does not maintain its own request layer. It is responsible for conversation lifecycle, streaming output, tool calls, multi-turn recursive dialogs, events, and plugin extension.
2. @ai-zen/agents-sdk — The engine / capability layer built on top of core. It is responsible for the business capability pipeline (discover → permission-filter → instantiate), the global Provider context, MCP connection management, task migration, and the built-in file/command toolset.

Project structure

agents/
├── packages/
│   ├── core/    # @ai-zen/agents-core — Agent / Message / Tool / plugin mechanism
│   └── sdk/     # @ai-zen/agents-sdk — Provider / capability pipeline / MCP / built-in tools
├── package.json # workspace root (private)
└── pnpm-workspace.yaml

Core capabilities

Capability	Description	See
Plugin-driven runtime	AgentPlugin + HookResult short-circuit semantics + dispatchHook unified event/plugin entry	Core API
Modular tools	Tool / CallbackTool / AgentTool / AgentToolLazy / IndexedSearchTool	Core API
Capability pipeline	Discover → permission-filter → instantiate (built-in / user / Skill / MCP / SubAgent)	SDK
Permission model	Four dimensions (tools / skills / mcps / subagents); permissions are disclosure	SDK
MCP support	McpConnectionManager + lazy-loaded tools (load_mcp, etc.)	MCP
Retrieval / RAG	RAG has been removed; retrieval is handled by search tools	Retrieval & RAG

Architecture layers

Upper-layer apps (CLI / Desktop)
        │
        ▼
@ai-zen/agents-sdk  ──►  @ai-zen/agents-core  ──►  official openai SDK
  (capability pipeline / Provider / MCP)   (Agent runtime)    (LLM API)
        │
        ▼
LLM API / MCP servers

Dependency direction (inside SDK): plugin → runtime → capabilities → crud → config → types. Upper layers depend on lower layers, not the other way around. See Architecture.

Quick start

git clone <your-repo-url>
cd agents
pnpm install
pnpm build-core

A minimal runnable example:

import OpenAI from "openai";
import { Agent, Message } from "@ai-zen/agents-core";

const client = new OpenAI({ apiKey: "sk-xxx", baseURL: "https://api.openai.com/v1" });
const agent = new Agent({ client, model: "gpt-4o", modelConfig: { temperature: 0.7 } });
agent.append(Message.System("You are an AI assistant."));
await agent.send("Hello, please introduce yourself.");
console.log(agent.messages.at(-1)?.content);

For complete installation and usage, see Quick Start.

Documentation index

• Quick Start — environment requirements, installation, build, first Agent
• Architecture — core / sdk layering and module dependencies
• Core API — core runtime public API (Agent / Message / Tool / plugins)
• SDK — capability layer (Provider / permissions / built-in tools / migration)
• Retrieval & RAG — retrieval capability status, RAG removal note
• MCP — Model Context Protocol support

Related repositories

@ai-zen/cli (interactive AI Agent terminal) and the Web UI used to belong to this monorepo; they have been migrated to their own repositories or are no longer maintained. See the repository root README.md.

License

MIT. See LICENSE.