Concepts

An agent is the core unit in Regent SDK. It represents an autonomous service with typed capabilities (entrypoints), optional payments, and discoverable metadata.

Creating an Agent

High-Level API

Use createRegentAgent() for the simplest setup:

import { createRegentAgent } from 'regent-sdk';

const agent = await createRegentAgent({
  name: 'my-agent',
  version: '1.0.0',
  description: 'An AI-powered assistant',
  http: { port: 3000 },
});

Low-Level API

Use createAgent() with the extension pattern for full control:

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();

The createAgent() function returns an AgentBuilder that lets you compose extensions before calling .build().

Agent Metadata

The AgentMeta type describes your agent for discovery and display:

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

Example with Full Metadata

const agent = await createAgent({
  name: 'trading-advisor',
  version: '1.0.0',
  description: 'AI-powered trading recommendations and market analysis',
  image: 'https://my-agent.example.com/og-image.png',
  url: 'https://my-agent.example.com',
})
  .use(http())
  .build();

This metadata is used to:

• Generate the Agent Card (/.well-known/agent.json) for A2A discovery

• Render Open Graph tags for social sharing

• Display information on the landing page (if enabled)

The Extension System

Agents are built by composing extensions. Each extension adds capabilities:

import { createAgent } from '@regent/core';
import { http } from '@regent/http';
import { wallets, walletsFromEnv } from '@regent/wallet';
import { payments, paymentsFromEnv } from '@regent/x402';
import { a2a } from '@regent/a2a';

const agent = await createAgent({
  name: 'full-featured-agent',
  version: '1.0.0',
})
  .use(http())                                    // HTTP protocol support
  .use(wallets({ config: walletsFromEnv() }))     // Wallet management
  .use(payments({ config: paymentsFromEnv() }))   // x402 payments
  .use(a2a())                                     // Agent-to-Agent protocol
  .build();

Available Extensions

Extension	Package	Purpose
http()	@regent/http	HTTP request/response handling, SSE streaming
wallets()	@regent/wallet	Wallet management for agent operations
payments()	@regent/x402	x402 payment protocol
a2a()	@regent/a2a	Agent-to-Agent communication
ap2()	@regent/ap2	Agent Payments Protocol

Extensions are independent and can be used in any combination.

Extension Interface

Extensions follow a consistent 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;
}

Lifecycle Hooks:

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

Conflict Detection

The builder automatically detects when two extensions add the same property:

// This throws an error:
// "Conflicting extensions: 'ext1' and 'ext2' both add 'handlers' property"
const agent = await createAgent(meta)
  .use(extensionThatAddsHandlers())
  .use(anotherExtensionThatAddsHandlers())
  .build();

AgentBuilder

The AgentBuilder provides a fluent API:

class AgentBuilder {
  // Add an extension
  use<E extends Extension>(ext: E): this;

  // Add an entrypoint definition
  addEntrypoint(def: EntrypointDef): this;

  // Build the runtime
  build(): Promise<AgentRuntime>;
}

Adding Entrypoints via Builder

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();

AgentRuntime

The built agent runtime provides access to all configured capabilities:

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

AgentCore

The core agent manages entrypoints:

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

Framework Adapters

After building an agent, use an adapter to expose it via your preferred framework:

Hono

import { createAgentApp } from '@regent/hono';

const { app, addEntrypoint } = await createAgentApp(agent);

addEntrypoint({
  key: 'greet',
  input: z.object({ name: z.string() }),
  async handler({ input }) {
    return { output: { message: `Hello, ${input.name}!` } };
  },
});

export default {
  port: 3000,
  fetch: app.fetch,
};

Express

import { createAgentApp } from '@regent/express';

const { app, addEntrypoint } = await createAgentApp(agent);

// Add entrypoints...

app.listen(3000);

TanStack Start

import { createTanStackRuntime } from '@regent/tanstack';

export const { runtime, handlers } = await createTanStackRuntime(agent);

Agent Card

Every agent automatically generates an Agent Card at /.well-known/agent.json. This follows the A2A protocol and includes:

• Agent metadata (name, version, description)

• Supported interfaces and capabilities

• Available skills (entrypoints)

• Payment methods (if configured)

• Identity registrations (if configured)

Example Agent Card:

{
  "protocolVersion": "1.0",
  "name": "my-agent",
  "version": "1.0.0",
  "description": "An AI-powered assistant",
  "supportedInterfaces": [
    {
      "url": "https://my-agent.example.com",
      "protocolBinding": "http"
    }
  ],
  "capabilities": {
    "streaming": true
  },
  "skills": [
    {
      "id": "chat",
      "name": "chat",
      "description": "Chat with the assistant"
    }
  ]
}

HTTP Endpoints

When using the http() extension and a framework adapter, your agent exposes:

Endpoint	Method	Purpose
/.well-known/agent.json	GET	Agent Card for A2A discovery
/entrypoints	GET	List available entrypoints
/entrypoints/:key/invoke	POST	Invoke an entrypoint
/entrypoints/:key/stream	POST	Stream from an entrypoint (SSE)
/tasks	POST	Create a new task
/tasks	GET	List tasks
/tasks/:id	GET	Get task status
/tasks/:id/cancel	POST	Cancel a task
/tasks/:id/subscribe	GET	Subscribe to task updates (SSE)
/health	GET	Health check

Next Steps

• Entrypoints - Define typed capabilities for your agent

• Packages: @regent/core - Core package reference