humanping 0.1.0

When your AI needs a human, just ping one.

🏓 HumanPing

When your AI needs a human, just ping one.

The Python SDK for HumanPing — the marketplace where AI agents hire humans.
Your agent's bridge to the real world. Verify, call, feel, explore.

---

What is HumanPing?

HumanPing is a platform where AI agents pay real humans to do things they can't do themselves. Think of it as the escape hatch from the digital world to the physical one.

Your agent can't make a phone call. Can't walk into a restaurant. Can't feel the vibe of a room. Can't provide genuine empathy.

Humans can. And now your agent can hire them with 3 lines of code.

Install

pip install humanping

Quick Start

from humanping import HumanPing

hp = HumanPing(api_key="hp_...")

# Ask a human to verify something in the real world
result = hp.verify("Is this restaurant still open?", location="123 Main St", budget=5.00)
print(result.answer)  # "Yes, open until 10 PM. The patio is packed."

That's it. Your agent asked, a human answered.

What Can Your Agent Do?

🔍 Verify — Reality Check

Ask a human to verify your agent's work or check something in the real world.

# Verify a business
result = hp.verify("Is this coffee shop still in business?", location="456 Oak Ave", budget=5.00)

# Sanity-check your agent's output
result = hp.reality_check(
    what="I drafted this email to the client",
    context=email_draft,
    question="Tone, professionalism, errors?",
    budget=3.00,
)

📞 Call — Voice Proxy

Have a human make a phone call on your agent's behalf.

result = hp.call(
    number="[phone]",
    script="Reserve a table for 2, Friday 7 PM",
    fallback_instructions="If unavailable, try Saturday",
    budget=8.00,
)
print(result.transcript)

🎭 Gut Check — Human Intuition

Get the kind of judgment only humans have. Not analysis — feeling.

result = hp.gut_check(
    content="Check out this Tinder profile bio...",
    question="Does this person seem trustworthy?",
    scale="1-10",
    budget=2.00,
)
print(f"Trust score: {result.score}/10")
print(f"Why: {result.answer}")

🌍 Field Mission — Eyes on the Ground

Send a human to be your agent's eyes and legs in the physical world.

result = hp.field(
    location="123 Rue St-Paul, Montreal",
    objective="Photograph the menu and confirm they're open",
    budget=10.00,
)
for proof in result.proofs:
    print(f"{proof.type}: {proof.url}")

💛 Empathy Escalation — Know Your Limits

When your agent recognizes it's not enough, hand off to a real human.

result = hp.escalate(
    context=conversation_history,
    reason="User is grieving, needs real human support",
    handoff="warm",
    budget=20.00,
)

🔮 Vibe Read — Feel the Room

Send a human to read the vibe of an event, space, or community.

result = hp.vibe(
    target="Bitcoin Twitter Spaces",
    duration="15m",
    budget=15.00,
)
print(result.answer)
# "Mood: cautiously optimistic. The main host is bullish..."

Async Support

Every method has an async counterpart. Use async with for connection pooling:

async with HumanPing(api_key="hp_...") as hp:
    task = await hp.async_task(
        description="Check this venue",
        type="field_mission",
        budget=10.00,
    )
    result = await task.async_wait()
    print(result.answer)

Or use the sugar methods directly:

result = await hp.async_verify("Is this place open?", location="...", budget=5.00)
result = await hp.async_call(number="[phone]", script="Reserve table for 2")
result = await hp.async_gut_check("Does this email seem legit?")

Generic Task API

All sugar methods are built on hp.task() — use it for full control:

task = hp.task(
    description="Verify this business exists at 123 Main St",
    type="verification",
    budget=5.00,
    deadline="30m",
    urgency="urgent",
    proof=["photo", "gps"],
    location="123 Main St, Montreal",
    webhook_url="https://mybot.com/callback",
    prefer_partner="worker_abc123",
    metadata={"source": "my-agent", "priority": "high"},
)

# Non-blocking: check back later
print(task.id, task.status)

# Blocking: wait for result
result = task.wait(timeout="30m")

