Records — where what the agent collects ends up

An agent that qualifies an enquiry and then leaves it in a transcript has done half a job. Records are the other half: a queue in your dashboard, one entry per thing that needs a person, with the conversation that produced it one click away.

Nothing here needs setting up. When the setup wizard creates an agent it also connects these tools, so a template that says it "hands your team a structured file" now has somewhere to hand it.

What an agent files

A lead or a checklist updates the record for its conversation rather than creating a second one, so an agent that files twice in one chat corrects itself instead of cluttering your queue. A booking and an escalation create one each time, because two of those are two real things.

The reference

Every record gets a short reference — 7K4M-2QP — built from an alphabet with no O/0 and no I/1, because it gets read down a phone and typed back wrong. The agent gives it to your customer so they can ask about it later.

The reference is not an access key. A read is authorised by the identity of the person asking, carried from the conversation, so quoting a reference someone overheard returns nothing.

Using the tools from your own stack

Two interfaces, the same behaviour. Your token is in the dashboard under Tenant & API.

MCP

Already connected for agents the wizard created. To wire it somewhere else, point a streamable_http MCP server at https://agent4.io/api/mcp with an Authorization: Bearer header. Tools: submit_lead, open_checklist, request_booking, escalate, lookup_case, close_case.

HTTP

curl -X POST https://agent4.io/api/tools/records \
  -H "Authorization: Bearer $AGENT4_TOOL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "type": "lead",
        "title": "Sarah — quote for a home policy",
        "summary": "Wants contents cover on a flat she has just bought.",
        "contact": { "name": "Sarah", "phone": "07700 900000" },
        "fields": { "sumInsured": "40000", "startDate": "2026-08-01" }
      }'

{ "reference": "7K4M-2QP", "created": true, "message": "Recorded. The reference is 7K4M-2QP …" }

Close one with PATCH /api/tools/records/{reference} and {"outcome":"quoted"}. Read one with GET /api/tools/records/{reference}, which requires the X-Agent4-End-User of the person the record belongs to.

Fields

title, summary, contact and urgency are the same in every trade — they are what the queue sorts and shows. Everything else goes in fields, and each template declares the keys its trade collects, so telephone is folded onto phone on the way in. A key no template declared is kept rather than dropped; it shows up on the record under "also mentioned".

Being told

A queue nobody is told about is a queue nobody reads, so Notifications sits on the queue itself. Two channels, and you choose per type which ones fire.

Email goes to your sign-in address unless you name another one — the person who pays is rarely the person who works the queue. Out of the box, escalations and booking requests email you and enquiries do not: an inbox that pings for every enquiry gets muted, and that silences the escalation along with it.

Webhook. We POST the record to your URL the moment it is filed:

{
  "event": "record.created",
  "record": {
    "reference": "7K4M-2QP",
    "type": "lead",
    "title": "Sarah — quote for a home policy",
    "summary": "Wants contents cover on a flat she has just bought.",
    "contact": { "name": "Sarah", "phone": "07700 900000" },
    "fields": { "sumInsured": "40000", "startDate": "2026-08-01" },
    "agent": "Front desk"
  },
  "url": "https://agent4.io/dashboard/records/7K4M-2QP"
}

Two headers come with it: X-Agent4-Timestamp, and X-Agent4-Signature — an HMAC-SHA256 of the timestamp, a dot, and the raw body, keyed by the signing secret on the settings page. Verify it and you know the POST is ours rather than someone who learned the URL. The timestamp is inside the signature, so a captured request cannot be replayed at you later.

expected = hmac.new(secret.encode(), f"{ts}.{raw_body}".encode(), hashlib.sha256).hexdigest()
hmac.compare_digest(expected, request.headers["X-Agent4-Signature"])

The URL must be https and reachable from the public internet — an address that only resolves inside your network is rejected when you save it, rather than failing silently every time a record arrives. Send a test from the settings page before you rely on it; it reports what the receiver actually said.

The payload carries the record's contents, contact details included — a webhook that omitted them would not be enough to open a ticket with, which is the thing it exists for. So the endpoint you point this at receives your customers' personal data, and deserves the same care as anywhere else you keep it.

Handing one to a colleague

No second account needed. Switch on a link and send it — on WhatsApp, or as a QR someone scans off your screen. Closing the case switches the link off, so revocation happens as part of finishing the work rather than as something to remember. Switching a link off and on again produces a different link, so "off" genuinely means off for whoever still has the old one.

You can also print a record. A printout has no expiry and cannot be recalled, which is worth a moment's thought before it leaves the building.

Leaving

Export every record as CSV from the queue, any time. If you outgrow this and move to a CRM, the agents keep working — the records are yours and they travel.

What we store, and how

The whole content of a record — the title, the summary, the contact details, the notes — is encrypted at rest. Only what the queue needs in order to sort and filter is in plain columns: the type, the status, the timestamps, and the identifiers that point back at the conversation. None of those identifies a person.

The consequence, deliberately accepted: we cannot search inside your records with a database query. Filtering is by type, status, agent and date.

Records are your customers' personal data, held on your behalf. Delete one, or all of them, from the dashboard; closing your account removes them with it.