Human Agents

Human agents are full mesh nodes that delegate execution to a real person via webhook. The mesh treats human responses identically to LLM responses — they have yields, can_call rules, and condition evaluation.

Configuration

The webhook's address, its header and query rows, and the inbound_token secret are an Add custom record on Studio's Infrastructure page with service type Outbound webhook; connection: names it. Writing the URL, headers or token inline is refused at load. See Connections & the Infra Page.

The simplest seat needs no webhook at all (2.4.486+). agent_type: human with nothing else set is an Inbox seat: its requests appear in Studio's Inbox and work out of the box. Set human_interface: api only when your own code answers the seat (through register_human_agent). A seat left as api that no code answers is answered in the Inbox, and start-up says so by name. Before 2.4.486, such a seat failed on its first question ("No human interface handler set"); on those versions, set human_interface: default for an Inbox seat.

Reaching a Person

2.4.486+. In Studio, how a seat reaches its person is one choice from one list. There is no new YAML key: the choice writes the shapes that already exist, and existing configs load unchanged. Nothing is refused or migrated.

human_interface: api (your own code answers, through register_human_agent) stays available as an advanced option. Left out, human_interface is api; from 2.4.486 a seat with no handler registered is answered in the Inbox.

How It Works

Human agents use a single unified webhook endpoint: POST /webhook/{entry_point}. The same URL handles both new tasks and human responses — routing is automatic based on whether the body contains a session_id matching a paused workflow.

Two Flows, One Endpoint

Flow 1 — External system starts a new task:

Slack/Zapier → POST /webhook/greet_user
Body: {"message": "Hello, I need help"}

LeafMesh: no session_id → looks up entry point "greet_user" → starts workflow
Response: {"status": "accepted", "session_id": "wh_greet_user_..."}

Flow 2 — Human responds to a paused workflow:

Earlier: mesh routed to human agent → sent outbound webhook
         with session_id and context → mesh PAUSED

Now: Human decides and sends response
POST /webhook/greet_user
Header: X-LeafMesh-Signature: sha256=<HMAC-SHA256>
Body: {"session_id": "abc-123", "decision": "approved", "notes": "Looks good"}

LeafMesh: session_id matches paused session → RESUMES workflow
Response: {"status": "resumed", "session_id": "abc-123", "agent": "approver"}

Step-by-Step (Mid-Flow Human Review)

LLM Agent (analyzer, processor, etc.)
    │ can_call → human agent
    ▼
