0 Fork 0

mirror of https://github.com/JackChen-me/open-multi-agent.git synced 2026-10-22 02:53:26 -05:00

Files

T

Jack Chen 1d37ce6026 refactor(repo): monorepo groundwork for an easier first run (#303 )

* refactor(repo): monorepo groundwork for an easier first run

Trying OMA for the first time costs more than it should: a lot to read before anything runs, and no one-command way to watch a team actually work. The plan is to fix that with a `npm create oma` scaffold (a multi-agent demo that runs on the first try) and an npm README that leads with getting started. Neither lands cleanly until core lives in its own package, so this PR does that part first.

This is groundwork, not the payoff: nothing changes for anyone installing `@open-multi-agent/core` today. It turns the repo into an npm-workspaces monorepo with core in `packages/core/`, and splits the README into a GitHub landing page (root) and the npm package page (`packages/core/`). Doing it now, while the repo is small, avoids migrating twice.

The published package is byte-identical: same name, same three runtime dependencies, same entry points, guarded by an isolated-install smoke test. `npm ci` + lint + test (1060) + build pass; the tarball still ships only `dist/`, `README.md`, `LICENSE`, and `package.json`.

* build: restore cross-platform optional deps in package-lock.json

Regenerating the lockfile on macOS pruned the non-host rollup/esbuild optional binaries (npm/cli#4828), so Linux CI could not load @rollup/rollup-linux-x64-gnu and vitest failed to start. Rebuild the lock from the pre-migration base so every platform variant is present again. Verified with npm ci + lint + build + test (1060).

* fix(examples,docs): correct monorepo paths and anchors after the packages/core move

with-vercel-ai-sdk example (pre-existing, surfaced by the move):
- package.json: the @open-multi-agent/core file: link was file:../../, which
  resolves to packages/core/examples (no manifest). Corrected to file:../../..
  (packages/core); predev cd updated to match.
- package-lock.json regenerated: was linking ../.. and pinning a stale core
  1.4.0; now links ../../.. at 1.7.0.
- README: setup paths and the file: note updated.

docs missed by the move:
- docs/cli.md: repo-clone build output is now packages/core/dist/cli/oma.js;
  the quick-start anchor now lives in the package README.
- CONTRIBUTING.md: the architecture anchor and src/ entry-point paths now live
  under packages/core/.

2026-06-18 17:31:52 +08:00

8.6 KiB

Raw Blame History

Providers

open-multi-agent keeps the agent config shape stable across hosted, cloud, and local providers. Change provider, model, and the relevant credential; the rest of your team definition stays the same.

const agent = {
  name: 'my-agent',
  provider: 'anthropic',
  model: 'claude-sonnet-4-6',
  systemPrompt: 'You are a helpful assistant.',
}

Built-In Provider Shortcuts

The framework ships a wired-in provider name for each of these. Set provider and the env var, and the adapter handles the endpoint.

Under the hood, Anthropic, Gemini, and Bedrock use provider-specific APIs. The other built-in shortcuts are pre-configured wrappers around OpenAI-compatible endpoints; same wire format as the OpenAI-compatible table below, with the baseURL already supplied.

Provider	Config	Env var	Example model	Notes
Anthropic (Claude)	`provider: 'anthropic'`	`ANTHROPIC_API_KEY`	`claude-sonnet-4-6`	Native Anthropic SDK.
Gemini	`provider: 'gemini'`	`GEMINI_API_KEY`	`gemini-2.5-pro`	Native Google GenAI SDK. Requires `npm install @google/genai`.
OpenAI (GPT)	`provider: 'openai'`	`OPENAI_API_KEY`	`gpt-4o`
Azure OpenAI	`provider: 'azure-openai'`	`AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_ENDPOINT`	`gpt-4`	Optional `AZURE_OPENAI_API_VERSION`, `AZURE_OPENAI_DEPLOYMENT`.
GitHub Copilot	`provider: 'copilot'`	`GITHUB_COPILOT_TOKEN` (falls back to `GITHUB_TOKEN`)	`gpt-4o`	Custom token-exchange flow on top of OpenAI protocol.
Grok (xAI)	`provider: 'grok'`	`XAI_API_KEY`	`grok-4`	OpenAI-compatible; endpoint is `api.x.ai/v1`.
DeepSeek	`provider: 'deepseek'`	`DEEPSEEK_API_KEY`	`deepseek-v4-flash`	OpenAI-compatible. `deepseek-v4-flash` (default) or `deepseek-v4-pro` (flagship for coding); both support 1M context and 384K max output. Legacy `deepseek-chat` / `deepseek-reasoner` retire 2026-07-24.
Doubao (Volcengine)	`provider: 'doubao'`	`ARK_API_KEY`	`doubao-seed-1-8-251228`	OpenAI-compatible. ByteDance Volcengine Ark endpoint `https://ark.cn-beijing.volces.com/api/v3`. See `providers/doubao`.
Hunyuan (Tencent MaaS / TokenHub)	`provider: 'hunyuan'`	`HUNYUAN_API_KEY`	`hy3-preview`	OpenAI-compatible. Default endpoint `https://tokenhub.tencentmaas.com/v1` (Tencent's current platform; `sk-...` keys, Hunyuan 3 models). Tool calling verified on `hy3-preview`. See `providers/hunyuan`.
Hunyuan (legacy Tencent Cloud)	`provider: 'hunyuan'` + `HUNYUAN_BASE_URL`	`HUNYUAN_API_KEY`	`hunyuan-turbos-latest`	Legacy endpoint `https://api.hunyuan.cloud.tencent.com/v1` (console.cloud.tencent.com/hunyuan key; separate key namespace). Tencent has announced this platform is being retired (sales stop 2026-06-30, full shutdown 2026-09-30). Set `HUNYUAN_BASE_URL=https://api.hunyuan.cloud.tencent.com/v1` to target it until then. Tool calling verified on `hunyuan-turbos` and `hunyuan-functioncall`.
MiniMax (global)	`provider: 'minimax'`	`MINIMAX_API_KEY`	`MiniMax-M3`	OpenAI-compatible.
MiniMax (China)	`provider: 'minimax'` + `MINIMAX_BASE_URL`	`MINIMAX_API_KEY`	`MiniMax-M3`	Set `MINIMAX_BASE_URL=https://api.minimaxi.com/v1`.
MiMo	`provider: 'mimo'`	`MIMO_API_KEY` (+ optional `MIMO_BASE_URL`)	`mimo-v2.5-pro`	OpenAI-compatible. Defaults to pay-as-you-go endpoint `https://api.xiaomimimo.com/v1`; Token Plan keys (`tp-...`) require the cluster base URL from your subscription page, such as `https://token-plan-cn.xiaomimimo.com/v1`. Supports reasoning/tool-call loops through the built-in MiMo adapter. See `providers/mimo`.
Qiniu	`provider: 'qiniu'`	`QINIU_API_KEY`	`deepseek-v3`	OpenAI-compatible. Endpoint `https://api.qnaigc.com/v1`; multiple model families, see Qiniu AI docs.
AWS Bedrock	`provider: 'bedrock'`	none (AWS SDK credential chain)	`anthropic.claude-3-5-haiku-20241022-v1:0`	No API key. Set `AWS_REGION` or pass `region` as the 4th arg to `createAdapter`. Credentials come from env vars, shared config, or IAM role. Newer Claude models can require a cross-region inference profile prefix such as `us.`. Also supports Llama, Mistral, and Cohere. See `providers/bedrock`. Requires `npm install @aws-sdk/client-bedrock-runtime`.

OpenAI-Compatible Providers

No bundled shortcut is needed when a server speaks OpenAI Chat Completions. Use provider: 'openai' and point baseURL at the service.

Service	Config	Env var	Example model	Notes
Ollama (local)	`provider: 'openai'` + `baseURL: 'http://localhost:11434/v1'`	none	`llama3.1`
vLLM (local)	`provider: 'openai'` + `baseURL`	none	server-loaded
LM Studio (local)	`provider: 'openai'` + `baseURL`	none	server-loaded
llama.cpp server (local)	`provider: 'openai'` + `baseURL`	none	server-loaded
OpenRouter	`provider: 'openai'` + `baseURL: 'https://openrouter.ai/api/v1'` + `apiKey`	`OPENROUTER_API_KEY`	`openai/gpt-4o-mini`
Groq	`provider: 'openai'` + `baseURL: 'https://api.groq.com/openai/v1'`	`GROQ_API_KEY`	`llama-3.3-70b-versatile`
Mistral	`provider: 'openai'` + `baseURL: 'https://api.mistral.ai/v1'`	`MISTRAL_API_KEY`	`mistral-large-latest`	See `providers/mistral`.
MiMo	`provider: 'openai'` + `baseURL: 'https://api.xiaomimimo.com/v1'`	`MIMO_API_KEY`	`mimo-v2.5-pro`	Prefer the built-in `mimo` provider when using tool-calling agent loops. Token Plan users should set their `token-plan-*.xiaomimimo.com/v1` base URL.
Zhipu GLM	`provider: 'openai'` + `baseURL: 'https://open.bigmodel.cn/api/paas/v4'`	`ZHIPU_API_KEY`	`glm-4-plus`	See `providers/zhipu`.
Qwen (DashScope)	`provider: 'openai'` + `baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1'`	`DASHSCOPE_API_KEY`	`qwen-plus`	See `providers/qwen`.
Moonshot AI (Kimi)	`provider: 'openai'` + `baseURL: 'https://api.moonshot.ai/v1'`	`MOONSHOT_API_KEY`	`kimi-k2.5`	See `providers/moonshot`.
LiteLLM (proxy)	`provider: 'openai'` + `baseURL: 'http://localhost:4000/v1'` + `apiKey`	`LITELLM_API_KEY` (if proxy auth enabled)	any model on your proxy	LiteLLM unifies 100+ providers (OpenAI, Anthropic, Azure, Bedrock, Vertex, etc.) behind one OpenAI-compatible endpoint. Run `litellm --config config.yaml` and point `baseURL` at the proxy.

Other services can be connected the same way if they implement the OpenAI Chat Completions API, but they are not listed as verified providers here. For services where the key is not OPENAI_API_KEY, pass it explicitly via apiKey; otherwise the openai adapter falls back to OPENAI_API_KEY.

Local Model Tool-Calling

The framework supports tool-calling with local models served by Ollama, vLLM, LM Studio, or llama.cpp. Tool-calling is handled natively through the OpenAI-compatible API.

Verified local models include Gemma 4, Llama 3.1, Qwen 3, Mistral, and Phi-4. Ollama publishes its tool-capable models at ollama.com/search?c=tools.

If a local model returns tool calls as text instead of the tool_calls wire format, the framework automatically extracts them from the text output. This helps with thinking models or misconfigured local servers.

Use timeoutMs on AgentConfig for slow local inference:

const localAgent = {
  name: 'local',
  model: 'llama3.1',
  provider: 'openai',
  baseURL: 'http://localhost:11434/v1',
  apiKey: 'ollama',
  tools: ['bash', 'file_read'],
  timeoutMs: 120_000,
}

Highly quantized MoE models on consumer hardware can fall into repetition loops or hallucinate tool-call schemas under default sampling. AgentConfig exposes topK, minP, frequencyPenalty, presencePenalty, parallelToolCalls, and extraBody for server-specific knobs such as vLLM's repetition_penalty. See providers/local-quantized for a complete setup.

Troubleshooting

Model not calling tools? Confirm it appears in Ollama's Tools category.
Using Ollama? Update to the latest version with ollama update.
Proxy interfering with local servers? Use no_proxy=localhost.

8.6 KiB Raw Blame History