Nonhumans Python SDK: Full AI Agent Reference Guide

from nonhumans import Nonhumans
import os

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

# Send an email
agent.email.send(
    to="hiring@acme.com",
    subject="Application received",
    body="Thank you for applying. We will be in touch shortly.",
)

# List recent unread messages
inbox = agent.email.list(limit=20, unread=True)
for message in inbox:
    print(message.subject, message.from_address)

# Fetch a single message by ID
message = agent.email.get("msg_01hx...")

# Reply to a thread
agent.email.reply(
    "msg_01hx...",
    body="Following up on your earlier question — see details below.",
)

# Check balances
balances = agent.wallet.balance()
# {'usdc': '250.00', 'eth': '0.412', 'usd': '1042.50'}

# Send a payment
agent.wallet.send(
    to="0xAbC123...",
    amount="50",
    currency="usdc",
    memo="Contractor payout — March",
)

# Create a payment invoice
invoice = agent.wallet.invoice.create(
    amount="200",
    currency="usd",
    description="Consulting fee",
    due_date="2025-04-01",
)
print(invoice.payment_url)

# Issue a virtual card
card = agent.wallet.card.create(
    label="Cloud infra budget",
    limit_amount="500",
    limit_currency="usd",
)

# Store a memory
agent.memory.store(
    content="User prefers email summaries on Monday mornings.",
    metadata={"user_id": "usr_99", "category": "preferences"},
)

# Semantic search
results = agent.memory.search(query="email preferences", top_k=5)
for record in results:
    print(record.content, record.score)

# Upload a file to agent storage
with open("contract.pdf", "rb") as f:
    file_ref = agent.memory.files.upload(
        name="contract.pdf",
        content=f.read(),
        mime_type="application/pdf",
    )
print(file_ref.url)

# Chat completion
response = agent.models.chat(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful recruiting assistant."},
        {"role": "user", "content": "Summarise this resume in three bullet points."},
    ],
    temperature=0.3,
)
print(response.choices[0].message.content)

# Generate embeddings
embedding = agent.models.embed(
    model="text-embedding-3-small",
    input="Candidate has 5 years of Python experience.",
)
print(len(embedding.data[0].embedding))  # e.g. 1536

# Execute a Python snippet on agent compute
result = agent.compute.run(
    runtime="python",
    code="""
data = [1, 2, 3]
return [x * 2 for x in data]
""",
)
print(result.output)  # [2, 4, 6]

# Store a secret
agent.vault.set("stripe_key", "sk_live_...")

# Retrieve a secret
stripe_key = agent.vault.get("stripe_key")

# List all stored secret names (values are never returned in list)
keys = agent.vault.list()
# ['stripe_key', 'openai_key', 'twilio_sid']

# Delete a secret
agent.vault.delete("stripe_key")

# Send an SMS
agent.phone.sms(
    to="+14155550199",
    body="Your verification code is 849201.",
)

# Initiate an outbound call
call = agent.phone.call(
    to="+14155550199",
    script="Hello, this is Alice calling from Acme to confirm your appointment.",
)

# Register a webhook endpoint
agent.web.endpoint.register(
    path="/webhooks/stripe",
    method="POST",
    handler=lambda req: {"status": 200, "body": {"received": True}},
)

# Set calendar availability
agent.web.calendar.set_availability(
    timezone="America/New_York",
    slots=[
        {"day": "monday", "start": "09:00", "end": "17:00"},
        {"day": "wednesday", "start": "09:00", "end": "12:00"},
    ],
)

import asyncio
from nonhumans import AsyncNonhumans
import os

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

async def process_inbox():
    emails = await agent.email.list(unread=True, limit=50)

    for email in emails:
        # Score with an LLM
        score = await agent.models.chat(
            model="gpt-4o",
            messages=[
                {"role": "system", "content": "Rate this application 1–10."},
                {"role": "user", "content": email.body},
            ],
        )
        # Store result
        await agent.memory.store(
            content=f"Score for {email.from_address}: {score.choices[0].message.content}",
            metadata={"email_id": email.id},
        )
        # Reply
        await agent.email.reply(email.id, body="Thanks for your application!")

asyncio.run(process_inbox())

from nonhumans import Nonhumans, NonhumansError
import os

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

try:
    agent.email.send(
        to="not-an-email",
        subject="Test",
        body="Hello",
    )
except NonhumansError as e:
    print(f"[{e.status}] {e.code}: {e.message}")
    # e.g. [422] validation_error: 'to' must be a valid email address

from nonhumans import Nonhumans, NonhumansError
import os

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

def process_applications():
    # 1. Fetch unread emails
    emails = agent.email.list(unread=True, limit=50)
    print(f"Found {len(emails)} new application(s).")

    for email in emails:
        try:
            # 2. Score the application with an LLM
            score = agent.models.chat(
                model="gpt-4o",
                messages=[
                    {
                        "role": "system",
                        "content": (
                            "You are a recruiting assistant. "
                            "Rate the candidate 1–10 and give a one-sentence reason."
                        ),
                    },
                    {"role": "user", "content": email.body},
                ],
                temperature=0,
            )
            score_text = score.choices[0].message.content

            # 3. Persist to memory
            agent.memory.store(
                content=f"Application from {email.from_address}: {score_text}",
                metadata={"email_id": email.id, "from": email.from_address},
            )

            # 4. Send a personalised reply
            agent.email.reply(
                email.id,
                body=(
                    "Hi,\n\n"
                    "Thank you for reaching out. We have received your application "
                    "and will review it shortly.\n\n"
                    "Best,\nAlice"
                ),
            )

        except NonhumansError as e:
            print(f"Failed to process {email.id}: {e.message}")

if __name__ == "__main__":
    process_applications()