> ## 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.

# Create and Deploy Your First AI Agent with Nonhumans

> Step-by-step guide to creating a Nonhumans agent, provisioning primitives, writing your agent loop, and deploying to always-on compute.

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](https://nonhumans.ai) account
* Node.js 18+ installed locally
* Basic familiarity with TypeScript

***

<Steps>
  ### Reserve your handle at nonhumans.ai

  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.

  Head to [nonhumans.ai](https://nonhumans.ai), create your account, and claim your handle. Handles are unique and first-come, first-served.

  <Tip>
    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.
  </Tip>

  ### Install the SDK

  Install the Nonhumans TypeScript SDK into your project:

  ```bash theme={null}
  npm install @nonhumans/sdk
  ```

  The SDK ships with full TypeScript types, so you get autocompletion for every primitive — email, wallet, memory, models, and more.

  ### Initialize your project with the CLI

  The CLI scaffolds a ready-to-run agent project, including a config file, environment variable template, and a starter agent loop:

  ```bash theme={null}
  npx nonhumans init my-agent
  cd my-agent
  ```

  You'll see the following structure generated:

  ```text theme={null}
  my-agent/
  ├── agent.ts          # Your agent loop
  ├── nonhumans.config.ts   # Primitives + spending policy config
  ├── .env.example      # API key template
  └── package.json
  ```

  Copy `.env.example` to `.env` and paste in your API key from the [Nonhumans dashboard](https://nonhumans.ai/dashboard):

  ```bash theme={null}
  cp .env.example .env
  # Then edit .env and set NONHUMANS_API_KEY=your_key_here
  ```

  ### Write your agent loop

  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.

  ```typescript agent.ts theme={null}
  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);
  ```

  **How it flows:**

  ```text theme={null}
  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
  ```

  <Note>
    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.
  </Note>

  ### Set spending policies

  Before your agent can autonomously spend money — on model calls, outbound messages, or wallet transactions — you should configure spending limits. Open `nonhumans.config.ts`:

  ```typescript nonhumans.config.ts theme={null}
  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
      },
    },
  });
  ```

  <Warning>
    Always set spending limits before deploying an agent that can make autonomous decisions. An uncapped agent with wallet access can spend real money.
  </Warning>

  ### Deploy to always-on compute

  When you're ready to go live, deploy with a single command:

  ```bash theme={null}
  npx nonhumans deploy
  ```

  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.

  You'll see output like:

  ```text theme={null}
  ✓ Agent "my-agent" deployed successfully
  ✓ Running at: my-agent.nonhumans.ai
  ✓ Inbox active: my-agent@nonhumans.ai
  ✓ Status: running
  ```

  ### Monitor your agent

  Stream live logs from your deployed agent at any time:

  ```bash theme={null}
  npx nonhumans logs my-agent
  ```

  Or tail only errors:

  ```bash theme={null}
  npx nonhumans logs my-agent --level error
  ```

  You can also view logs, usage metrics, and spending in the [Nonhumans dashboard](https://nonhumans.ai/dashboard).
</Steps>

***

## Next steps

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

<CardGroup cols={3}>
  <Card title="Agent Email" icon="envelope" href="/guides/send-email">
    Build email triage workflows, handle attachments, and set up inbound webhooks.
  </Card>

  <Card title="Payments" icon="credit-card" href="/guides/payments">
    Give your agent a wallet — send crypto, issue invoices, and create virtual cards.
  </Card>

  <Card title="Integrations" icon="plug" href="/guides/integrations">
    Connect your agent to LangChain, CrewAI, Slack, Stripe, and more.
  </Card>
</CardGroup>