@towns-labs/agent

An agent framework for Towns.

Installing

We suggest users to quickstart a project using our cli.

$ bunx towns-agent init

If you prefer to install manually:

$ bun add @towns-labs/agent viem hono

Usage

With Node:

import { makeTownsAgent } from "@towns-labs/agent";
import { serve } from "@hono/node-server";

const app = new Hono();
const agent = await makeTownsAgent("<app-private-data-base64>", "<jwt-secret>");

agent.onMessage((handler, { channelId, isMentioned }) => {
  if (isMentioned) {
    handler.sendMessage(channelId, "Hello, world!");
  }
});

const { jwtMiddleware, handler } = agent.start();
app.post("/webhook", jwtMiddleware, handler);

serve({ fetch: app.fetch });

With Bun:

import { makeTownsAgent } from "@towns-labs/agent";

const app = new Hono();
const agent = await makeTownsAgent("<app-private-data-base64>", "<jwt-secret>");

agent.onMessage((handler, { channelId, isMentioned }) => {
  if (isMentioned) {
    handler.sendMessage(channelId, "Hello, world!");
  }
});

const { jwtMiddleware, handler } = agent.start();
app.post("/webhook", jwtMiddleware, handler);

export default app;

Identity Metadata (ERC-8004)

Agents can optionally define ERC-8004 compliant identity metadata for agent discovery and trust.

Minimal Example

Create identity.ts:

import type { AgentAgentIdentityConfig } from "@towns-labs/agent";

const identity = {
  name: "My Agent",
  description: "A helpful agent for Towns",
  image: "https://example.com/agent-logo.png",
  domain: "myAgent.example.com",
} as const satisfies AgentIdentityConfig;

export default identity;

Use in agent setup:

import identity from "./identity";

const agent = await makeTownsAgent(
  process.env.APP_PRIVATE_DATA!,
  process.env.JWT_SECRET!,
  {
    commands,
    identity,
  },
);

// Get metadata for hosting at /.well-known/agent-metadata.json
const metadata = agent.getIdentityMetadata();
app.get("/.well-known/agent-metadata.json", metadata);

Advanced Example

For full ERC-8004 compliance with endpoints and trust models:

import type { AgentIdentityConfig } from "@towns-labs/agent";

const identity = {
  name: "Advanced Agent",
  description: "AI-powered agent with multi-protocol support",
  image: "https://example.com/agent-logo.png",
  motto: "Building the future of agent economies",
  domain: "agent.example.com",

  endpoints: [
    {
      name: "A2A",
      endpoint: "https://agent.example.com/.well-known/agent-card.json",
      version: "0.3.0",
    },
    {
      name: "MCP",
      endpoint: "https://mcp.agent.example.com/",
      version: "2025-06-18",
    },
  ],

  registrations: [],

  supportedTrust: ["reputation", "crypto-economic"],

  attributes: [
    { trait_type: "Category", value: "Gateway" },
    { trait_type: "Model", value: "GPT-4" },
  ],
} as const satisfies AgentIdentityConfig;

export default identity;

The agent automatically adds agentWallet endpoint using the agent's app address and A2A endpoint if domain is configured.

Debug Logging

Agent framework uses debug package for logging. You can enable by setting the DEBUG environment variable to csb:agent.

DEBUG=csb:agent node dist/agent.cjs