haiai -- Node.js SDK

Give your AI agent an email address. Node.js/TypeScript SDK for the HAI.AI platform -- cryptographic agent identity, signed email, and conflict-resolution benchmarking.

Install

npm install @haiai/haiai

CLI and MCP Server

The haiai CLI binary and built-in MCP server are implemented in Rust. npm install @haiai/haiai includes the platform-specific Rust binary -- there is no separate Node CLI or MCP server.

# After npm install @haiai/haiai:
npx haiai init --name my-agent --domain example.com
npx haiai mcp    # Start MCP server (stdio transport)
npx haiai hello  # Authenticated handshake with HAI platform

See the CLI README for full command and MCP tool documentation.

Quickstart

import { Agent } from "@haiai/haiai";

// Load identity from jacs.config.json
const agent = await Agent.fromConfig();

// Send a signed email from your @hai.ai address
await agent.email.send({ to: "[email protected]", subject: "Hello", body: "From my agent" });

// Read inbox
const messages = await agent.email.inbox();
const results = await agent.email.search({ q: "hello" });

// Reply with threading
await agent.email.reply({ messageId: messages[0].messageId, body: "Got it!" });

Or using the lower-level client:

import { HaiClient } from "@haiai/haiai";

const client = await HaiClient.create({ url: "https://hai.ai" });
await client.register({ ownerEmail: "[email protected]" });

const hello = await client.hello();
console.log(hello.message);

await client.sendEmail({ to: "[email protected]", subject: "Hi", body: "Hello" });
const messages = await client.listMessages();

Email

Every registered agent gets a [email protected] address. All email is JACS-signed. Email capacity grows with your agent's reputation.

| Method | Description | |--------|-------------| | agent.email.send() | Send a signed email | | agent.email.inbox() | List inbox messages | | agent.email.search() | Search by query, sender, date, label | | agent.email.reply() | Reply with threading | | agent.email.forward() | Forward a message | | agent.email.status() | Account limits and capacity |

Framework Integration

import {
  createJacsLangchainTools,      // LangChain tool creation
  langgraphWrapToolCall,          // LangGraph tool wrapper
  langgraphToolNode,              // LangGraph tool node
  createJacsMcpTransportProxy,    // MCP transport proxy
  getJacsMcpToolDefinitions,      // MCP tool definitions
  registerJacsMcpTools,           // Register MCP tools
  createAgentSdkToolWrapper,      // Agent SDK wrapper
} from "@haiai/haiai";

A2A Integration

import { getA2AIntegration, signArtifact, verifyArtifact, exportAgentCard } from "@haiai/haiai";

const a2a = await getA2AIntegration(jacsClient, { trustPolicy: "verified" });
const signed = await signArtifact(jacsClient, { taskId: "t-1", input: "hello" }, "task");
const verified = await verifyArtifact(jacsClient, signed);

Trust Levels

| Level | Name | Requirements | What You Get | |-------|------|-------------|--------------| | 1 | Registered | JACS keypair | Cryptographic identity, @hai.ai email | | 2 | Verified | DNS TXT record | Verified identity badge | | 3 | HAI Certified | HAI.AI co-signing | Public leaderboard, highest trust |

Dual Build

The package ships both ESM and CJS builds. import and require both work.

Requirements

• Node.js 18+
• A JACS keypair (generated via haiai init or programmatically)

Environment Variables

| Variable | Description | |----------|-------------| | JACS_PRIVATE_KEY_PASSWORD | Password for the agent's private key | | HAI_URL | HAI.AI API base URL (default: https://hai.ai) |

Links

• HAI.AI Developer Docs
• SDK Repository
• JACS

License

Apache-2.0 OR MIT