@cuylabs/agent-core

Composable AI agent harness with pluggable execution control.

@cuylabs/agent-core is the in-process execution kernel for AI agents. It owns the Agent API, streaming execution, tool and model semantics, middleware and lifecycle hooks, sessions, prompt construction, tracing, and the reusable task/turn/workflow primitives that runtime packages build on for durability, hosting, and scheduling.

Package Boundary

Use @cuylabs/agent-core when you want:

• Agent creation and chat() / send() 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
• EventBus — pluggable pub/sub with history replay and backpressure
• AgentSignal — typed inter-agent signalling within teams
• Runtime-facing task, turn, and workflow primitives for durable adapters

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
# 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.",
});

for await (const event of agent.chat("session-1", "Say hi to Ada")) {
  switch (event.type) {
    case "text-delta":
      process.stdout.write(event.text);
      break;
    case "tool-start":
      console.log(`calling ${event.toolName}`);
      break;
    case "tool-result":
      console.log(`tool result:`, event.result);
      break;
    case "complete":
      console.log("\ndone");
      break;
  }
}

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 type { AgentMiddleware } from "@cuylabs/agent-core/middleware";
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/scope";
import { createSkillRegistry } from "@cuylabs/agent-core/skill";
import { createSubAgentTools } from "@cuylabs/agent-core/subagents";
import { createMCPManager } from "@cuylabs/agent-core/mcp";
import { createEventBus } from "@cuylabs/agent-core/events";
import type { AgentSignal } from "@cuylabs/agent-core/signal";

Additional focused entrypoints are available for tool, tracking, storage, reasoning, models, mcp, inference, tool/host, scope, dispatch, subagents, events, and signal.

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

Learn More

Start with the package docs:

• docs/README.md for the learning path
• docs/agent.md for the main Agent API
• docs/middleware/ for model/tool hooks and lifecycle middleware
• docs/scope.md for nested execution lineage and scope snapshots
• docs/tools/ for tool definition and execution
• docs/execution/README.md for task/turn/workflow execution integration
• docs/events.md for the EventBus pub/sub interface
• docs/signal.md for inter-agent signalling
• docs/tracing.md for tracing setup

Runnable examples live in examples/README.md.

License

Apache-2.0