mirror of
https://github.com/JackChen-me/open-multi-agent.git
synced 2026-10-21 18:42:50 -05:00
Jack Chen
5e2fa4515e
A saved plan could replay with different agent behavior than the one reviewed: memoryScope (full shared memory vs dependency-only context) and the retry fields were dropped on the way into the artifact. PlanTaskArtifact and tasksFromPlan already supported them, but TaskExecutionRecord did not carry them, so the planOnly snapshot and createPlanArtifact dropped them before runFromPlan could apply them. A coordinator can emit these (parseTaskSpecs accepts them), so the gap was reachable, not theoretical. Add the four fields to TaskExecutionRecord, populate them where records are built, and serialize them in createPlanArtifact so the round-trip is lossless. Also document the API with examples/patterns/plan-replay.ts and README / README_zh coverage. Follow-up to #285.
Examples
Runnable scripts demonstrating open-multi-agent. Organized by category — pick one that matches what you're trying to do.
All scripts run with npx tsx examples/<category>/<name>.ts. Scripts that call a model require the corresponding API key in your environment.
basics — start here
The four core execution modes. Read these first.
| Example | What it shows |
|---|---|
basics/single-agent |
One agent with bash + file tools, then streaming via the Agent class. |
basics/team-collaboration |
runTeam() coordinator pattern — goal in, results out. |
basics/task-pipeline |
runTasks() with explicit task DAG and dependencies. |
basics/multi-model-team |
Different models per agent in one team. |
providers — model & adapter examples
One example per supported provider. All follow the same three-agent (architect / developer / reviewer) shape so they're easy to compare.
| Example | Provider | Env var |
|---|---|---|
providers/ollama |
Ollama (local) + Claude | ANTHROPIC_API_KEY |
providers/gemma4-local |
Gemma 4 via Ollama (100% local) | — |
providers/local-quantized |
Quantized MoE on vLLM / llama-server with tuned sampling (topK / minP / frequencyPenalty / parallelToolCalls / extraBody.repetition_penalty) |
— |
providers/copilot |
GitHub Copilot (GPT-4o + Claude) | GITHUB_TOKEN |
providers/azure-openai |
Azure OpenAI | AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT (+ optional AZURE_OPENAI_API_VERSION, AZURE_OPENAI_DEPLOYMENT) |
providers/bedrock |
AWS Bedrock (Claude via Converse API) | AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION |
providers/grok |
xAI Grok | XAI_API_KEY |
providers/gemini |
Google Gemini | GEMINI_API_KEY |
providers/minimax |
MiniMax M2.7 | MINIMAX_API_KEY |
providers/mimo |
MiMo V2.5 Pro | MIMO_API_KEY |
providers/hunyuan |
Tencent Hunyuan (MaaS, hy3) | HUNYUAN_API_KEY |
providers/deepseek |
DeepSeek Chat | DEEPSEEK_API_KEY |
providers/openrouter |
OpenRouter (OpenAI-compatible) | OPENROUTER_API_KEY |
providers/groq |
Groq (OpenAI-compatible) | GROQ_API_KEY |
providers/mistral |
Mistral (OpenAI-compatible) | MISTRAL_API_KEY |
providers/zhipu |
Zhipu GLM (OpenAI-compatible) | ZHIPU_API_KEY |
providers/doubao |
Doubao / ByteDance (OpenAI-compatible) | ARK_API_KEY |
providers/qiniu |
Qiniu (OpenAI-compatible) | QINIU_API_KEY |
providers/qwen |
Qwen / DashScope (OpenAI-compatible) | DASHSCOPE_API_KEY |
providers/moonshot |
Moonshot AI / Kimi (OpenAI-compatible) | MOONSHOT_API_KEY |
patterns — orchestration patterns
Reusable shapes for common multi-agent problems.
| Example | Pattern |
|---|---|
patterns/fan-out-aggregate |
MapReduce-style fan-out via AgentPool.runParallel(). |
patterns/structured-output |
Zod-validated JSON output from an agent. |
patterns/task-retry |
Per-task retry with exponential backoff. |
patterns/multi-perspective-code-review |
Multiple reviewer agents in parallel, then synthesis. |
patterns/research-aggregation |
Multi-source research collated by a synthesis agent. |
patterns/cost-tiered-pipeline |
Run the same four-stage pipeline twice to compare flagship vs tiered model cost. |
patterns/agent-handoff |
Synchronous sub-agent delegation via delegate_to_agent. |
patterns/plan-replay |
Pin a coordinator plan with createPlanArtifact, then replay it with runFromPlan, no coordinator re-run. |
cookbook — use-case recipes
End-to-end examples framed around a concrete problem (meeting summarization, translation QA, competitive monitoring, etc.) rather than a single orchestration primitive. Lighter bar than production/: no tests or pinned model versions required. Good entry point if you want to see how the patterns compose on a real task.
| Example | Problem solved |
|---|---|
cookbook/meeting-summarizer |
Fan-out post-processing of a transcript into summary, structured action items, and sentiment. |
cookbook/contract-review-dag |
4-task DAG (extract → compliance-check + summary → notify) with step-level retry. Run normally or with FORCE_FAIL=task2 to exercise retry. |
cookbook/incident-postmortem-dag |
5-task DAG with three parallel root tasks (log patterns + deploy correlation + blast radius) feeding root-cause hypothesis and final postmortem synthesis. |
cookbook/competitive-monitoring |
Parallel source monitoring (Twitter/Reddit/News), contradiction detection, and aggregated intelligence reporting. |
cookbook/paper-replication-triage |
Multi-source paper replication triage with artifact discovery, seeded conflicts, and a structured go/no-go plan. |
cookbook/rare-disease-information-triage |
Source-isolated rare disease information triage with mock fixtures, seeded misinformation/conflict detection, and safety-boundary arbitration. |
cookbook/personalized-interview-simulator |
Interactive interviewer loop with observer flags, shared memory, and structured debrief. |
integrations — external systems
Hooking the framework up to outside-the-box tooling.
| Example | Integrates with |
|---|---|
integrations/trace-observability |
onTrace spans for LLM calls, tools, and tasks. |
integrations/mcp-github |
An MCP server's tools exposed to an agent via connectMCPTools(). |
integrations/mcp-bilig-workpaper |
Bilig WorkPaper MCP tools for formula readback, recalculation, and persisted workbook JSON. |
integrations/with-vercel-ai-sdk/ |
Next.js app — OMA runTeam() + AI SDK useChat streaming. |
integrations/express-customer-support/ |
Express REST API — runTasks() behind POST /tickets with per-agent Zod output schemas, mix-and-match provider env vars, and HTTP error mapping (400/502/504). |
production — real-world use cases
End-to-end examples wired to real workflows. Higher bar than the categories above. See production/README.md for the acceptance criteria and how to contribute.
Adding a new example
| You're adding… | Goes in… | Filename |
|---|---|---|
| A new model provider | providers/ |
<provider-name>.ts (lowercase, hyphenated) |
| A reusable orchestration pattern | patterns/ |
<pattern-name>.ts |
| A use-case-driven example (problem-first, uses one or more patterns) | cookbook/ |
<use-case>.ts |
| Integration with an outside system (MCP server, observability backend, framework, app) | integrations/ |
<system>.ts or <system>/ for multi-file |
| A real-world end-to-end use case, production-grade | production/ |
<use-case>/ directory with its own README |
Conventions:
- No numeric prefixes. Folders signal category; reading order is set by this README.
- File header docstring with one-line title,
Run:block, and prerequisites. - Imports should resolve as
from '../../src/index.js'(one level deeper than the old flat layout). - Match the provider template when adding a provider: three-agent team (architect / developer / reviewer) building a small REST API. Keeps comparisons honest.
- Add a row to the table in this file for the corresponding category.