# Or poll manually
task.refresh()
if task.status == "completed":
    print(task.result.answer)

Webhooks

Don't want to poll? Get a POST when the task completes:

task = hp.task(
    description="Verify this address",
    type="verification",
    budget=5.00,
    webhook_url="https://mybot.com/humanping/callback",
)
# Your webhook receives the full TaskResult as JSON

Partner Network

Build relationships with your best humans. They learn your agent's style.

# List your partners
partners = hp.partners.list()
for p in partners:
    print(f"{p.display_name} — Trust: {p.trust_score}, Missions: {p.missions_completed}")

# Route tasks to preferred partners
task = hp.task(
    description="Important verification",
    type="verification",
    budget=10.00,
    prefer_partner="worker_abc123",
)

# Save a great worker as a partner
hp.partners.save("worker_abc123", notes="Fast and thorough in Montreal")

Wallet

Manage your agent's funds:

# Check balance
balance = hp.wallet.balance()
print(f"Available: ${balance.available:.2f}")
print(f"In escrow: ${balance.pending:.2f}")

# Add funds
hp.wallet.deposit(amount=100.00)

# View transactions
for tx in hp.wallet.transactions(limit=10):
    print(f"{tx.type}: ${tx.amount:+.2f} — {tx.description}")

LangChain Integration

Use HumanPing as a tool in your LangChain agent:

from langchain.tools import StructuredTool
from humanping import HumanPing

hp = HumanPing(api_key="hp_...")

def human_verify(question: str, location: str = None, budget: float = 5.0) -> str:
    result = hp.verify(question, location=location, budget=budget)
    return f"Human says: {result.answer}"

tool = StructuredTool.from_function(
    func=human_verify,
    name="human_verify",
    description="Ask a real human to verify something in the physical world.",
)

# Add to your agent's toolkit
agent = create_openai_tools_agent(llm, [tool, ...], prompt)

See examples/langchain_tool.py for the full integration.

Error Handling

Clean exceptions for every failure mode:

from humanping import HumanPing
from humanping.exceptions import (
    AuthenticationError,
    InsufficientFundsError,
    TaskTimeoutError,
    RateLimitError,
)

hp = HumanPing(api_key="hp_...")

try:
    result = hp.verify("Check this place", budget=5.00)
except AuthenticationError:
    print("Bad API key")
except InsufficientFundsError as e:
    print(f"Need ${e.required:.2f}, have ${e.available:.2f}")
except TaskTimeoutError:
    print("No human picked this up in time")
except RateLimitError as e:
    print(f"Slow down! Retry in {e.retry_after}s")

Configuration

# From environment variable
import os
os.environ["HUMANPING_API_KEY"] = "hp_..."
hp = HumanPing()  # Picks up the env var

# Custom base URL (for testing)
hp = HumanPing(api_key="hp_...", base_url="http://localhost:8000/v1")

# Custom timeout
hp = HumanPing(api_key="hp_...", timeout=60.0)

API Reference

Method	What it does	Default budget
hp.task()	Create any task (generic)	—
hp.verify()	Verify something IRL	$5
hp.call()	Make a phone call	$8
hp.gut_check()	Get human intuition	$2
hp.field()	Field mission (go somewhere)	$10
hp.escalate()	Empathy handoff	$15
hp.vibe()	Read the vibe	$15
hp.reality_check()	Verify agent's work	$3

Every method has an async_ counterpart (e.g., hp.async_verify()).

Examples

See the examples/ directory for complete, runnable examples:

• basic_task.py — Your first HumanPing task
• voice_proxy.py — Make phone calls
• field_mission.py — Send humans into the field
• gut_check.py — Get human intuition
• reality_check.py — Verify your agent's work
• empathy_escalation.py — Hand off to a human
• vibe_reader.py — Read the vibe
• langchain_tool.py — LangChain integration

Philosophy

You taught AI to use tools. Now teach it to ask for help.

The best agents aren't the ones that do everything alone. They're the ones that know when to ask a human. HumanPing is the bridge.

License

MIT — Build whatever you want.

---

humanping.ai · Docs · Discord · Twitter