0 Fork 0

mirror of https://github.com/JackChen-me/open-multi-agent.git synced 2026-10-19 01:29:57 -05:00

Files

T

Jack Chen bbdb928a5b docs(examples): make the example index runnable from a fresh checkout (#575 )

The examples index is the first page most visitors open after the root
README, but it never said the scripts import the framework source and
need a repository checkout, which examples run without an API key, or
that four integrations existed at all.

- Add a "Run an example" block (clone, install, key, npx tsx) and note
  the two exceptions: observability-v2 needs a build, apps have their
  own start scripts. Explain how to port a script into a real project.
- Add a "No API key needed" table for the seven offline examples.
- Let the basics scripts switch provider through OMA_PROVIDER and
  OMA_MODEL instead of hard-coding Claude, following the convention the
  cookbook already uses.
- List external-agent-acp, external-agent-process, with-engram, and
  with-tencentdb-memory, and fail test:example-catalog when a catalog
  entry has no link in the index so it cannot drift again.
- Reorder sections so the 20-row providers table no longer sits between
  basics and the patterns and cookbook tables; mark production/ as empty.
- Align integrations/README.md with the apps grouping and define the
  mcp-<server>.ts versus with-<product>/ naming by example shape.

2026-09-04 22:51:45 +08:00

3.9 KiB

Raw Blame History

examples/integrations/

OMA wired to external systems: MCP servers, observability backends, other frameworks, app shells. Runnable starting points, not product docs.

Three categories live here.

Reference integrations demonstrate wiring against widely used protocols or frameworks. The OMA team maintains these once merged, regardless of who contributed them. Current:

mcp-github.ts: MCP servers via connectMCPTools().
mcp-open-design.ts: batch fan-out over an MCP server's async, long-running jobs — N Open Design landing-page variants generated in parallel via runTasks(), each variant driven create_project → start_run → poll get_run to a terminal status by deterministic code.
external-agent-acp.ts: external coding agents (Gemini CLI / Claude Code) as team members via the acp backend. See docs/external-agents.md.
external-agent-process.ts: deterministic local subprocesses as team members via the process backend.
trace-observability.ts: the onTrace API.
observability-v2/: no-network examples for batching/custom exporters, InMemory/File TraceStore, an application-owned OTel provider, and explicit CLI/server/serverless lifecycle handling. The original trace-observability.ts remains the legacy callback example.

Full applications embed OMA in a real app shell. Each has its own package.json and start script (npm install then npm start or npm run dev) instead of npx tsx, and imports the published @open-multi-agent/core package name. The main index lists them under apps. Current:

express-customer-support/: Express REST API + runTasks(). Contributed by @CodingBangboo via #191.
with-vercel-ai-sdk/: Next.js + AI SDK + runTeam().

Vendor integrations show OMA paired with a specific third-party commercial product and stay credited to the contributor. Naming follows the shape of the example, not the vendor: a single-file script that wires one protocol or MCP server keeps the protocol prefix (mcp-<server>.ts, as with mcp-bilig-workpaper.ts and mcp-open-design.ts above), while a multi-file integration that ships its own store, toolkit, or app shell lives under with-<product>/. Current:

with-engram/: Engram memory backend. Contributed by @Agentscreator via #160.
with-tencentdb-memory/: TencentDB-Agent-Memory long-term memory (L0→L3 pipeline) via its Hermes Gateway sidecar.

Submitting a reference integration

Open a PR following the conventions in examples/README.md. For widely used protocols or frameworks, no prior discussion needed. For niche ones, open a discussion first so we can confirm the wiring is worth maintaining long-term.

Submitting a vendor integration

One condition: the integration is reciprocal. Your product's repo or docs should reference OMA as a supported integration. No payment involved, this is a signal filter for who has actually shipped against OMA.

Flow:

Open a discussion with the link to OMA in your product's docs and a sketch of the example.
Wait for a maintainer reply confirming the example is in scope.
PR it. Follow the conventions in examples/README.md.

If your product doesn't reference OMA yet, open a discussion to get listed in the Built with OMA section.

The Featured Partner program is separate and paid, for prominent README placement. Eligibility is an active OMA integration; reciprocal listing isn't required.

Out of scope here

Marketing copy for a third-party product.
Examples gated behind paid-only APIs with no free or trial tier.
Thin connectMCPTools() wrappers whose only difference from mcp-github.ts is the server name and prefix. Those belong in your own docs.

3.9 KiB Raw Blame History

examples/integrations/

Submitting a reference integration

Submitting a vendor integration

Out of scope here

3.9 KiB

Raw Blame History