# Install a Somebody agent: instructions for coding agents

You are a coding agent (Claude Code, Codex, Cursor or similar) adding a Somebody agent to a
website. Somebody agents are live AI agents with a face and a voice. The face is rendered in the
visitor's browser; there is no video stream to host.

Follow the steps in order. Do not invent attributes, events or endpoints that are not listed here.
If you need something this file does not cover, tell the person and point them to
https://somebodyai.co/developers.

## 1. Get the agent ID from the person

You cannot create the agent yourself. Ask the person for their **agent ID**. If they do not have
one:

1. They sign up free at https://app.somebodyai.co/signup (the Free plan includes website embedding).
2. They create an agent: pick an agent type, an avatar and a voice, and describe what it should do.
3. They open the agent, click **Share**, then **Embed**, then **Code**, and copy the agent ID from
   the snippet.

Never guess an ID. Never commit provider API keys (OpenAI, Gemini, Azure) to the site: those are
added in the Somebody app under Credentials, not in the page.

## 2. Find where the snippet belongs

Find the file that renders the closing `</body>` for every page the agent should appear on:

| Stack | Usual location |
|---|---|
| Plain HTML | each page, or the shared footer include |
| Next.js (app router) | `app/layout.tsx`, with `next/script` and `strategy="afterInteractive"` |
| Next.js (pages router) | `pages/_app.tsx` or `pages/_document.tsx` |
| Astro | the shared layout in `src/layouts/` |
| Nuxt | `app.vue`, or `useHead({ script: [...] })` |
| SvelteKit | `src/app.html` |
| Remix / React Router | `app/root.tsx` |
| WordPress | theme footer, or a "header and footer scripts" plugin |
| Shopify theme | `layout/theme.liquid` |

If the agent should appear on some pages only, add it to those pages' layout instead.

## 3. Add the embed

Pick one form. Keep the agent ID in an environment variable or site config if the project has one.

**Script tag**: adds a launcher to the page. Use this unless the person asks for a fixed position.

```html
<script
  src="https://embed.somebodyai.co/embed.js"
  data-agent-id="YOUR_AGENT_ID"
  async></script>
```

**Web component**: places the agent exactly where the element sits in the layout.

```html
<somebody-agent agent-id="YOUR_AGENT_ID"></somebody-agent>
<script src="https://embed.somebodyai.co/embed.js" async></script>
```

**JavaScript API**: when the page needs to control the agent or react to it. `embed.js` defines
`window.SomebodyAgent` once it has loaded.

```js
const agent = SomebodyAgent.mount({
  agentId: 'YOUR_AGENT_ID',
  target: '#concierge', // CSS selector of the element to mount into
});

agent.on('avatar.ready', () => { /* the face is on screen */ });
agent.on('session.started', () => { /* a conversation began */ });

agent.start(); // begin a conversation, e.g. from your own button
agent.end();   // end it
```

An **iframe** form exists for site builders that block scripts. Its code is specific to the agent:
ask the person to copy it from **Share > Embed > Code > Iframe** in the app.

Load `embed.js` once per page. In a single-page app, mount once in the root layout so the
conversation survives client-side navigation.

### If the agent's share link is off

Each agent has a setting in the app under **Share > Access keys**: **Anyone with the link can talk
to this agent**. While it is on, the snippets above work on any site. Agents created in the app
start with it on; agents created through the REST API start with it off.

While it is off, an agent ID alone starts nothing: the player says the agent isn't shared. Use one
of these instead, and ask the person which one they want:

- **The agent's own publishable key**, locked to the site's origins. The person creates it under
  **Share > Access keys** and gives you the key. It needs the JavaScript API: add
  `playbackKey: 'pk_...'` to `mount()`.
- **A session credential from the site's server.** The server calls the REST API with the
  organization's secret API key when a visitor is about to talk, and the page passes the result to
  `mount()`:

  ```http
  POST https://api.somebodyai.co/api/v1/agents/YOUR_AGENT_ID/session-credentials
  Authorization: Bearer YOUR_SECRET_API_KEY
  ```

  The answer is `{ "token": "...", "expiresIn": 600 }`. The credential covers this one agent for
  ten minutes. Pass a function so the player can ask for a fresh one each time it connects:

  ```js
  SomebodyAgent.mount({
    agentId: 'YOUR_AGENT_ID',
    target: '#concierge',
    sessionCredential: async () => {
      const res = await fetch('/api/somebody-credential', { method: 'POST' }); // your endpoint
      return (await res.json()).token;
    },
  });
  ```

  The secret API key stays on the server. Never put it in the page, and never commit it.

## 4. Do not restyle it from the page

Placement (launcher, inline, modal, full page), corner, skin, colours, greeting, captions and
which page actions the agent may take are set in the app under **Share > Embed** and are picked up
by the snippet already on the site. Send the person there instead of adding CSS overrides.

Two page-level switches are safe to set in markup:

- `data-embed-placement="launcher"` (or `inline`) to override the saved placement on this page.
- `data-actions="off"` to stop the agent acting on this page (navigating, highlighting, filling
  forms), whatever the agent's own setting.

An attribute the loader does not recognise is ignored with a console warning that starts
`[somebody] snippet attribute`.

## 5. Content Security Policy

If the site sends a CSP, allow:

- `script-src https://embed.somebodyai.co`
- `frame-src https://embed.somebodyai.co`
- `connect-src https://api.somebodyai.co`

The microphone prompt comes from the player when the visitor starts talking. If the site sets a
`Permissions-Policy` header, it must not block `microphone` for `https://embed.somebodyai.co`.

## 6. Verify

1. Run the site locally and open a page with the snippet.
2. The agent's face should appear (launcher in the corner, or in the target element).
3. Open the browser console. There should be no `[somebody]` warnings and no CSP errors.
4. Tell the person to click the agent and say hello. A real conversation uses their plan's minutes;
   an agent that is only waiting on the page uses none.

If the face does not appear: check the agent ID, check the console for CSP errors, and check that
`embed.js` was not removed by a consent manager or script blocker.

## 7. Report back

Tell the person which file you changed, which embed form you used, and that appearance and
behaviour are edited in the app, not in code.

## More

- Developer overview: https://somebodyai.co/developers
- REST API (paid plans), publishable and secret keys: created in the app under **Access keys**
- Putting a face on an existing ElevenLabs agent: https://somebodyai.co/developers#elevenlabs
