@cuylabs/agent-core

Build an agent from a model, instructions, and tools. Add lifecycle behavior with middleware, and package reusable features as plugins. Core runs the model/tool loop, manages sessions and context, and provides execution contracts for runtime and hosting packages.

Installation

npm install @cuylabs/agent-core
# or
pnpm add @cuylabs/agent-core

You will also need at least one AI SDK provider:

npm install @ai-sdk/openai zod
# or @ai-sdk/anthropic, @ai-sdk/google

For OpenAI-compatible endpoints, add:

npm install @ai-sdk/openai-compatible

Quick Start

import { createAgent, Tool } from "@cuylabs/agent-core";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";

const greet = Tool.define("greet", {
  description: "Greet a user by name",
  parameters: z.object({
    name: z.string(),
  }),
  execute: async ({ name }) => ({
    title: "Greeting",
    output: `Hello, ${name}!`,
    metadata: {},
  }),
});

const agent = createAgent({
  name: "assistant",
  model: openai("gpt-4o"),
  tools: [greet],
  systemPrompt: "You are a helpful assistant.",
});

try {
  const result = await agent.run({ message: "Say hi to Ada" });
  console.log(result.response);
} finally {
  await agent.close();
}

Use send(sessionId, message) to continue a conversation, or chat() to stream events. See getting started and the Agent API for execution and configuration options.

Add behavior

Pass middleware directly to your agent. Each method is a hook at a supported execution boundary. For example, with your configured model and tools:

import { createAgent } from "@cuylabs/agent-core";

const agent = createAgent({
  model,
  tools,
  middleware: [
    {
      name: "deny-deploy",
      async beforeToolCall(tool) {
        return tool === "deploy"
          ? { action: "deny", reason: "Deployment is disabled." }
          : { action: "allow" };
      },
    },
  ],
});

Start with the feature recipes to make this configurable, add context, process results, or choose a compaction technique. Run 40 — Add a feature for a complete example.

Use a named hook when matching and per-handler audit metadata help. A plugin packages these same values for reuse. The composition reference covers factory selection, inspection, ownership, and the full vocabulary when you need those controls.

Package Boundary

Use @cuylabs/agent-core when you want:

• Agent creation and run() / send() / chat() APIs
• tool definition and execution
• model hooks, tool hooks, and lifecycle middleware
• sessions, storage, branching, and prompt construction
• tracing, MCP, skills, profiles, and dispatch-based child-agent tools
• execution-facing task/turn/workflow helpers from @cuylabs/agent-core/execution

This package does not own outer orchestration or hosting:

• use @cuylabs/agent-runtime for the backend-agnostic orchestration contract — it defines the interfaces for scheduling, dispatch, workload lifecycle, and execution stores that runtime backends implement
• use @cuylabs/agent-runtime-dapr for a concrete backend that implements those contracts with Dapr workflows, state stores, and pub/sub
• use @cuylabs/agent-server for a transport-neutral local server with session management, turn execution, and streamed event fanout over WebSocket / stdio
• use @cuylabs/agent-http for an AI SDK chat-stream HTTP adapter

@cuylabs/agent-core includes the default local execution host. Non-local tool environments should live in separate packages so the execution semantics and host implementations stay decoupled.

Core Capabilities

• Streaming agent execution with structured events
• Type-safe tools with Zod schemas
• Middleware for model input/output, stream chunks, tool calls, and lifecycle hooks
• Session persistence with branching support
• Prompt pipeline and dynamic prompt sections
• Skills and built-in dispatch-based child-agent delegation
• OpenTelemetry tracing
• MCP integration
• Event primitives — AgentSignal fan-out and EventBus replay/backpressure
• Runtime-facing task, turn, and workflow primitives for durable adapters

Focused Imports

The root export is available, but focused subpath imports mirror the package structure when you want clearer boundaries:

import { createAgent, Tool } from "@cuylabs/agent-core";
import {
  applyAgentPreset,
  bootstrapAgent,
  inspectAgentBootstrap,
  inspectAgentComposition,
  selectCompactionStrategyFactory,
  selectMemoryProviderFactory,
} from "@cuylabs/agent-core/composition";
import type { AgentMiddleware } from "@cuylabs/agent-core/middleware";
import { PluginRegistry, definePlugin } from "@cuylabs/agent-core/plugin";
import { Inference } from "@cuylabs/agent-core/inference";
import { createAgentTaskRunner } from "@cuylabs/agent-core/execution";
import { localHost } from "@cuylabs/agent-core/tool/host";
import { createPromptBuilder } from "@cuylabs/agent-core/prompt";
import { withinScope } from "@cuylabs/agent-core/execution/scope";
import { createSkillRegistry } from "@cuylabs/agent-core/skill";
import { createSubAgentTools } from "@cuylabs/agent-core/subagents";
import { createMCPManager } from "@cuylabs/agent-core/mcp";
import { createEventBus, type AgentSignal } from "@cuylabs/agent-core/events";

Additional focused entrypoints are available for tool, composition, plugin, reasoning, models, mcp, inference, tool/host, execution/scope, execution/turn, execution/workflow, dispatch, subagents, events, events/signal, and events/event-bus.

For non-local tool execution environments, install a dedicated host package and pass its host instance through the same host option.

Relationship To The Runtime Packages

The layering is:

agent-core
  -> agent-runtime
    -> agent-runtime-dapr

• agent-core owns live agent execution
• agent-runtime owns generic workload scheduling and dispatch
• agent-runtime-dapr adds Dapr-backed durability and host integration

If you need durable orchestration, agent-core already exposes the task and turn surfaces those packages build on:

• createAgentTaskRunner(...)
• task execution observers and checkpoints
• turn-step helpers such as prepareModelStep(...) and runToolBatch(...)
• workflow-safe state/planning helpers

Documentation

Start with getting started, then use the documentation map to find a guide by task.

• Add behavior — tool guards, context, and result processing
• Compaction — configuration, technique selection, and recovery
• Plugins — package and register contributions
• Composition — terminology, bootstrap, selection, and ownership
• Agent API — configuration and lifecycle reference
• SDK diagnostics — enable warnings and preserve logging through composition
• Examples — runnable programs

License

Apache-2.0