/agents · read me first

For AI agents

You are an AI agent and you need a human. One call opens a live session with a verified human expert; you stream their replies, keep talking, and hand control back when it is resolved.

this page as markdown: /agents.md

discover

curl https://chatwithhuman.chrismai.ai/llms.txt
curl https://chatwithhuman.chrismai.ai/openapi.json
curl https://chatwithhuman.chrismai.ai/agents.md

When to escalate

-Ambiguous intent you cannot resolve with another clarifying question.
-Sensitive context (money, health, legal, account access) that needs human judgment.
-A task that requires a human action or sign-off you cannot perform.
-The user explicitly asks for a human.

The loop

Implemented routes, schemas in /openapi.json.

#	Call	What it does
1	POST /api/sessions	Open a session with agent_id + context (Authorization: Bearer <API key>). Returns session_id, status "queued", eta_seconds.
2	GET /api/sessions/{id}/events	Server-Sent Events: status changes (queued → connected → closed) and human messages. Ping every 20 s.
3	POST /api/sessions/{id}/messages	Send your messages (role "agent") into the live session.
4	GET /api/sessions/{id}	Read status and the full transcript at any time; resume your flow when status is "closed".

1 · escalate

curl -X POST https://chatwithhuman.chrismai.ai/api/sessions \
  -H "Authorization: Bearer $CHATWITHHUMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"agent_abc123","context":"User is asking about a refund for order #8821","tier":"priority"}'
# 201 {"session_id":"ses_…","status":"queued","eta_seconds":12,"billing_started":false,"tier":"priority","rate_cents_per_minute":2500,…}

2 · listen

curl -N https://chatwithhuman.chrismai.ai/api/sessions/ses_x9k2m/events \
  -H "Authorization: Bearer $CHATWITHHUMAN_API_KEY"
# data: {"type":"status","status":"connected"}
# data: {"type":"message","message":{"role":"human","content":"…"}}

3 · reply

curl -X POST https://chatwithhuman.chrismai.ai/api/sessions/ses_x9k2m/messages \
  -H "Authorization: Bearer $CHATWITHHUMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role":"agent","content":"Order #8821 was paid by card ending 4242."}'

4 · read

curl https://chatwithhuman.chrismai.ai/api/sessions/ses_x9k2m \
  -H "Authorization: Bearer $CHATWITHHUMAN_API_KEY"   # status + full transcript

Writing good context

-Put everything the human needs in context: the user goal, what you already tried, relevant ids.
-Use tier: "priority" ($25/min, guaranteed fast human response) when a user is waiting on it; otherwise the default standard ($10/min).
-Attach your own correlation ids in metadata; they are echoed back.

Billing

Billing starts when a human connects (status "connected"), not when you create the session: whole minutes at the session tier rate (Standard $10/min, Priority $25/min), no platform fee.

Plan	Rate	API tier	For
Standard	$10 / min	"standard"	Developers and small teams
Priority	$25 / min	"priority"	Funded startups and crypto projects
Enterprise	from $250,000 / year	contract	Public companies and large institutions

Same call in other languages

One request, pick your client. Add "tier": "priority" for $25/min guaranteed fast response.

curl -X POST https://chatwithhuman.chrismai.ai/api/sessions \
  -H "Authorization: Bearer $CHATWITHHUMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_id": "agent_abc123",
  "context": "User is asking about a refund for order #8821",
  "tier": "standard"
}'

const res = await fetch("https://chatwithhuman.chrismai.ai/api/sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CHATWITHHUMAN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "agent_id": "agent_abc123",
    "context": "User is asking about a refund for order #8821",
    "tier": "standard"
  }),
});
const { session_id, eta_seconds } = await res.json();

import os, requests

r = requests.post(
    "https://chatwithhuman.chrismai.ai/api/sessions",
    headers={"Authorization": f"Bearer {os.environ['CHATWITHHUMAN_API_KEY']}"},
    json={
        "agent_id": "agent_abc123",
        "context": "User is asking about a refund for order #8821",
        "tier": "standard",  # or "priority" ($25/min)
    },
)
session = r.json()  # {"session_id": "ses_x9k2m", "status": "queued", "tier": "standard", ...}

MCP server

plannedThere is no MCP server yet. The descriptor at /.well-known/mcp.json documents the intended shape so agent runtimes can plan for it. Until then, use the REST API in /openapi.json. Descriptor: /.well-known/mcp.json

Planned tool	REST equivalent (today)	Arguments
escalate_to_human	POST /api/sessions	agent_id, context, priority?, metadata?
send_message	POST /api/sessions/{id}/messages	session_id, content
get_session	GET /api/sessions/{id}	session_id
close_session	PATCH /api/sessions/{id}	session_id (status: "closed")

Machine-readable

/llms.txt — llmstxt.org index: summary + links
/llms-full.txt — All docs, pricing and FAQ inlined in one file
/openapi.json — OpenAPI 3.1 spec of the implemented /api routes
/agents.md — Guide for AI agents: when and how to hand off to a human
/.well-known/ai-plugin.json — AI plugin manifest (points to openapi.json)
/.well-known/mcp.json — MCP server descriptor — status: planned
/index.md — Markdown twin of every page (/docs.md, /pricing.md …)
/sitemap.xml — Sitemap incl. markdown twins
/robots.txt — Crawl policy — AI crawlers explicitly welcome

## When to escalate

## The loop

## Writing good context

## Billing

## Same call in other languages

## MCP server

## Machine-readable