opencoreagents-rest-workers
Express REST for agents/runs (@opencoreagents/rest-api), BullMQ async dispatch (adapters-bullmq), Redis-backed dynamic definitions and workers (dynamic-runtime-rest).
- License 许可
- Apache-2.0
- 最近更新
- 2026-08-23
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- opencoreagents-rest-workers
- description
- Express REST for agents/runs (@opencoreagents/rest-api), BullMQ async dispatch (adapters-bullmq), Redis-backed dynamic definitions and workers (dynamic-runtime-rest).
03 SKILL.md 正文
OpenCore Agents — REST API & workers
Bundled docs:
docs/reference/core/12-multi-tenancy.md(engine tenancy / scopes);docs/reference/core/21-dynamic-runtime-rest.md(dynamic store + workers);packages/rest-api/README.md,packages/core/README.md.skillDocsDirectory("opencoreagents-rest-workers"),skillPackagesDirectory("opencoreagents-rest-workers").
Use for HTTP APIs over the engine, BullMQ-backed run/resume, and Redis + worker setups—not for in-process-only demos unless the user asks for HTTP.
Same stack as the public monorepo OpenCoreAgents/runtime.
Packages (install what you use)
| Package | Role |
|---|---|
@opencoreagents/rest-api |
createRuntimeRestRouter → Express Router (URL shape summarized below; more options in packages/rest-api/README.md) |
@opencoreagents/adapters-bullmq |
createEngineQueue, createEngineWorker; re-exports dispatchEngineJob from core |
@opencoreagents/dynamic-definitions |
hydrateAgentDefinitionsFromStore, persisted agent/skill/HTTP-tool shapes |
@opencoreagents/adapters-redis |
RedisDynamicDefinitionsStore, shared Memory / RunStore when you need Redis |
rest-api lists adapters-bullmq / bullmq as optional peers—add them when using dispatch.
HTTP contract summary (@opencoreagents/rest-api)
What it is: an Express Router—not a standalone “REST server” binary. You own listen port, TLS, rate limits, auth beyond API keys, and any extra routes.
Implemented paths (relative to where you mount the router):
| Method | Path | Purpose |
|---|---|---|
| GET | /agents |
List agent ids for the effective projectId (optional agentIds allowlist). |
| GET | /agents/:agentId/memory |
Read memory via MemoryAdapter.query — needs runtime; query sessionId + memoryType required; optional endUserId. Unregistered if the router is enqueue-only (dispatch without runtime). |
| POST | /agents/:fromAgentId/send |
Inter-agent MessageBus.send (same idea as system_send_message). Needs runtime + messageBus on AgentRuntime (501 if missing). Optional sendMessageTargetPolicy can 403. |
| POST | /agents/:agentId/run |
Start a run — body message (required), optional sessionId, projectId, wait. Inline → Agent.run. Queue → 202 + jobId / statusUrl, or block with wait + queueEvents. |
| POST | /agents/:agentId/resume |
Resume a wait — runId, sessionId, resumeInput { type, content }, optional projectId, wait. Inline needs runStore on AgentRuntime. |
| GET | /runs/:runId |
Run snapshot from runStore — ?sessionId= required; exact projectId match and optional ?tenantId= for tenant-scoped runs (403 mismatch). |
| GET | /runs/:runId/history |
Full Run.history — same sessionId / project / tenant rules as GET /runs/:runId. |
| GET | /agents/:agentId/runs |
List runs — needs runStore; optional status, sessionId, tenantId, limit. Uses listByAgentAndSession(projectId, agentId, sessionId, { tenantId?, ... }) when sessionId is supplied. |
| GET | /jobs/:jobId |
BullMQ job status + run summary when done — only if dispatch is configured. |
Execution modes (how run/resume run):
| Mode | Config | Effect |
|---|---|---|
| Inline | runtime |
POST …/run and POST …/resume execute in the HTTP process. resume and GET /runs* need runStore on AgentRuntime. |
| Queue | dispatch: { engine, queueEvents?, jobWaitTimeoutMs? } |
Run/resume enqueue; default 202 + jobId. wait needs queueEvents. isBullmqJobWaitTimeoutError → 504 vs 502. |
| Both | runtime + dispatch |
dispatch wins for POST run/resume; runtime still powers memory/send routes when mounted. |
Multi-tenant resolution (when projectId is omitted from router options): X-Project-Id header → ?projectId= → body.projectId on POSTs. Optional run tenantId resolves from X-Tenant-Id → ?tenantId= → body.tenantId; set requiredTenant: true to require it on run routes. allowedProjectIds, resolveProjectId(req), resolveApiKey + getRuntimeRestRouterProjectId / getRuntimeRestRouterTenantId for scoped secrets — see packages/rest-api/README.md.
Engine-level multi-tenancy: the router only picks the effective projectId on the wire. How projectId scopes definitions, memory, runs, RunStore rows, MessageBus keys, and dynamic-definition store data lives in docs/reference/core/12-multi-tenancy.md—read it when combining rest-api with shared Redis, workers, or dynamicDefinitionsStore, not only for “HTTP auth” questions.
Useful exports: mapEngineErrorToHttp, RUNTIME_REST_ENGINE_ERROR_CODES, isBullmqJobWaitTimeoutError, buildRuntimeRestOpenApiSpec, swagger option (/openapi.json, /docs — often without API key; lock down in production).
Library limits (know the box): JSON body cap (512kb); no endUserId / expiresAtMs on POST run/resume** HTTP bodies (use **queue** / **EngineJobPayload** if you need them); **no** define-CRUD routes inside this router; **no** built-in idempotency or rate limiting. **SSE / token streaming** is **not** in **rest-api** — use a custom BFF (e.g. monorepo **examples/real-world-with-express`) if you need that shape.
Mounting & auth (minimal)
import express from "express";
import { createRuntimeRestRouter } from "@opencoreagents/rest-api";
const app = express();
app.use(express.json());
app.use(
createRuntimeRestRouter({
runtime,
projectId: "my-project", // omit for multi-tenant (see summary above + package README)
runStore,
resolveApiKey: () => process.env.REST_API_KEY?.trim() || undefined,
// swagger: true → GET …/openapi.json, GET …/docs (no API key by default—protect in production)
}),
);
// Optional prefix: app.use("/api", createRuntimeRestRouter({ … }))
BullMQ worker path
dispatchEngineJob(runtime, payload)is implemented in@opencoreagents/coreand re-exported from@opencoreagents/adapters-bullmq.- Worker should build
AgentRuntimewith the same adapters you need in production (Redis memory/run store if multiple workers). - Dynamic agents: set
dynamicDefinitionsStore(e.g.RedisDynamicDefinitionsStore) onAgentRuntimesoruntime.dispatch/dispatchEngineJobhydrates from Redis per job—details indocs/reference/core/21-dynamic-runtime-rest.md.
Dynamic definitions (mental model)
- Definitions live in a store (usually Redis); API validates auth and writes + enqueues.
- Worker runs
hydrateAgentDefinitionsFromStore(or relies ondynamicDefinitionsStoreonAgentRuntime) beforeAgent.loadfor that job—so Redis edits apply on the next job without redeploying workers. @opencoreagents/coredoes not depend ondynamic-definitionsat build time; workers must install@opencoreagents/dynamic-definitionsso the dynamic import resolves.
Reference: examples/dynamic-runtime-rest/ (full monorepo clone only) — infrastructure pattern; you can still mount createRuntimeRestRouter({ dispatch }) on the same API if you want /agents/... paths alongside custom /v1/... routes.
Production posture (stay honest)
The plugin gives routes and engine wiring, not a full product security boundary. Treat multi-tenant isolation, API keys / auth, rate limits, OpenAPI/Swagger (often public if you enable it), idempotency for queued or retried work, and shared RunStore consistency as your integration work—do not describe the stack as hardened multi-tenant SaaS unless you have actually implemented those layers.
04 同仓库更多 Skills
opencoreagents-workspace
Navigate the OpenCore Agents monorepo (@opencoreagents/*), pnpm workspaces, Turbo, docs layout, and where to change code safely.
opencoreagents-rag-dynamic
Use @opencoreagents/rag (catalog, ingest, file tools, skills) and related core hooks (registerRagCatalog on AgentRuntime).
opencoreagents-engine
Implement or debug @opencoreagents/core — AgentRuntime, Agent.load, RunBuilder, Tool.define, Skill.define, Session, RunStore, wait/resume, adapters.
openclaw_demo
Demonstrates the OpenClaw skill loader — uses the exec tool with Node (same runtime as pnpm start).
gated_missing_bin
This skill should be skipped at load time (missing binary gate).