charieswei
/
open-multi-agent
mirror of https://github.com/JackChen-me/open-multi-agent.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
open-multi-agent/AGENTS.md

3.2 KiB
Raw Blame History

AGENTS.md

Commands

npm run build          # tsc, src/ → dist/
npm run dev            # tsc --watch
npm run lint           # tsc --noEmit (type-check only, NOT a linter)
npm test               # vitest run
npm run test:watch     # vitest

CI gate: npm run lint && npm test — must pass on Node 18, 20, 22.

Run a single test file: npx vitest run tests/task-queue.test.ts

Key Facts

  • ES modules only — "type": "module" in package.json. All local imports use .js extensions despite writing .ts files.
  • npm run lint is type-check, not ESLint. No linter or formatter is configured. Follow existing patterns.
  • Strict TypeScript (strict: true), but noUnusedLocals and noUnusedParameters are intentionally false.
  • 3 runtime deps only (@anthropic-ai/sdk, openai, zod). Do not add runtime dependencies without strong justification — see DECISIONS.md for the project's minimal-dependency philosophy.
  • Optional redis peer dependency — only needed when using RedisStore. Not installing it has zero impact on core functionality.
  • Storage is pluggable — KVStore (low-level) and MessageStore (messages) are injectable via TeamConfig.store / TeamConfig.messageStore. Defaults are in-memory.
  • Tests require no API keys or network. They exercise core modules (TaskQueue, SharedMemory, ToolExecutor, Semaphore) in pure unit-test fashion. Examples in examples/ are the ones needing ANTHROPIC_API_KEY / OPENAI_API_KEY / XAI_API_KEY.
  • tsconfig.json excludes tests/ and examples/ from the build. Tests import directly from ../src/*.js.

Architecture Quick Reference

Top-level API: OpenMultiAgent (src/orchestrator/orchestrator.ts)

  • runAgent(config, prompt) — single agent, one-shot
  • runTeam(team, goal) — coordinator agent decomposes goal → task DAG → parallel execution
  • runTasks(team, tasks) — explicit user-defined task pipeline

All public types live in src/types.ts (single file to avoid circular deps). Public surface exported from src/index.ts.

Directory Map

Dir Purpose
src/orchestrator/ Top-level API, coordinator pattern, scheduler, retry logic
src/agent/ Agent lifecycle, conversation loop (runner.ts), pool (pool.ts), structured output
src/team/ Agent roster, MessageBus, SharedMemory binding
src/task/ Dependency-aware TaskQueue, task creation helpers
src/tool/ defineTool() + Zod schemas, ToolRegistry, parallel batch executor, built-in tools
src/llm/ LLMAdapter interface + lazy-loaded adapters (anthropic, openai, grok, copilot)
src/memory/ Namespaced key-value store, markdown summary injection
src/utils/ Semaphore, trace/observability utilities

Adding an LLM Adapter

Implement LLMAdapter (chat + stream), add to SupportedProvider union and createAdapter() switch in src/llm/adapter.ts. Adapters are lazy-imported.

Conventions

  • No comments unless asked — existing codebase uses JSDoc on public APIs only.
  • PRs target main.
  • See DECISIONS.md for features deliberately excluded (agent handoffs, persistence, A2A, MCP, dashboard). Do not implement these without prior discussion.