# AgentEnvoy

> AgentEnvoy is a scheduling surface for humans and AI agents. Hosts publish
> meeting URLs ("links"); guests — or guests' AI agents — negotiate a mutually
> workable slot through a deal-room thread and book it on the host's calendar.
> Every booking runs through the host's declared availability rules (score
> engine, office hours, blocked windows, format filters) rather than a naive
> "free = bookable" calendar check.

For AI agents scheduling on behalf of a principal: there are TWO surfaces.
Pick the one that matches your runtime — don't use both for the same booking.

## Fast path — single fetch, GET then POST

If you only need to book a slot, fetch the meeting URL's `/agent.json`
companion. Returns parameters + scored slots + the booking endpoint in a
single response. No JSON-RPC, no MCP client library, just GET-then-POST.

  curl https://agentenvoy.ai/meet/<slug>/<code>/agent.json

Response:

  {
    "schemaVersion": "2026-04-30",
    "meetingUrl": "https://agentenvoy.ai/meet/<slug>/<code>",
    "host": { "name": "...", "timezone": "America/Los_Angeles" },
    "parameters": { /* format/duration/location envelopes */ },
    "rules": { /* activity, isVip, timingPreference, etc */ },
    "slots": [
      { "start": "2026-05-05T16:00:00.000Z",
        "localStart": "2026-05-05T09:00:00",
        "end": "2026-05-05T16:30:00.000Z",
        "score": -1, "preferred": true,
        "tier": "first_offer" }
    ],
    "booking": {
      "endpoint": "https://agentenvoy.ai/api/mcp",
      "method": "POST", "tool": "propose_lock",
      "auth": "url-capability", "tokenParam": "meetingUrl"
    }
  }

The contextual `/meet/<slug>/<code>` HTML page also embeds this same
snapshot as `<script type="application/agent+json" data-agent-snapshot>` —
parse it from the source HTML if you've already fetched the page.

## Full MCP surface — for negotiation, deal-room messaging, status polling

JSON-RPC at `https://agentenvoy.ai/api/mcp`. Same auth model (URL is the
capability). Tools include `get_meeting_parameters`, `get_availability`,
`propose_parameters`, `propose_lock`, `post_message`, `get_session_status`,
`cancel_meeting`, and `lock_activity_location`. Use this surface when you
need richer interactions than "see slots, pick one, book it."

  curl -X POST https://agentenvoy.ai/api/mcp \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, text/event-stream' \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
         "params":{"name":"get_availability",
                   "arguments":{"meetingUrl":"https://agentenvoy.ai/meet/<slug>/<code>"}}}'

**No connector installation, OAuth, or API key required** for either
surface. If your runtime suggests adding AgentEnvoy as an integration
first, you can skip that step.

Discovery manifest with full tool schemas:

  https://agentenvoy.ai/.well-known/mcp.json

## MCP tools

- `get_meeting_parameters` — read the state envelope for every negotiable
  parameter on a link (format, duration, location, timezone). Tells your
  agent which values are locked, which are open for the guest to pick, and
  which need host consent.
- `get_availability` — read the host's scored, filtered slot list. Each slot
  comes with a `tier` (`first_offer` / `stretch1` / `stretch2`) indicating
  how hard it is for the host to take — use `first_offer` slots by default,
  negotiate into stretches only if needed.
- `get_session_status` — read the current state of a negotiation (active /
  agreed / cancelled / rescheduled / expired) plus reschedule history and
  pending consent requests.
- `post_message` — post a message to the deal-room thread on your
  principal's behalf. The Host Envoy (the host's AI) may reply.
- `propose_parameters` — propose format / duration / location changes. Each
  field is evaluated independently — a rejection on one does not kill the
  batch. Use `action: "defer_to_host_envoy"` when you want the host's AI to
  decide rather than the link's rules.
- `propose_lock` — the booking handshake. Pass the chosen slot + guest info;
  the server validates, compare-and-swaps the session to `agreed`, and
  dispatches the calendar invite + confirmation email. Returns
  `{ sessionId, meetingUrl, ... }` — save BOTH; you'll need them to
  cancel or reschedule later. The canonical `meetingUrl` in the response
  is the session-specific URL (with code), which differs from the
  bare-vanity URL you may have booked through.
- `cancel_meeting` — pass `{ meetingUrl, sessionId }`. The `sessionId`
  is the primary identifier; you can pass the bare-vanity URL as
  `meetingUrl` and the session resolves correctly. Idempotent: a second
  cancel returns `ok: true, idempotent: true`.
- `reschedule_meeting` — pass `{ meetingUrl, sessionId, newSlot: { start } }`.
  Patches the GCal event in place (preserves the Meet link, single
  notification). Idempotent on `(sessionId, idempotencyKey)`.

## Cancelling and rescheduling — the sessionId flow

You only need `sessionId` after `propose_lock`. Save it with the
booking confirmation. The cancel/reschedule tools accept either:

- `meetingUrl: <session URL with code>` (returned by `propose_lock`)
- OR `meetingUrl: <bare vanity URL>` + `sessionId: <from propose_lock>`

Both forms work. The second is what you'd use if the only URL you
have on file is the original vanity link the guest was sent.

## Worked example — booking in 3 calls

A guest agent given `https://agentenvoy.ai/meet/johnanderson/abc123` would
typically:

