opencoreagents-engine
Implement or debug @opencoreagents/core — AgentRuntime, Agent.load, RunBuilder, Tool.define, Skill.define, Session, RunStore, wait/resume, adapters.
- License 许可
- Apache-2.0
- 最近更新
- 2026-08-23
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- opencoreagents-engine
- description
- Implement or debug @opencoreagents/core — AgentRuntime, Agent.load, RunBuilder, Tool.define, Skill.define, Session, RunStore, wait/resume, adapters.
03 SKILL.md 正文
OpenCore Agents — engine (@opencoreagents/core)
Bundled docs:
docs/next to this file. Paths below are relative to that folder (docs/reference/core/...,docs/roadmap/...). API:skillDocsDirectory("opencoreagents-engine").
Use when changing runtime behavior, definitions (Tool / Skill / Agent), or adapter wiring.
For the full monorepo layout and every docs/reference/core/ topic (including RAG, scaffold, multi-tenancy, and planning), enable the opencoreagents-workspace skill alongside this one.
The open-source runtime (this engine and sibling packages) lives at OpenCoreAgents/runtime.
Mental model
AgentRuntimeholds adapters (llmAdapter,memoryAdapter, optionalrunStore,messageBus,dynamicDefinitionsStore, …).Agent.define/Tool.define/Skill.defineregister config in-process (or hydrate from a store).Agent.load(id, runtime, { session })returns an agent handle.agent.run(input)returnsRunBuilder→ chain hooks →Runwithhistory(thought/action/observation/wait/result).
Where to read
- Purpose & shape:
docs/reference/core/01-purpose.md,docs/reference/core/02-architecture.md,docs/roadmap/mvp.md - Loop & state:
docs/reference/core/03-execution-model.md,docs/reference/core/04-protocol.md - Definitions:
docs/reference/core/06-definition-syntax.md - Adapters:
docs/reference/core/05-adapters-contracts.md,docs/reference/core/13-adapters-infrastructure.md - LLM contract:
docs/reference/core/07-llm-adapter.md - Context & tools in prompt:
docs/reference/core/08-context-builder.md - Skills vs tools:
docs/reference/core/09-skills.md - Failures & recovery:
docs/reference/core/10-errors-parsing-and-recovery.md - Scope & production checklist:
docs/reference/core/11-scope-and-security.md - Multi-agent:
docs/reference/core/14-communication-multiagent.md - Cluster / workers:
docs/reference/core/16-cluster-deployment.md
Fragments from examples/minimal-run
Deterministic LLMAdapter: return JSON thought then result so the loop finishes without API keys.
// Adapted from examples/minimal-run/src/main.ts
import type { LLMAdapter, LLMRequest, LLMResponse } from "@opencoreagents/core";
import {
Agent,
AgentRuntime,
Session,
InMemoryMemoryAdapter,
} from "@opencoreagents/core";
class DeterministicDemoLlm implements LLMAdapter {
private i = 0;
async generate(_req: LLMRequest): Promise<LLMResponse> {
const content =
this.i++ === 0
? JSON.stringify({ type: "thought", content: "Plan a one-line greeting for the demo." })
: JSON.stringify({ type: "result", content: "Hello from the minimal runtime example." });
return { content };
}
}
const runtime = new AgentRuntime({
llmAdapter: new DeterministicDemoLlm(),
memoryAdapter: new InMemoryMemoryAdapter(),
maxIterations: 10,
});
await Agent.define({
id: "demo-greeter",
projectId: "demo-project",
systemPrompt: "You are a helpful assistant.",
tools: [],
llm: { provider: "openai", model: "gpt-4o-mini" },
});
const agent = await Agent.load("demo-greeter", runtime, {
session: new Session({ id: "demo-session-1", projectId: "demo-project" }),
});
const run = await agent.run("Say hello.");
const result = run.history.find((h) => h.type === "result");
Fragments from examples/openai-tools-skill
Tool.define then Skill.define; the agent lists skills only (tools are on the skill). OpenAI tool_calls map to engine action steps.
// Adapted from examples/openai-tools-skill/src/main.ts
import { OpenAILLMAdapter } from "@opencoreagents/adapters-openai";
import {
Agent,
AgentRuntime,
Session,
Skill,
Tool,
InMemoryMemoryAdapter,
} from "@opencoreagents/core";
const PROJECT_ID = "demo-openai";
const runtime = new AgentRuntime({
llmAdapter: new OpenAILLMAdapter(process.env.OPENAI_API_KEY!),
memoryAdapter: new InMemoryMemoryAdapter(),
maxIterations: 15,
});
await Tool.define({
id: "roll_dice",
scope: "global",
description: "Roll a single fair die with `sides` faces (minimum 2). Returns { side: number }.",
inputSchema: {
type: "object",
properties: { sides: { type: "number" } },
required: ["sides"],
},
execute: async (input: unknown) => {
const sides = Math.max(2, Math.floor(Number((input as { sides?: unknown }).sides ?? 6)));
return { side: 1 + Math.floor(Math.random() * sides), sides };
},
});
await Skill.define({
id: "dice-skill",
projectId: PROJECT_ID,
tools: ["roll_dice"],
description: "Rolling dice for games and demos.",
});
await Agent.define({
id: "demo-gamer",
projectId: PROJECT_ID,
systemPrompt: "When the user asks to roll, call roll_dice; after the observation, summarize.",
skills: ["dice-skill"],
tools: [],
llm: { provider: "openai", model: "gpt-4o-mini" },
});
const agent = await Agent.load("demo-gamer", runtime, {
session: new Session({ id: "session-openai-1", projectId: PROJECT_ID }),
});
await agent.run("Roll a twenty-sided die once.");
Fragments from examples/console-wait
RunBuilder.onWait: mock LLM emits wait once; host collects input and returns resume text; next generate sees updated history and returns result.
// Adapted from examples/console-wait/src/main.ts
import * as readline from "node:readline/promises";
import { stdin as input, stdout as output } from "node:process";
import type { LLMAdapter, LLMRequest, LLMResponse } from "@opencoreagents/core";
import {
Agent,
AgentRuntime,
Session,
InMemoryMemoryAdapter,
} from "@opencoreagents/core";
class WaitThenEchoLlm implements LLMAdapter {
private turn = 0;
constructor(private readonly userLine: { value: string }) {}
async generate(_req: LLMRequest): Promise<LLMResponse> {
if (this.turn++ === 0) {
return {
content: JSON.stringify({
type: "wait",
reason: "I need one piece of input from you (prompt below).",
}),
};
}
const line = this.userLine.value.trim() || "(empty)";
return { content: JSON.stringify({ type: "result", content: `Done. Received: «${line}».` }) };
}
}
const PROJECT_ID = "demo-console-wait";
const userLine = { value: "" };
const runtime = new AgentRuntime({
llmAdapter: new WaitThenEchoLlm(userLine),
memoryAdapter: new InMemoryMemoryAdapter(),
maxIterations: 10,
});
await Agent.define({
id: "demo-cli-wait",
projectId: PROJECT_ID,
systemPrompt: "Protocol demo: you will wait once, then finish.",
tools: [],
llm: { provider: "openai", model: "gpt-4o-mini" },
});
const agent = await Agent.load("demo-cli-wait", runtime, {
session: new Session({ id: "session-cli", projectId: PROJECT_ID }),
});
const run = await agent.run("Start the interactive flow.").onWait(async (step) => {
const reason = step.type === "wait" ? step.reason : "";
console.log(`Reason: ${reason}`);
const rl = readline.createInterface({ input, output });
const raw = await rl.question("Your line: ");
rl.close();
userLine.value = raw?.trim() ?? "";
return userLine.value.length > 0 ? userLine.value : " ";
});
Common pitfalls
InMemoryMemoryAdapteris single-process only; multi-worker needs Redis / Upstash memory adapters.waitacross processes needsRunStore+ same session/run discipline (see cluster doc).SecurityContextis often not applied inContextBuilderfor tool hiding—seedocs/reference/core/11-scope-and-security.mdanddocs/reference/core/08-context-builder.md(verify on OpenCoreAgents/runtimemainif behavior changed).
Full examples (monorepo clone)
Runnable sources for the fragments above: examples/minimal-run, examples/load-openclaw-skills (OpenClaw SKILL.md + skill-loader-openclaw), examples/openai-tools-skill, examples/console-wait. Paths exist only in a full clone of OpenCoreAgents/runtime, not inside the npm skill tarball.
04 同仓库更多 Skills
opencoreagents-workspace
Navigate the OpenCore Agents monorepo (@opencoreagents/*), pnpm workspaces, Turbo, docs layout, and where to change code safely.
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).
opencoreagents-rag-dynamic
Use @opencoreagents/rag (catalog, ingest, file tools, skills) and related core hooks (registerRagCatalog on AgentRuntime).
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).