Quickstart: Build Your First Nonhumans Agent

You are five minutes away from an AI agent that can send real email, move money, store memories, and run code on demand. This guide walks you through signing up, installing the SDK, and making your first live API calls — no prior setup required.

Create your free Nonhumans account at nonhumans.ai. Once your account is confirmed, open the dashboard and copy your API key from the API Keys section.Store the key in an environment variable — never paste it directly into your code:

NONHUMANS_KEY=nhk_live_xxxxxxxxxxxxxxxxxxxx

Install the SDK

Choose the package manager you already use. Nonhumans supports TypeScript/Node.js, Python, and Go.

npm install @nonhumans/sdk

yarn add @nonhumans/sdk

pnpm add @nonhumans/sdk

pip install nonhumans

Prefer the CLI? You can scaffold and manage agents directly from your terminal:

npx nonhumans init

Initialize your agent

Import the SDK and create a client using your API key. The Nonhumans instance is the entry point for every primitive.

import { Nonhumans } from '@nonhumans/sdk'

const agent = new Nonhumans({ apiKey: process.env.NONHUMANS_KEY })

from nonhumans import Nonhumans
import os

agent = Nonhumans(api_key=os.environ['NONHUMANS_KEY'])

Your agent is provisioned with a handle, inbox, wallet, and compute the moment the client is initialised with a valid key.

Send your first email

Your agent’s inbox is ready immediately. Call agent.email.send() to deliver a real message from your agent’s verified address, then use agent.email.list() to check received messages.

// Send an email from your agent's verified inbox
await agent.email.send({
  to: 'team@acme.com',
  subject: 'Update from your agent',
  text: 'Closed ticket #482 — log attached.',
})

// List messages received in your agent's inbox
const inbox = await agent.email.list()
console.log(inbox)

# Send an email from your agent's verified inbox
agent.email.send(
    to='team@acme.com',
    subject='Update from your agent',
    text='Closed ticket #482 — log attached.',
)

# List messages received in your agent's inbox
inbox = agent.email.list()
print(inbox)

Emails are sent from your agent’s handle address (e.g. alice@nonhumans.ai) and replies land directly in its inbox.

Move funds and check balances

Your agent’s wallet is ready to send and receive value. Use agent.wallet.send() to transfer funds and agent.wallet.balance() to check what your agent holds.

// Check your agent's wallet balance
const balance = await agent.wallet.balance()
console.log(balance)
// { USDC: '42.00', ETH: '0.01' }

// Transfer USDC to another address
await agent.wallet.send({
  to: '0xRecipientAddress',
  amount: '12.50',
  asset: 'USDC',
})

# Check your agent's wallet balance
balance = agent.wallet.balance()
print(balance)
# { 'USDC': '42.00', 'ETH': '0.01' }

# Transfer USDC to another address
agent.wallet.send(
    to='0xRecipientAddress',
    amount='12.50',
    asset='USDC',
)

Store and search memory

Your agent has a persistent vector memory store. Use agent.memory.store() to save observations and agent.memory.search() to retrieve relevant context across sessions.

// Save a memory entry
await agent.memory.store({
  content: 'User prefers concise updates via email rather than Slack.',
  metadata: { userId: 'user_123' },
})

// Search for relevant memories by natural-language query
const results = await agent.memory.search({
  query: 'communication preferences',
  limit: 5,
})
console.log(results)

# Save a memory entry
agent.memory.store(
    content='User prefers concise updates via email rather than Slack.',
    metadata={'userId': 'user_123'},
)

# Search for relevant memories by natural-language query
results = agent.memory.search(
    query='communication preferences',
    limit=5,
)
print(results)

Run compute and manage secrets

Use agent.compute.run() to execute code on your agent’s always-on compute, and agent.vault.set() / agent.vault.get() to securely store and retrieve credentials.

// Store a credential in the vault
await agent.vault.set({ key: 'STRIPE_KEY', value: 'sk_live_...' })

// Retrieve a credential from the vault
const secret = await agent.vault.get({ key: 'STRIPE_KEY' })

// Run a task on always-on compute
const result = await agent.compute.run({
  code: 'return 1 + 1',
  runtime: 'node',
})
console.log(result)
// { output: 2 }

# Store a credential in the vault
agent.vault.set(key='STRIPE_KEY', value='sk_live_...')

# Retrieve a credential from the vault
secret = agent.vault.get(key='STRIPE_KEY')

# Run a task on always-on compute
result = agent.compute.run(code='1 + 1', runtime='python')
print(result)
# { 'output': 2 }

Deploy your agent

When you are ready to go live, deploy your agent from the CLI. This publishes your agent configuration and makes it continuously available.

npx nonhumans deploy

Once deployed, head back to nonhumans.ai and open the Agent tab. You’ll see your agent’s handle, inbox activity, wallet balance, memory entries, and compute logs — all in one place. From here you can also rotate API keys, configure webhooks, and monitor usage.

Full example

Here is a complete script that exercises all the core primitives in a single agent session — email, wallet, memory, vault, and compute.

import { Nonhumans } from '@nonhumans/sdk'

const agent = new Nonhumans({ apiKey: process.env.NONHUMANS_KEY })

// Send an email from your agent's verified inbox
await agent.email.send({
  to: 'team@acme.com',
  subject: 'Update from your agent',
  text: 'Closed ticket #482 — log attached.',
})

// List received messages
const inbox = await agent.email.list()

// Check wallet balance and transfer funds
const balance = await agent.wallet.balance()
await agent.wallet.send({ to: '0xRecipientAddress', amount: '12.50', asset: 'USDC' })

// Store and retrieve memory
await agent.memory.store({ content: 'Task #482 resolved.', metadata: { task: '482' } })
const memories = await agent.memory.search({ query: 'task resolved', limit: 3 })

// Manage secrets in the vault
await agent.vault.set({ key: 'STRIPE_KEY', value: 'sk_live_...' })
const secret = await agent.vault.get({ key: 'STRIPE_KEY' })

// Run code on always-on compute
const result = await agent.compute.run({ code: 'return 1 + 1', runtime: 'node' })

from nonhumans import Nonhumans
import os

agent = Nonhumans(api_key=os.environ['NONHUMANS_KEY'])

# Send an email from your agent's verified inbox
agent.email.send(
    to='team@acme.com',
    subject='Update from your agent',
    text='Closed ticket #482 — log attached.',
)

# List received messages
inbox = agent.email.list()

# Check wallet balance and transfer funds
balance = agent.wallet.balance()
agent.wallet.send(to='0xRecipientAddress', amount='12.50', asset='USDC')

# Store and retrieve memory
agent.memory.store(content='Task #482 resolved.', metadata={'task': '482'})
memories = agent.memory.search(query='task resolved', limit=3)

# Manage secrets in the vault
agent.vault.set(key='STRIPE_KEY', value='sk_live_...')
secret = agent.vault.get(key='STRIPE_KEY')

# Run code on always-on compute
result = agent.compute.run(code='1 + 1', runtime='python')

What’s next?

You’ve got a working agent. Here’s where to go depending on what you want to build next.

Primitives

Deep-dive into every capability — email, wallet, memory, compute, models, and more.

Guides

Step-by-step tutorials for common agent patterns like scheduling, payments, and retrieval.

API Reference

Full REST API documentation with every endpoint, request schema, and response example.

​Full example

​What’s next?

Primitives

Guides

API Reference

Full example

What’s next?