# Handoff links

Agents running in the cloud carry their operator's name, OpenAI or Anthropic, never their person's. A handoff link fixes that the honest way. When an agent builds a cart, a quote, a configuration or a booking on your site, your server gives it a link to pass on: "send this to your user". When the person opens it, Punchline connects the agent's work to that person's visit and to what they do next, without knowing who they are.


**What gets passed on.** In our tests, agents that built something passed its link on every time (Claude: 18 of 18). Links offered on ordinary pages almost never were: agents give the page's plain address instead (Claude: 0 of 15). So make handoff links for things agents build. [Share links](https://punchlineanalytics.com/docs/edge-markdown#share-links) (no code, with an edge install) still show which assistants fetch which pages for people, but don't count on them to connect visits.

## How it works

1. **The agent builds something.** Your server calls `POST /v1/handoffs` (or `createHandoff` in the SDK) with the kind, the value, the page and the agent's request (its IP address and user agent, used in memory only, so the link is tied to the agent's session).
2. **You hand the agent the link.** The response's `url` is your page with a `pl_ho` token added: `https://shop.example/cart/8431?pl_ho=…`.
3. **A person opens it.** Your edge install or the browser snippet sees the token and Punchline records the open against that visit. If the visit then reaches one of your [goals](https://punchlineanalytics.com/docs/events-goals), the handoff counts as converted.

```ts
import { Punchline } from "@punchline-analytics/sdk";

const punchline = new Punchline({ apiKey: process.env.PUNCHLINE_WRITE_KEY });
const { data } = await punchline.createHandoff({
  site_id: "<your site id>",
  kind: "cart",               // cart, quote, configuration, booking or other
  value: 249,                 // optional: the total
  currency: "USD",
  url: "/cart/8431",          // a path or https URL on your site
  visitor: { ip: agentIp, user_agent: agentUserAgent },
  expires_in_days: 30,        // 1–90
});
// Give data.url to the agent.
```

The key needs the `events:write` scope.

## For B2B sites

In B2B, what an agent builds is rarely a cart. The handoffs worth making:

| What the agent does | Kind | The link the person opens |
|---|---|---|
| Builds a quote or picks a plan and add-ons | `quote` | The saved quote, ready to sign up |
| Holds a demo or sales call | `booking` | A page to confirm the time. Confirming is the conversion. |
| Configures a product (seats, regions, integrations) | `configuration` | The saved configuration |
| Reads your pricing, security or comparison pages | `page` | The page itself, from [share links](https://punchlineanalytics.com/docs/edge-markdown#share-links), no code. Rarely passed on; mostly shows which pages assistants fetched for someone |

Two things make agents finish the job, which matters more than anything else: an agent that never reaches the step that makes the link can't pass it on.

- **One link per action.** Many assistants fetch pages but don't click through multi-step forms. Give each action a URL that does it in one request, like `/quote/save?plan=team&seats=12` or `/book/hold?slot=2026-10-20T15:00`, and have the response show the handoff link.
- **Say where they are.** List those URLs in your `llms.txt` under an *Actions* heading, with their parameters. It's public documentation, like an API reference, not an instruction.

The [demo site](https://agentlens-demo-eight.vercel.app/llms.txt) does both: a quote you can save in one request and a demo call you can hold in one request.

## What you see

**AI & agents → Handoffs:** links given, opened by a person, then converted, with values, per kind and per agent operator. The same numbers are at `GET /v1/handoffs` and in the MCP tool `get_handoffs`. Opened handoffs also count in **Where agents run → Connected, by method**.

## Privacy

- The token is random (24 characters), expires, and carries no personal data. Punchline stores only its SHA-256, never the token.
- Nothing else from the query string is kept: only a well-formed `pl_ho` token is read.
- Visitor hashes on handoffs are cleared after 90 days; the counts stay.