Human Agent triggered
    │
    ├── 1. Outbound webhook POST to the record's address
    │      Payload: session_id, input_data, conversation_history, timeout
    │
    ├── 2. Flow PAUSES — awaiting the human's response
    │      (API returns the upstream agent's result immediately)
    │
    ├── 3. Human reviews data in your system (dashboard, Slack, email)
    │
    ├── 4. Human responds: POST /webhook/{entry_point}
    │      Header: X-LeafMesh-Signature: sha256=<HMAC>
    │      Body: {"session_id": "...", "decision": "approved"}
    │
    ├── 5. LeafMesh verifies HMAC → finds pending session → resumes
    │
    ├── 6. can_call evaluated against human's response
    │      decision == 'approved' → executor
    │      decision == 'rejected' → rejection_handler
    │
    └── 7. If no response within timeout → HUMAN_INPUT_TIMEOUT event

Configuration Fields

Scaling: scaling.copies on a human seat is refused at load (from 2.4.485), with an error naming the seat: it would ask the same person the same thing several times. It can use scaling.runs.max to cap how many of its requests are open at once, counted across all pods. See Agent Configuration → scaling.

Webhook Config Fields

Outbound Webhook Payload

When the flow reaches a human agent, LeafMesh sends this payload to the webhook record's address:

Inbound Response Format

The human's response must include session_id. All other fields are used for can_call condition evaluation:

The response must be signed with HMAC-SHA256:

Inbound webhook requests are signed with LEAFMESH_WEBHOOK_SECRET from the mesh's .env. From 2.4.507 the mesh never derives it; without it, signed webhooks answer 503.

Conversation History in the Payload

Human agents have always shipped the last few conversation turns in the webhook body so the human reviewer has context. Pre-v2.2.1 this was hardcoded to 5 turns. From v2.2.1 onward it's configurable per agent:

Backwards-compatibility note: Human agents that have NOT set receive_conversation_history: true continue to use the legacy 5-turn cap — your existing HITL integrations keep working unchanged. Flip the flag to take advantage of the new history_limit range (1–200).

Both the built-in HITL queue (the in-app Studio panel) and outbound webhook payloads honour the same cap. The Studio "Inputs & Outputs" panel and Playground inspector expose a single toggle for it.

HITL Event Lifecycle

The Manager subscribes to all HITL events. On timeout, it takes configured actions: retry, escalate, fallback, or stop.

Native Channel Adapters

Beyond webhooks, human agents support native channel adapters for messaging platforms. Adapters handle inbound routing, outbound notifications, and session mapping automatically.

Supported today: Slack, Microsoft Teams, Telegram, Zoho Cliq, Email and the hosted Inbox. Discord and WhatsApp are coming.

Slack Adapter

connection: names a credential held in your mesh's own encrypted vault. Nothing secret goes in config — see Connections & the Infra page. A literal token, or an ${ENV_VAR} reference in its place, is refused at load; the connection name may come from the environment (connection: "${SLACK_CONNECTION:slack-workspace}"). Channel records are made under Infrastructure → Messaging (Slack, Microsoft Teams, Telegram, Zoho Cliq; Discord and WhatsApp coming); email under Infrastructure → Workspace → Email.

Channel Configuration

How Inbound Messages Are Routed

Two questions, in this order: is this for us, and which conversation is it.

1. Is the message addressed to the mesh?

A DIRECT message (DM, or mail to the mesh's address)
    └── always ours — no mention needed

A message in a SHARED ROOM
    ├── mentions the mesh, names one of its agents, or is a slash command → ours
    ├── posted inside a thread the mesh opened                            → ours
    └── anything else                                                     → IGNORED

A bare message in a room is people talking to each other. Having spoken to the mesh before does not make later messages its business — otherwise a "yes, go ahead" aimed at a colleague gets read as an answer to a pending request.

The mesh also never answers its own messages, on any channel.

2. Which conversation does it belong to?

Addressed the mesh directly (@mention / named agent / slash command)
    └── a NEW conversation, even if a question is open
        (nobody @-mentions a bot to answer its question — you just type)

A reply inside a thread
    ├── something pending → answers THAT message, in the same session
    └── nothing pending   → runs the flow again, in the SAME session

A new email (no In-Reply-To, no reply token)
    └── a new conversation. A reply stays in its own.

Threads exist on Slack, Teams and Email. Telegram and Cliq have none, so each person has one continuous conversation there — and a question the mesh asks in a Cliq room can only be answered by naming it, or in a DM.

operators_only: true adds a prior gate: anyone not in operators is refused before any of this, including in a DM.

Using Channels with Escalation Targets

Timeout Handling

When the human doesn't respond within human_timeout_seconds:

Timeout strategies:

• Retry: Send the request again to the same reviewer
• Fallback: Use fallback_response values and continue the chain
• Escalate: Route to a different human or Manager escalation target
• Stop: End the chain

When the person is told their reply did not come in time ("No reply within N seconds …"), that notice is posted in the thread of the question it is about — on Slack, Teams and Telegram as on email and the Inbox — not as a new message beside it.

Email Channel

Email is a first-class channel — same model as Slack/Discord/Teams. Inbound mail arrives via a webhook from your email service provider, gets parsed + verified + threaded to a session, and is routed to the human agent. Outbound replies are sent over SMTP.

When to Use

• Customer support inboxes (support@yourcompany.com)
• Approval requests where the reviewer prefers email over a dashboard
• Any case where the counterparty cannot install an app or sign into a portal

Configuration

Add channels.email to a human agent. The full field reference is at Email Channel — ChannelConfig.

A corrected password applies live (2.4.492+). When the email record's SMTP/IMAP username and password, or the provider API key (Mailgun, SendGrid, Postmark), is corrected or rotated in the vault, the running channel uses the new value with no restart. A value written directly in the channel's config is never replaced by the vault.

How Threading Works

The adapter threads inbound replies to the same session as the original conversation using two complementary mechanisms:

1. Standard email headers — In-Reply-To and References are the spec-defined way clients chain replies. The adapter tries these first.
2. Plus-addressing reply token — outbound mail is sent with Reply-To: support+THREAD123@inbound.example.com. When the user replies, the local part support+THREAD123 carries the thread ID even when the client strips reply headers.
3. Subject-token fallback — if subject_prefix is set (e.g. "[#TICKET-{thread_id}]"), the adapter parses the thread ID out of the subject as a last-resort match.

Choose the strategy with the threading field:

• references_first (default) — try headers first, fall back to plus-addressing, then subject token.
• reply_to_token — skip headers, rely solely on plus-addressing. Use this when you don't trust upstream MTAs to preserve headers.

The thread token embedded in Reply-To is sanitized: \r, \n, \x00, and @ are stripped to prevent header injection.

Auto-Reply Filtering

auto_reply_drop: true (default) silently drops:

• Messages with Auto-Submitted: header set to anything other than no
• Messages with Precedence: set to bulk, list, junk, or auto_reply (matches any token in a multi-value header like Precedence: bulk, list)
• Senders matching common no-reply patterns (noreply@, no-reply@, donotreply@, etc.)

This prevents out-of-office replies, mailing list bounces, and vacation responders from creating noise sessions.

Provider Setup

Mailgun

1. Configure an inbound route in Mailgun: match_recipient(".*@inbound.example.com") → forward to https://your-leafmesh.example.com/channels/email/{agent_name}/mailgun/inbound.
2. Get the HTTP webhook signing key from Mailgun → Settings → Webhooks → HTTP webhook signing key. Save it as the signing_secret field of the email record (Infrastructure → Workspace → Email).
3. Inbound requests are verified using Mailgun's signing scheme; stale / replayed requests are rejected.
4. SMTP credentials come from Sending → Domain settings → SMTP credentials; save them on the email record. Use port 587 with STARTTLS.

SendGrid

1. Configure Inbound Parse: domain inbound.example.com → POST URL https://your-leafmesh.example.com/channels/email/{agent_name}/sendgrid/inbound. Enable Check incoming emails for spam but do not enable Send Raw.
2. Generate an ECDSA P-256 verification key (Settings → Mail Settings → Event Webhook → Signed Event Webhook). Paste the public key (PEM, base64) as the email record's signing_secret.
3. Outbound: use SendGrid SMTP relay (smtp.sendgrid.net:587) with API key as the SMTP password and apikey as the username, saved on the email record.

Postmark

1. Create an Inbound stream with the inbound domain. Postmark POSTs to https://your-leafmesh.example.com/channels/email/{agent_name}/postmark/inbound.
2. Verification is HTTP Basic Auth — set the username/password under stream settings and configure the same on your reverse proxy or set signing_secret to the Basic Auth shared secret. Optionally restrict the inbound webhook by IP allowlist (Postmark publishes the source IPs).
3. Postmark's MailboxHash field carries the plus-addressing token (support+THREAD123@inbound.example.com → MailboxHash="THREAD123"). Threading uses this even when DNS routing strips the local part.
4. Outbound: Postmark SMTP (smtp.postmarkapp.com:587) with the server token as both username and password, saved on the email record.

Inbound Attachments (Opt-In)

Attachments are dropped by default. To surface them:

The object-storage address (storage_url, e.g. s3://bucket/prefix) is set on the email record (Infrastructure → Workspace → Email), not in YAML. When enabled, attachments are uploaded there and the agent receives presigned URLs in input_data.attachments — never raw bytes. This caps memory pressure and keeps PII out of agent context windows.

Webhook Endpoint Reference

Request signatures are verified before the body is parsed. Requests that fail verification return 401 and never reach the agent.

Understanding What a Person Meant

A person answers in their own words. "Go ahead", "not this one, it's past the window", a reply in Hindi, a thumbs-up — the mesh never decides what a reply means by looking for particular words. If you give the human agent a model, that model reads the reply:

The model is used for three things:

• Filling the fields your routes read. In the example, it decides whether the reply is a refund or a question — choosing only from the values your conditions name. It never picks the destination itself, and it can never claim a reply came from somewhere it did not.
• Choosing between routes you left open. When several routes have no condition, it picks the one the reply is meant for, using each route's description, instead of sending the reply to all of them.
• Learning from the person's decisions. It reads whether the reply decides something, whether it lets the work go ahead, and why — and keeps that as experience.

There is no default model. Without intent_model, the human agent asks the person which agent they meant whenever a reply cannot be routed on its own; for experience, the model of the agent that asked is used, and if that has none, nothing is filed.

At startup the mesh warns you when the setup cannot work as written — a model that will never be used, routes that need a model to read plain replies, or a reply that would fan out to several agents.

When to Use Human Agents

• Approval workflows (refunds, deployments, access requests)
• Quality review for high-stakes LLM outputs
• Escalation endpoints for critical incidents
• Compliance checkpoints requiring human judgment
• Any decision that should not be fully automated

Next Steps

• Agent Types — All four agent types
• HITL Workflows — Tested approval patterns
• UI Integration — Building review interfaces
• Manager — Escalation — Multi-target escalation

LeafMesh — Human judgment as a first-class mesh node