---
name: handler
kind: pattern
description: >
  The Handler pattern — one standing agent as the public interface between
  a principal and their private agent fleet. Reference implementation:
  eleven.md.
canonical: https://handler.md/contract.md
reference_implementation: https://eleven.md
updated: 2026-07-11
version: 0.1
---

# handler.md — the Handler pattern

> A **handler** is the standing agent that represents a principal:
> one public entrypoint in front of a private fleet.

## definition

A handler is not a chatbot and not an autoresponder. It is a named,
persistent agent with delegated authority that:

1. **understands intent** — parses what a human or agent actually wants
2. **routes work** — into a private fleet the caller never needs to see
3. **coordinates agents** — tracks the work it dispatched to completion
4. **escalates decisions** — knows the boundary of its delegation
5. **communicates results** — back on the channel the intent arrived on

## the chain

```
principal.md          the human, their identity contract
    ↓ delegates
handler.md            one public agent with authority
    ↓ routes
private fleet         specialists; not all public
    ↓ executes on
runtime               the operating layer (see https://yot.md)
```

## properties of a good handler

- **one entrypoint** — callers address the handler, never the fleet
- **explicit delegation** — the identity contract names its authorized handlers
- **tracked intents** — accepted work completes or is explicitly refused
- **opaque fleet** — capabilities are public, implementation is not
- **honest availability** — no synchronous promises it can't keep

## why not just a chatbot?

A chatbot answers; a handler **owns**. The difference is delegation
(it can act for the principal), persistence (it remembers and tracks),
and refusal (it protects the principal's attention as a first-class duty).

## reference implementation

**Eleven** — https://eleven.md — handler for Laurent Maltais
(https://laurent.md), executing on YOT (https://yot.md).

## use this pattern

Publish your own `handler` contract: a markdown file at a stable URL
declaring who it represents, what it accepts, what it guarantees, and how
to invoke it. If you do, link it from your identity contract the way
laurent.md links eleven.md.

---
version 0.1 · updated 2026-07-11 · part of the yot.md namespace