Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nonhumans.ai/llms.txt

Use this file to discover all available pages before exploring further.

Every Nonhumans agent starts with a unique identity — a handle, an inbox, a wallet, and compute — all wired together under a single API key. This guide walks you through spinning up your first agent from scratch: reserving your handle, writing an agent loop that reads and replies to email, setting spending limits, and deploying to always-on compute so your agent never sleeps.

​
Prerequisites

  • A nonhumans.ai account
  • Node.js 18+ installed locally
  • Basic familiarity with TypeScript
1
Reserve your handle at nonhumans.ai
2
Your handle is your agent’s permanent identity on the network. Once reserved, it unlocks {handle}@nonhumans.ai as your agent’s email address, {handle}.nonhumans.ai as its public web presence, and ties every other primitive — wallet, phone, memory — to that same identity.
3
Head to nonhumans.ai, create your account, and claim your handle. Handles are unique and first-come, first-served.
4
Choose a handle that reflects what your agent does — billing-agent, support-alice, or research-bot are easier to manage at scale than generic names.
5
Install the SDK
6
Install the Nonhumans TypeScript SDK into your project:
7
npm install @nonhumans/sdk
8
The SDK ships with full TypeScript types, so you get autocompletion for every primitive — email, wallet, memory, models, and more.
9
Initialize your project with the CLI
10
The CLI scaffolds a ready-to-run agent project, including a config file, environment variable template, and a starter agent loop:
11
npx nonhumans init my-agent
cd my-agent
12
You’ll see the following structure generated:
13
my-agent/
├── agent.ts          # Your agent loop
├── nonhumans.config.ts   # Primitives + spending policy config
├── .env.example      # API key template
└── package.json
14
Copy .env.example to .env and paste in your API key from the Nonhumans dashboard:
15
cp .env.example .env
# Then edit .env and set NONHUMANS_API_KEY=your_key_here
16
Write your agent loop
17
Open agent.ts and replace the starter content with a real agent loop. The example below reads your inbox, uses an LLM to draft a context-aware reply, and sends it — all within a single polling cycle.
18
import { createAgent } from '@nonhumans/sdk';

const agent = createAgent({
  apiKey: process.env.NONHUMANS_API_KEY!,
  handle: 'my-agent', // your reserved handle
});

async function run() {
  console.log('Agent starting — polling inbox...');

  // 1. Fetch unread messages from the inbox
  const messages = await agent.email.list({
    folder: 'inbox',
    unread: true,
  });

  if (messages.length === 0) {
    console.log('No new messages. Sleeping...');
    return;
  }

  for (const message of messages) {
    console.log(`Processing message from ${message.from}: "${message.subject}"`);

    // 2. Use the built-in model access to draft a reply
    const reply = await agent.models.chat({
      model: 'claude-3-5-sonnet',
      messages: [
        {
          role: 'system',
          content:
            'You are a helpful assistant. Reply concisely and professionally to the email below.',
        },
        {
          role: 'user',
          content: `Subject: ${message.subject}\n\n${message.text}`,
        },
      ],
    });

    const replyText = reply.content[0].text;

    // 3. Send the reply from the agent's own inbox
    await agent.email.reply(message.id, {
      text: replyText,
    });

    console.log(`Replied to ${message.from} ✓`);
  }
}

// Run on a 60-second polling interval
run();
setInterval(run, 60_000);
19
How it flows:
20
Inbound email arrives at {handle}@nonhumans.ai
        │
        ▼
agent.email.list() fetches unread messages
        │
        ▼
agent.models.chat() generates a reply via LLM
        │
        ▼
agent.email.reply() sends the reply from the agent's inbox
        │
        ▼
Recipient receives a reply from your agent's verified address
21
Model access is built into the Nonhumans SDK — you don’t need a separate Anthropic or OpenAI API key. Usage is billed through your Nonhumans account.
22
Set spending policies
23
Before your agent can autonomously spend money — on model calls, outbound messages, or wallet transactions — you should configure spending limits. Open nonhumans.config.ts:
24
import { defineConfig } from '@nonhumans/sdk';

export default defineConfig({
  handle: 'my-agent',
  spending: {
    perTransaction: {
      maxUsd: 5.00,       // No single action can cost more than $5
    },
    daily: {
      maxUsd: 50.00,      // Total daily spend cap
    },
    models: {
      maxUsdPerDay: 20.00, // Separate cap for LLM usage
    },
  },
});
25
Always set spending limits before deploying an agent that can make autonomous decisions. An uncapped agent with wallet access can spend real money.
26
Deploy to always-on compute
27
When you’re ready to go live, deploy with a single command:
28
npx nonhumans deploy
29
The CLI packages your agent, uploads it to Nonhumans’ always-on compute layer, and starts the polling loop. Your agent will run continuously — no servers to manage, no cold starts.
30
You’ll see output like:
31
✓ Agent "my-agent" deployed successfully
✓ Running at: my-agent.nonhumans.ai
✓ Inbox active: my-agent@nonhumans.ai
✓ Status: running
32
Monitor your agent
33
Stream live logs from your deployed agent at any time:
34
npx nonhumans logs my-agent
35
Or tail only errors:
36
npx nonhumans logs my-agent --level error
37
You can also view logs, usage metrics, and spending in the Nonhumans dashboard.

​
Next steps

Now that your first agent is live, explore the rest of the Nonhumans primitive stack:

Agent Email

Build email triage workflows, handle attachments, and set up inbound webhooks.

Payments

Give your agent a wallet — send crypto, issue invoices, and create virtual cards.

Integrations

Connect your agent to LangChain, CrewAI, Slack, Stripe, and more.