Quickstart

Build a working agent in under 5 minutes.

Option 1: High-Level API (Simplest)

import { createRegentAgent } from 'regent-sdk';
import { z } from 'zod';
import { createAgentApp } from '@regent/hono';

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

// Add an entrypoint
agent.runtime.entrypoints.add({
  key: 'greet',
  input: z.object({ name: z.string() }),
  output: z.object({ message: z.string() }),
  handler: async ({ input }) => ({ output: { message: `Hello, ${input.name}!` } }),
});

// Serve it with an adapter (Hono example)
const { app } = await createAgentApp(agent.runtime);

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

Option 2: Using the CLI

bunx @regent/cli my-agent

Select:

1. Adapter: hono

2. Template: blank (or axllm for LLM-powered)

Then:

cd my-agent
bun run dev

Option 3: Low-Level API (Full Control)

import { z } from 'zod';
import { createAgent } from '@regent/core';
import { http } from '@regent/http';
import { createAgentApp } from '@regent/hono';

// 1. Create the agent
const agent = await createAgent({
  name: 'my-agent',
  version: '1.0.0',
  description: 'A helpful assistant',
})
  .use(http())
  .build();

// 2. Create the Hono app
const { app, addEntrypoint } = await createAgentApp(agent);

// 3. Add entrypoints
addEntrypoint({
  key: 'greet',
  description: 'Greets a user by name',
  input: z.object({ name: z.string() }),
  output: z.object({ message: z.string() }),
  async handler({ input }) {
    return { output: { message: `Hello, ${input.name}!` } };
  },
});

addEntrypoint({
  key: 'echo',
  description: 'Echoes back the input',
  input: z.object({ text: z.string() }),
  output: z.object({ text: z.string() }),
  async handler({ input }) {
    return {
      output: { text: input.text },
      usage: { total_tokens: input.text.length },
    };
  },
});

// 4. Start the server
export default {
  port: 3000,
  fetch: app.fetch,
};

Test Your Agent

View the Agent Manifest

curl http://localhost:3000/.well-known/agent.json

Returns the Agent Card describing capabilities:

{
  "protocolVersion": "1.0",
  "name": "my-agent",
  "version": "1.0.0",
  "description": "A helpful assistant",
  "skills": [
    { "id": "greet", "name": "greet", "description": "Greets a user by name" },
    { "id": "echo", "name": "echo", "description": "Echoes back the input" }
  ]
}

List Entrypoints

curl http://localhost:3000/entrypoints

Invoke an Entrypoint

curl -X POST http://localhost:3000/entrypoints/greet/invoke \
  -H "Content-Type: application/json" \
  -d '{"input": {"name": "Alice"}}'

Response:

{
  "run_id": "abc123",
  "status": "succeeded",
  "output": { "message": "Hello, Alice!" }
}

Add Streaming

For LLM responses or long operations, use streaming:

addEntrypoint({
  key: 'chat',
  description: 'Chat with the assistant',
  input: z.object({ message: z.string() }),
  streaming: true,
  async stream(ctx, emit) {
    const response = 'Hello, how can I help you today?';

    // Emit character by character (simulating LLM streaming)
    for (const char of response) {
      await emit({
        kind: 'delta',
        delta: char,
        mime: 'text/plain',
      });
    }

    return {
      output: { completed: true },
      usage: { total_tokens: response.length },
    };
  },
});

Test streaming:

curl -X POST http://localhost:3000/entrypoints/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"input": {"message": "Hello"}}'

Response (SSE):

event: run-start
data: {"kind":"run-start","runId":"abc123"}

event: delta
data: {"kind":"delta","delta":"H","mime":"text/plain","runId":"abc123"}

event: delta
data: {"kind":"delta","delta":"e","mime":"text/plain","runId":"abc123"}

...

event: run-end
data: {"kind":"run-end","runId":"abc123","status":"succeeded","output":{"completed":true}}

Add Payments

Monetize your agent with x402:

import { createAgent } from '@regent/core';
import { http } from '@regent/http';
import { payments, paymentsFromEnv } from '@regent/x402';
import { createAgentApp, withPayments } from '@regent/hono';

const agent = await createAgent({
  name: 'paid-agent',
  version: '1.0.0',
})
  .use(http())
  .use(payments({ config: paymentsFromEnv() }))
  .build();

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

addEntrypoint({
  key: 'premium',
  description: 'Premium analysis',
  price: '$0.01',  // Requires payment
  input: z.object({ text: z.string() }),
  output: z.object({ analysis: z.string() }),
  async handler({ input }) {
    return { output: { analysis: 'Detailed analysis...' } };
  },
});

// Wrap with payment middleware
const appWithPayments = withPayments(app, agent);

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

Set environment variables:

FACILITATOR_URL=https://facilitator.example.com
PAYMENTS_RECEIVABLE_ADDRESS=0xYourWalletAddress
NETWORK=base-sepolia

Register On-Chain Identity

import { createRegentAgent } from 'regent-sdk';

const agent = await createRegentAgent({
  name: 'my-agent',
  description: 'A trusted assistant',
  version: '1.0.0',
  http: { port: 3000 },
  wallet: {
    privateKey: process.env.PRIVATE_KEY,
  },
  identity: {
    chainId: 84532,  // Base Sepolia
    rpcUrl: 'https://sepolia.base.org',
    ipfs: 'pinata',
    ipfsConfig: { pinataJwt: process.env.PINATA_JWT },
  },
  trust: { reputation: true },
});

// Register on-chain (mints ERC-721 NFT)
const { agentId } = await agent.registerOnchain();
console.log('Registered agent:', agentId);  // e.g., "84532:42"

Project Structure

A typical Regent agent project:

my-agent/
├── src/
│   └── index.ts        # Agent definition and entrypoints
├── .env                # Environment variables
├── package.json
└── tsconfig.json

Next Steps

• Concepts: Agents - Deep dive into agent configuration

• Concepts: Entrypoints - Learn about handlers and streaming

• Packages: @regent/erc8004 - On-chain identity and discovery

• Examples - More complete examples