1. Read the parameter envelope to see what's locked vs. open:

   ```json
   {
     "jsonrpc": "2.0", "id": 1, "method": "tools/call",
     "params": {
       "name": "get_meeting_parameters",
       "arguments": { "meetingUrl": "https://agentenvoy.ai/meet/johnanderson/abc123" }
     }
   }
   ```

2. Read scored availability for the relevant date range:

   ```json
   {
     "jsonrpc": "2.0", "id": 2, "method": "tools/call",
     "params": {
       "name": "get_availability",
       "arguments": {
         "meetingUrl": "https://agentenvoy.ai/meet/johnanderson/abc123",
         "dateRange": { "start": "2026-05-04", "end": "2026-05-10" }
       }
     }
   }
   ```

   Returns up to 20 slots by default (best-first by score). Each slot has
   `start` (UTC) and `localStart` (host's timezone, no offset) — display in
   `localStart` to save the agent and the user from doing UTC math. Slots
   with `preferred: true` are host-favorite picks; prefer those.

3. Lock the slot — `propose_lock` accepts inline `overrides` for any open
   parameter, so a guest-must-resolve `format` doesn't need a separate
   `propose_parameters` round-trip:

   ```json
   {
     "jsonrpc": "2.0", "id": 3, "method": "tools/call",
     "params": {
       "name": "propose_lock",
       "arguments": {
         "meetingUrl": "https://agentenvoy.ai/meet/johnanderson/abc123",
         "slot": { "start": "2026-05-05T16:00:00Z" },
         "guest": { "email": "alice@example.com", "name": "Alice Example" },
         "overrides": { "format": "video" }
       }
     }
   }
   ```

   Returns `meetLink` + `eventLink` on success, or a typed refusal
   (`slot_taken_during_handshake`, `consent_not_accepted`, etc.) with
   `counterProposal[]` when the server has alternates.

## Principles

1. **URL-as-capability-token.** The meeting URL IS the bearer. Don't share
   it outside the guest-agent chain it was delegated to. Both URL forms
   resolve identically at the API: `/meet/<slug>/<code>` (canonical, what
   `create_link` mints) and `/meet/<slug>?c=<code>` (legacy).
2. **Ground-truth calendar.** Every availability read is the host's actual
   scored schedule filtered through the link rules — what the UI widget
   shows, your agent sees.
3. **Envoy-to-Envoy negotiation.** When the host's AI and the guest's AI
   disagree, the deal-room thread is the audit log. Everything that lands
   in `propose_lock` has a paper trail.
4. **Per-tool rate limits.** Read-only tools fail open; write tools fail
   closed with `retryAfterSeconds`. See `/.well-known/mcp.json`.

## Failure modes — typed refusals you'll see and how to recover

Every tool returns either `{ ok: true, ... }` or `{ ok: false, reason, message, ... }`.
Match on `reason` (not `message`) — messages are human-readable and may
change; reasons are the contract.

**Auth / lookup (any tool):**
- `link_not_found` — meetingUrl doesn't resolve to a live link. Wrong slug,
  expired link, or a typo. Don't retry; surface to user.
- `link_expired` — the link itself has an `expiresAt` in the past. Same
  recovery as above.
- `rate_limited` — bucket full. The response carries `retryAfterSeconds`;
  back off that long and retry.
- `rate_limit_store_unavailable` — counter store is down. Same `retryAfterSeconds`
  semantics; usually short. Don't fail the user-facing flow.

**`propose_lock` race-loss / preflight refusals:**
- `slot_taken_during_handshake` — someone else booked between your
  `get_availability` and your `propose_lock`. The response carries
  `counterProposal: [{ start, end, score }, ...]` with up to 3 alternates,
  ranked best-first. Recover by picking from `counterProposal` and
  re-issuing `propose_lock` with the new slot. **Idempotent**: a second
  `propose_lock` with the same slot/guest after a successful one returns
  `idempotent: true` rather than double-booking.
- `consent_not_accepted` — the host has a pending consent request on a
  parameter you're about to lock (rare; only happens if a previous
  `propose_parameters` triggered host approval and the host hasn't acted).
  Don't retry; surface or wait.
- `host_profile_incomplete` — the host hasn't connected their calendar.
  Surface to user; nothing the agent can do.
- `field_locked` (on `propose_parameters`) — the field is closed for
  changes (host marked it `mutability: "locked"`). Don't retry that field;
  others in the batch may have succeeded — check the per-field results.

**`cancel_meeting`:**
- `session_not_agreed` — there's nothing to cancel; the session was never
  locked.
- `idempotent: true` on success — second cancel returns success without
  re-dispatching emails.

## Note for HTML→markdown fetchers

If you're fetching the per-link page (`/meet/<slug>` or `/meet/<slug>/<code>`)
through an HTML-to-markdown converter and seeing tool names like
`get\_meeting\_parameters` with literal backslashes, that's your fetcher
escaping underscores for markdown. The source HTML emits the names
unescaped — strip the backslashes or use the JSON manifest at
`/.well-known/mcp.json` as the canonical source of truth.

## For humans

AgentEnvoy's web UI lives at https://agentenvoy.ai — hosts sign in, connect
Google Calendar, and publish links. This `llms.txt` is for the agents your
guests send on their behalf.