docs: polish READMEs for 1.2 feature surface
- Document AgentConfig.customTools alongside agent.addTool() - Add Tool Output Control section (maxToolOutputChars, maxOutputChars, compressToolResults) - Add Context Management section covering all four strategies (sliding-window, summarize, compact, custom) - Bump examples count 18 to 19 and add example 16 (MCP) and example 19 (Groq) to curated list - Sync README_zh with README: add CLI (oma) note, full MCP Tools section, Groq row in providers table - Drop stale rentech-quant-platform entry from Used by
This commit is contained in:
JackChen
parent
b4b38ffdd8
commit
2708531b1d
85
README.md
85
README.md
|
|
@ -53,7 +53,6 @@ See [`DECISIONS.md`](./DECISIONS.md) for the full rationale.
|
|||
`open-multi-agent` is a new project (launched 2026-04-01, MIT, 5,500+ stars). The ecosystem is still forming, so the list below is short and honest:
|
||||
|
||||
- **[temodar-agent](https://github.com/xeloxa/temodar-agent)** (~50 stars). WordPress security analysis platform by [Ali Sünbül](https://github.com/xeloxa). Uses our built-in tools (`bash`, `file_*`, `grep`) directly in its Docker runtime. Confirmed production use.
|
||||
- **[rentech-quant-platform](https://github.com/rookiecoderasz/rentech-quant-platform).** Multi-agent quant trading research platform. Five pipelines plus MCP integrations, built on top of `open-multi-agent`. Early signal, very new.
|
||||
- **Cybersecurity SOC (home lab).** A private setup running Qwen 2.5 + DeepSeek Coder entirely offline via Ollama, building an autonomous SOC pipeline on Wazuh + Proxmox. Early user, not yet public.
|
||||
|
||||
Using `open-multi-agent` in production or a side project? [Open a discussion](https://github.com/JackChen-me/open-multi-agent/discussions) and we will list it here.
|
||||
|
|
@ -142,14 +141,16 @@ For MapReduce-style fan-out without task dependencies, use `AgentPool.runParalle
|
|||
|
||||
## Examples
|
||||
|
||||
18 runnable scripts and 1 full-stack demo in [`examples/`](./examples/). Start with these:
|
||||
19 runnable scripts and 1 full-stack demo in [`examples/`](./examples/). Start with these:
|
||||
|
||||
- [02 — Team Collaboration](examples/02-team-collaboration.ts): `runTeam()` coordinator pattern.
|
||||
- [06 — Local Model](examples/06-local-model.ts): Ollama and Claude in one pipeline via `baseURL`.
|
||||
- [09 — Structured Output](examples/09-structured-output.ts): any agent returns Zod-validated JSON.
|
||||
- [11 — Trace Observability](examples/11-trace-observability.ts): `onTrace` spans for LLM calls, tools, and tasks.
|
||||
- [16 — MCP (GitHub)](examples/16-mcp-github.ts): expose an MCP server's tools to an agent via `connectMCPTools()`.
|
||||
- [17 — MiniMax](examples/17-minimax.ts): three-agent team using MiniMax M2.7.
|
||||
- [18 — DeepSeek](examples/18-deepseek.ts): three-agent team using DeepSeek Chat.
|
||||
- [19 — Groq](examples/19-groq.ts): OpenAI-compatible Groq endpoint with fast free-tier models.
|
||||
- [with-vercel-ai-sdk](examples/with-vercel-ai-sdk/): Next.js app — OMA `runTeam()` + AI SDK `useChat` streaming.
|
||||
|
||||
Run scripts with `npx tsx examples/02-team-collaboration.ts`.
|
||||
|
|
@ -256,7 +257,58 @@ const customAgent: AgentConfig = {
|
|||
|
||||
### Custom Tools
|
||||
|
||||
Tools added via `agent.addTool()` are always available regardless of filtering.
|
||||
Two ways to give an agent a tool that is not in the built-in set.
|
||||
|
||||
**Inject at config time** via `customTools` on `AgentConfig`. Good when the orchestrator wires up tools centrally. Tools defined here bypass preset/allowlist filtering but still respect `disallowedTools`.
|
||||
|
||||
```typescript
|
||||
import { defineTool } from '@jackchen_me/open-multi-agent'
|
||||
import { z } from 'zod'
|
||||
|
||||
const weatherTool = defineTool({
|
||||
name: 'get_weather',
|
||||
description: 'Look up current weather for a city.',
|
||||
schema: z.object({ city: z.string() }),
|
||||
execute: async ({ city }) => ({ content: await fetchWeather(city) }),
|
||||
})
|
||||
|
||||
const agent: AgentConfig = {
|
||||
name: 'assistant',
|
||||
model: 'claude-sonnet-4-6',
|
||||
customTools: [weatherTool],
|
||||
}
|
||||
```
|
||||
|
||||
**Register at runtime** via `agent.addTool(tool)`. Tools added this way are always available, regardless of filtering.
|
||||
|
||||
### Tool Output Control
|
||||
|
||||
Long tool outputs can blow up conversation size and cost. Two controls work together.
|
||||
|
||||
**Truncation** — cap an individual tool result to a head + tail excerpt with a marker in between:
|
||||
|
||||
```typescript
|
||||
const agent: AgentConfig = {
|
||||
// ...
|
||||
maxToolOutputChars: 10_000, // applies to every tool this agent runs
|
||||
}
|
||||
|
||||
// Per-tool override (takes priority over AgentConfig.maxToolOutputChars):
|
||||
const bigQueryTool = defineTool({
|
||||
// ...
|
||||
maxOutputChars: 50_000,
|
||||
})
|
||||
```
|
||||
|
||||
**Post-consumption compression** — once the agent has acted on a tool result, compress older copies in the transcript so they stop costing input tokens on every subsequent turn. Error results are never compressed.
|
||||
|
||||
```typescript
|
||||
const agent: AgentConfig = {
|
||||
// ...
|
||||
compressToolResults: true, // default threshold: 500 chars
|
||||
// or: compressToolResults: { minChars: 2_000 }
|
||||
}
|
||||
```
|
||||
|
||||
### MCP Tools (Model Context Protocol)
|
||||
|
||||
|
|
@ -282,6 +334,33 @@ Notes:
|
|||
- Current transport support is stdio.
|
||||
- MCP input validation is delegated to the MCP server (`inputSchema` is `z.any()`).
|
||||
|
||||
See [example 16](examples/16-mcp-github.ts) for a full runnable setup.
|
||||
|
||||
## Context Management
|
||||
|
||||
Long-running agents can hit input token ceilings fast. Set `contextStrategy` on `AgentConfig` to control how the conversation shrinks as it grows:
|
||||
|
||||
```typescript
|
||||
const agent: AgentConfig = {
|
||||
name: 'long-runner',
|
||||
model: 'claude-sonnet-4-6',
|
||||
// Pick one:
|
||||
contextStrategy: { type: 'sliding-window', maxTurns: 20 },
|
||||
// contextStrategy: { type: 'summarize', maxTokens: 80_000, summaryModel: 'claude-haiku-4-5' },
|
||||
// contextStrategy: { type: 'compact', maxTokens: 100_000, preserveRecentTurns: 4 },
|
||||
// contextStrategy: { type: 'custom', compress: (messages, estimatedTokens, ctx) => ... },
|
||||
}
|
||||
```
|
||||
|
||||
| Strategy | When to reach for it |
|
||||
|----------|----------------------|
|
||||
| `sliding-window` | Cheapest. Keep the last N turns, drop the rest. |
|
||||
| `summarize` | Send old turns to a summary model; keep the summary in place of the originals. |
|
||||
| `compact` | Rule-based: truncate large assistant text blocks and tool results, keep recent turns intact. No extra LLM call. |
|
||||
| `custom` | Supply your own `compress(messages, estimatedTokens, ctx)` function. |
|
||||
|
||||
Pairs well with `compressToolResults` and `maxToolOutputChars` above.
|
||||
|
||||
## Supported Providers
|
||||
|
||||
| Provider | Config | Env var | Status |
|
||||
|
|
|
|||
114
README_zh.md
114
README_zh.md
|
|
@ -53,7 +53,6 @@ CrewAI 是 Python。LangGraph 需要你自己画图。`open-multi-agent` 是你
|
|||
`open-multi-agent` 是一个新项目（2026-04-01 发布，MIT 许可，5,500+ stars）。生态还在成形，下面这份列表很短，但都真实：
|
||||
|
||||
- **[temodar-agent](https://github.com/xeloxa/temodar-agent)**（约 50 stars）。WordPress 安全分析平台，作者 [Ali Sünbül](https://github.com/xeloxa)。在 Docker runtime 里直接使用我们的内置工具（`bash`、`file_*`、`grep`）。已确认生产环境使用。
|
||||
- **[rentech-quant-platform](https://github.com/rookiecoderasz/rentech-quant-platform)。** 多智能体量化交易研究平台，5 条管线 + MCP 集成，基于 `open-multi-agent` 构建。早期信号，项目非常新。
|
||||
- **家用服务器 Cybersecurity SOC。** 本地完全离线运行 Qwen 2.5 + DeepSeek Coder（通过 Ollama），在 Wazuh + Proxmox 上构建自主 SOC 流水线。早期用户，未公开。
|
||||
|
||||
你在生产环境或 side project 里用 `open-multi-agent` 吗？[开一个 Discussion](https://github.com/JackChen-me/open-multi-agent/discussions)，我们会把你列上来。
|
||||
|
|
@ -77,6 +76,8 @@ npm install @jackchen_me/open-multi-agent
|
|||
- `DEEPSEEK_API_KEY`（DeepSeek）
|
||||
- `GITHUB_TOKEN`（Copilot）
|
||||
|
||||
**CLI (`oma`)。** 面向 shell 和 CI，包自带一个 JSON-first 的二进制。`oma run`、`oma task`、`oma provider`、退出码和文件格式见 [docs/cli.md](./docs/cli.md)。
|
||||
|
||||
三个智能体，一个目标——框架处理剩下的一切：
|
||||
|
||||
```typescript
|
||||
|
|
@ -140,14 +141,16 @@ Tokens: 12847 output tokens
|
|||
|
||||
## 示例
|
||||
|
||||
[`examples/`](./examples/) 里有 18 个可运行脚本和 1 个完整项目。推荐从这几个开始：
|
||||
[`examples/`](./examples/) 里有 19 个可运行脚本和 1 个完整项目。推荐从这几个开始：
|
||||
|
||||
- [02 — 团队协作](examples/02-team-collaboration.ts)：`runTeam()` 协调者模式。
|
||||
- [06 — 本地模型](examples/06-local-model.ts)：通过 `baseURL` 把 Ollama 和 Claude 放在同一条管线。
|
||||
- [09 — 结构化输出](examples/09-structured-output.ts)：任意 agent 产出 Zod 校验过的 JSON。
|
||||
- [11 — 可观测性](examples/11-trace-observability.ts)：`onTrace` 回调，为 LLM 调用、工具、任务发出结构化 span。
|
||||
- [16 — MCP (GitHub)](examples/16-mcp-github.ts)：通过 `connectMCPTools()` 把 MCP 服务器的工具暴露给 agent。
|
||||
- [17 — MiniMax](examples/17-minimax.ts)：使用 MiniMax M2.7 的三智能体团队。
|
||||
- [18 — DeepSeek](examples/18-deepseek.ts)：使用 DeepSeek Chat 的三智能体团队。
|
||||
- [19 — Groq](examples/19-groq.ts)：OpenAI 兼容的 Groq 端点，搭配高速免费档模型。
|
||||
- [with-vercel-ai-sdk](examples/with-vercel-ai-sdk/)：Next.js 应用 — OMA `runTeam()` + AI SDK `useChat` 流式输出。
|
||||
|
||||
用 `npx tsx examples/02-team-collaboration.ts` 运行脚本示例。
|
||||
|
|
@ -254,7 +257,109 @@ const customAgent: AgentConfig = {
|
|||
|
||||
### 自定义工具
|
||||
|
||||
通过 `agent.addTool()` 添加的工具始终可用，不受过滤规则影响。
|
||||
两种方式给 agent 装一个不在内置工具集里的工具。
|
||||
|
||||
**配置时注入**：通过 `AgentConfig.customTools` 传入。适合编排层统一挂工具的场景。这里定义的工具会绕过 preset / 白名单过滤，但仍受 `disallowedTools` 约束。
|
||||
|
||||
```typescript
|
||||
import { defineTool } from '@jackchen_me/open-multi-agent'
|
||||
import { z } from 'zod'
|
||||
|
||||
const weatherTool = defineTool({
|
||||
name: 'get_weather',
|
||||
description: '查询某城市当前天气。',
|
||||
schema: z.object({ city: z.string() }),
|
||||
execute: async ({ city }) => ({ content: await fetchWeather(city) }),
|
||||
})
|
||||
|
||||
const agent: AgentConfig = {
|
||||
name: 'assistant',
|
||||
model: 'claude-sonnet-4-6',
|
||||
customTools: [weatherTool],
|
||||
}
|
||||
```
|
||||
|
||||
**运行时注册**：`agent.addTool(tool)`。这种方式添加的工具始终可用，不受任何过滤规则影响。
|
||||
|
||||
### 工具输出控制
|
||||
|
||||
工具返回过长会迅速撑大对话体积和成本。两个控制点互相配合。
|
||||
|
||||
**截断** — 把单次工具结果压到 head + tail 摘要（中间放一个标记）：
|
||||
|
||||
```typescript
|
||||
const agent: AgentConfig = {
|
||||
// ...
|
||||
maxToolOutputChars: 10_000, // 该 agent 所有工具的默认上限
|
||||
}
|
||||
|
||||
// 单工具覆盖（优先级高于 AgentConfig.maxToolOutputChars）：
|
||||
const bigQueryTool = defineTool({
|
||||
// ...
|
||||
maxOutputChars: 50_000,
|
||||
})
|
||||
```
|
||||
|
||||
**消费后压缩** — agent 在后续轮次已经用完某个工具结果后，把历史副本压缩，避免每轮都重复消耗输入 token。错误结果永不压缩。
|
||||
|
||||
```typescript
|
||||
const agent: AgentConfig = {
|
||||
// ...
|
||||
compressToolResults: true, // 默认阈值 500 字符
|
||||
// 或：compressToolResults: { minChars: 2_000 }
|
||||
}
|
||||
```
|
||||
|
||||
### MCP 工具（Model Context Protocol）
|
||||
|
||||
`open-multi-agent` 可以连接任意 MCP 服务器，并把它的工具直接暴露给 agent。
|
||||
|
||||
```typescript
|
||||
import { connectMCPTools } from '@jackchen_me/open-multi-agent/mcp'
|
||||
|
||||
const { tools, disconnect } = await connectMCPTools({
|
||||
command: 'npx',
|
||||
args: ['-y', '@modelcontextprotocol/server-github'],
|
||||
env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
|
||||
namePrefix: 'github',
|
||||
})
|
||||
|
||||
// 把每个 MCP 工具注册进你的 ToolRegistry，然后在 AgentConfig.tools 里引用它们的名字
|
||||
// 用完别忘了清理
|
||||
await disconnect()
|
||||
```
|
||||
|
||||
注意事项：
|
||||
- `@modelcontextprotocol/sdk` 是 optional peer dependency，只在用 MCP 时才需要装。
|
||||
- 当前仅支持 stdio transport。
|
||||
- MCP 的入参校验交给 MCP 服务器自身（`inputSchema` 是 `z.any()`）。
|
||||
|
||||
完整可运行示例见 [example 16](examples/16-mcp-github.ts)。
|
||||
|
||||
## 上下文管理
|
||||
|
||||
长时间运行的 agent 很容易撞上输入 token 上限。在 `AgentConfig` 上设置 `contextStrategy` 来控制对话在成长过程中如何收缩：
|
||||
|
||||
```typescript
|
||||
const agent: AgentConfig = {
|
||||
name: 'long-runner',
|
||||
model: 'claude-sonnet-4-6',
|
||||
// 选一种：
|
||||
contextStrategy: { type: 'sliding-window', maxTurns: 20 },
|
||||
// contextStrategy: { type: 'summarize', maxTokens: 80_000, summaryModel: 'claude-haiku-4-5' },
|
||||
// contextStrategy: { type: 'compact', maxTokens: 100_000, preserveRecentTurns: 4 },
|
||||
// contextStrategy: { type: 'custom', compress: (messages, estimatedTokens, ctx) => ... },
|
||||
}
|
||||
```
|
||||
|
||||
| 策略 | 什么时候用 |
|
||||
|------|------------|
|
||||
| `sliding-window` | 最省事。只保留最近 N 轮，其余丢弃。 |
|
||||
| `summarize` | 把老对话交给一个摘要模型，用摘要替代原文。 |
|
||||
| `compact` | 基于规则：截断过长的 assistant 文本块和 tool 结果，保留最近若干轮。不额外调用 LLM。 |
|
||||
| `custom` | 传入自己的 `compress(messages, estimatedTokens, ctx)` 函数。 |
|
||||
|
||||
搭配上面的 `compressToolResults` 和 `maxToolOutputChars` 使用效果更好。
|
||||
|
||||
## 支持的 Provider
|
||||
|
||||
|
|
@ -269,13 +374,14 @@ const customAgent: AgentConfig = {
|
|||
| GitHub Copilot | `provider: 'copilot'` | `GITHUB_TOKEN` | 已验证 |
|
||||
| Gemini | `provider: 'gemini'` | `GEMINI_API_KEY` | 已验证 |
|
||||
| Ollama / vLLM / LM Studio | `provider: 'openai'` + `baseURL` | — | 已验证 |
|
||||
| Groq | `provider: 'openai'` + `baseURL` | `GROQ_API_KEY` | 已验证 |
|
||||
| llama.cpp server | `provider: 'openai'` + `baseURL` | — | 已验证 |
|
||||
|
||||
Gemini 需要 `npm install @google/genai`（optional peer dependency）。
|
||||
|
||||
已验证支持 tool-calling 的本地模型：**Gemma 4**（见[示例 08](examples/08-gemma4-local.ts)）。
|
||||
|
||||
任何 OpenAI 兼容 API 均可通过 `provider: 'openai'` + `baseURL` 接入（Groq、Mistral、Qwen 等）。**Grok、MiniMax 和 DeepSeek 现已原生支持**，分别使用 `provider: 'grok'`、`provider: 'minimax'` 和 `provider: 'deepseek'`。
|
||||
任何 OpenAI 兼容 API 均可通过 `provider: 'openai'` + `baseURL` 接入（Mistral、Qwen、Moonshot、Doubao 等）。Groq 已在[示例 19](examples/19-groq.ts) 中验证。**Grok、MiniMax 和 DeepSeek 现已原生支持**，分别使用 `provider: 'grok'`、`provider: 'minimax'` 和 `provider: 'deepseek'`。
|
||||
|
||||
### 本地模型 Tool-Calling
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue