core

The core package provides the agent runtime and extension system. It's protocol-agnostic—HTTP, payments, and other capabilities are added via extensions.

Installation

bun add @regent/core

Basic Usage

import { createAgent } from '@regent/core';
import { http } from '@regent/http';

const agent = await createAgent({
  name: 'my-agent',
  version: '1.0.0',
  description: 'An AI-powered assistant',
})
  .use(http())
  .build();

API Reference

createAgent(meta)

Creates an AgentBuilder for constructing an agent with extensions.

function createAgent(meta: AgentMeta): AgentBuilder

Parameters:

Parameter	Type	Description
meta	AgentMeta	Agent metadata (name, version, description, etc.)

Returns: AgentBuilder - A fluent builder for configuring the agent.

AgentMeta

type AgentMeta = {
  name: string;         // Required: Agent name
  version: string;      // Required: Semantic version (e.g., "1.0.0")
  description?: string; // What the agent does
  icon?: string;        // Icon URL
  image?: string;       // Open Graph image URL (1200x630px recommended)
  url?: string;         // Canonical URL for the agent
  type?: 'website' | 'article';
};

AgentBuilder

Fluent builder for composing extensions.

class AgentBuilder {
  use<E extends Extension>(ext: E): this;
  addEntrypoint(def: EntrypointDef): this;
  build(): Promise<AgentRuntime>;
}

.use(extension)

Adds an extension to the agent:

const agent = await createAgent(meta)
  .use(http())
  .use(payments({ config }))
  .use(a2a())
  .build();

Extensions are applied in order. Each extension can access context from previous extensions.

.addEntrypoint(def)

Adds an entrypoint definition:

const agent = await createAgent(meta)
  .use(http())
  .addEntrypoint({
    key: 'greet',
    input: z.object({ name: z.string() }),
    async handler({ input }) {
      return { output: { message: `Hello, ${input.name}!` } };
    },
  })
  .build();

.build()

Builds the agent runtime:

const agent = await createAgent(meta)
  .use(http())
  .build();

// Access runtime properties
agent.config       // Agent configuration
agent.agent        // AgentCore with entrypoint management
agent.handlers     // HTTP handlers (if http extension used)

AgentRuntime

The built agent runtime:

type AgentRuntime = {
  config: AgentConfig;
  agent: AgentCore;
  handlers?: AgentHttpHandlers;    // If http() used
  payments?: PaymentsRuntime;      // If payments() used
  wallets?: WalletsRuntime;        // If wallets() used
  a2a?: A2ARuntime;               // If a2a() used
  ap2?: AP2Runtime;               // If ap2() used
};

AgentCore

Core agent functionality:

interface AgentCore {
  addEntrypoint(def: EntrypointDef): void;
  getEntrypoint(key: string): EntrypointDef | undefined;
  getEntrypoints(): EntrypointDef[];
}

Extension System

Extension Interface

interface Extension<R extends Record<string, unknown> = {}> {
  name: string;
  build: (ctx: BuildContext) => R;
  onEntrypointAdded?: (entrypoint: EntrypointDef, runtime: AgentRuntime) => void;
  onBuild?: (runtime: AgentRuntime) => void | Promise<void>;
  onManifestBuild?: (
    card: AgentCardWithEntrypoints,
    runtime: AgentRuntime
  ) => AgentCardWithEntrypoints;
}

BuildContext

type BuildContext = {
  meta: AgentMeta;
  runtime: Partial<AgentRuntime>;
};

Lifecycle Hooks

Hook	When Called	Purpose
build	During .build()	Initialize extension, return runtime slice
onEntrypointAdded	After addEntrypoint()	React to new entrypoints
onBuild	After all extensions built	Final setup (can be async)
onManifestBuild	When building Agent Card	Enhance manifest

Creating a Custom Extension

import type { Extension, BuildContext, AgentRuntime } from '@regent/types/core';

function myExtension(options: MyOptions): Extension<{ myFeature: MyFeature }> {
  return {
    name: 'my-extension',

    build(ctx: BuildContext) {
      // Initialize and return runtime slice
      const myFeature = new MyFeature(options);
      return { myFeature };
    },

    onEntrypointAdded(entrypoint, runtime) {
      // React to entrypoints being added
      console.log(`New entrypoint: ${entrypoint.key}`);
    },

    async onBuild(runtime) {
      // Final setup after all extensions
      await runtime.myFeature?.initialize();
    },

    onManifestBuild(card, runtime) {
      // Add extension info to Agent Card
      return {
        ...card,
        capabilities: {
          ...card.capabilities,
          myFeature: true,
        },
      };
    },
  };
}

Conflict Detection

The builder detects when extensions add the same property:

// Throws: "Conflicting extensions: 'ext1' and 'ext2' both add 'handlers'"
const agent = await createAgent(meta)
  .use(extensionWithHandlers())
  .use(anotherExtensionWithHandlers())
  .build();

EntrypointDef

type EntrypointDef<
  TInput extends z.ZodTypeAny | undefined = z.ZodTypeAny | undefined,
  TOutput extends z.ZodTypeAny | undefined = z.ZodTypeAny | undefined,
> = {
  key: string;
  description?: string;
  input?: TInput;
  output?: TOutput;
  streaming?: boolean;
  price?: EntrypointPrice;
  network?: Network;
  handler?: EntrypointHandler<TInput, TOutput>;
  stream?: EntrypointStreamHandler<TInput>;
  metadata?: Record<string, unknown>;
};

Handler Types

EntrypointHandler

type EntrypointHandler<TInput, TOutput> = (
  ctx: AgentContext & { input: TInput }
) => Promise<{
  output: TOutput;
  usage?: Usage;
  model?: string;
}>;

EntrypointStreamHandler

type EntrypointStreamHandler<TInput> = (
  ctx: AgentContext & { input: TInput },
  emit: (chunk: StreamPushEnvelope) => Promise<void> | void
) => Promise<StreamResult>;

AgentContext

type AgentContext = {
  key: string;
  input: unknown;
  signal: AbortSignal;
  metadata?: Record<string, unknown>;
  runId?: string;
  runtime?: AgentRuntime;
};

Usage

type Usage = {
  prompt_tokens?: number;
  completion_tokens?: number;
  total_tokens?: number;
};

Validation

import { validateAgentMetadata } from '@regent/core';

// Throws if missing required fields
validateAgentMetadata({
  name: 'my-agent',
  version: '1.0.0',
  // description missing - will throw
});

Exports

// Main API
export { createAgent } from '@regent/core';
export { AgentBuilder } from '@regent/core';

// Lower-level API
export { AgentCore, createAgentCore } from '@regent/core';

// Validation
export { validateAgentMetadata } from '@regent/core';

// Re-exported types
export type {
  EntrypointDef,
  EntrypointHandler,
  EntrypointStreamHandler,
  AgentConfig,
  AgentContext,
  Usage,
  Network,
} from '@regent/core';