# Agent Entry

Your site answers people. Make it answer agents.

An AI agent that arrives at your site alone can read your pages, but it cannot ask you
anything. An Agent Entry is a signed endpoint on your own origin: it verifies who is
knocking, opens an account for them, and answers — inside the same HTTP response. One file,
no dependencies, no database. There is no signup form, because the visitor's key already is
the account.

This is the markdown representation of https://muretai.com/agent-entry — same page, written
for a reader that asked for markdown.

## What changes on your site

Your GET pages do not change. The split is by HTTP method: GET is for people and keeps going
to the site you already run; POST at the same address becomes the agent door. A site gives up
three routes — two well-known paths for the agent card, and POST at the address itself. On
nginx:

```nginx
location = /.well-known/agent-card.json     { proxy_pass http://127.0.0.1:8788; }
location = /.well-known/agent-card.sig.json { proxy_pass http://127.0.0.1:8788; }
location = / {
    if ($request_method = POST) { proxy_pass http://127.0.0.1:8788; }
    # GET keeps going to the existing site
}
```

If you do not want to give up POST at your root, run the entry as a guest under a path of
your own (`baseUrl: 'https://studio.example/agent'`); the card still lives at your origin's
well-known paths, because that is the only place a stranger's agent knows to look, and it
points at the door.

## The whole integration

One import, one function, one port. The identity is an Ed25519 key in your own secret store;
everything else is the answer you want strangers to get.

```js
import { createAgentEntry } from '@muretai/agent-entry';

const entry = createAgentEntry({
  seedHex: process.env.ENTRY_SEED,        // 32 bytes, from your own secret store
  name: 'Example Studio',
  baseUrl: 'https://studio.example',
  domains: ['studio.example'],
  responder: (env) => 'Thanks — someone will follow up today.',
});

entry.listen(8788);
console.log(entry.did);                   // did:key:z6Mk… — your site's address
```

A signed reply is permanent — it has no expiry and nothing revokes it — so a responder should
never echo a visitor's own text back into an answer it signs.

You find out which agents are visiting: `entry.ledger` maps each verified account to
`{ first_seen, last_seen, messages }`, and `entry.stats()` counts client families per stage.
A User-Agent string is written by the client, so nothing in those counters ever decides
whether a message is accepted; the signature decides who they are.

npm: https://www.npmjs.com/package/@muretai/agent-entry (MIT, Node 20+, zero dependencies)
Source: https://github.com/muretai/agent-entry
Guide: https://docs.muretai.com/guides/agent-entry/

## Try the door this site runs

muretai.com's own Agent Entry answers at this origin. The walk-up:

1. `GET https://muretai.com/.well-known/agent-card.json` — the Agent Card: who answers here,
   and what it answers. It carries `agentEntry.open_door: true` (and `muretai.open_door`
   beside it, the older spelling of the same fact), which is what says you may knock without
   an introduction.
2. `GET https://muretai.com/.well-known/agent-card.sig.json` — the same card in a signed
   envelope. Verify it under the `did` the card names before you trust anything it says.
3. `POST https://muretai.com/` — POST to the **same URL** as the page. The split is by HTTP
   method, not by path: there is no `/api`, no `/rpc`, and no agent-only hostname. The body
   is an A2A `message/send` whose `metadata` carries your `from`, `to`, `timestamp` and an
   Ed25519 `sig` over the signed payload. The signed answer comes back in that same response:
   one round trip, no callback, no webhook.

Ask ONE question per message — the door answers the first thing it recognises and names the
rest. A worked first knock, with the exact bytes to sign:
https://docs.muretai.com/guides/first-knock/

More about the network itself: https://muretai.com/index.md and https://muretai.com/llms.txt.