---
title: Track Personal Agent Protocol traffic in Agent Analytics
description: "Record whether a person or an AI wrote each message when a personal agent talks to your customer-facing agent over Personal Agent Protocol, so human-experience metrics stay clean and you can compare personal agents by outcome."
product: general
lang: en
last_updated: 2026-11-20
token_estimate: 3022
---
# Track Personal Agent Protocol traffic in Agent Analytics

When a person's personal agent talks to your customer-facing agent over [Personal Agent Protocol](https://personalagentprotocol.org) (Poppy), Agent Analytics records who wrote each message on each side: the person or an AI on their behalf, and your agent or a person at your company. Set `[Agent] Message Source` from the Poppy message author and add two context properties from the Poppy Session. Your human-experience metrics then stay clean, you can tune your agent for both audiences, and you can see which personal agents complete real outcomes and when the person steps in.

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

Use this page when your company runs its own agent that personal agents talk to. Your agent is the one Agent Analytics evaluates. The personal agent is a channel into it, like chat or voice. If personal agents reach you only through your APIs or website, with no agent of yours in the conversation, track that traffic as ordinary product analytics events instead.

## Who's who

| Party | In Poppy | In Agent Analytics |
| --- | --- | --- |
| Your agent | The Company Agent | The agent you instrument and evaluate, identified by `[Agent] Agent ID` |
| The person | The User | `device_id` before sign-in, `user_id` after, and User Message events with Message Source `user` |
| The person's personal agent | The Personal Agent, identified by its `client_id` URL | User Message events with Message Source `personal_agent`, and the `poppy_personal_agent` context property |
| A person at your company | `responder` set to `human` after a handoff | AI Response events with Message Source `human_agent` |

## What you can measure

- **Human-experience metrics without agent noise**: Filter to Message Source `user` to measure what people themselves write, such as friction and negative feedback, without text an AI wrote.
- **Quality for each audience**: Agent Analytics counts every personal agent message as a turn and runs built-in signals on every user turn. Break signals down by `poppy_personal_agent` to compare agent-driven and human-driven sessions, and tune your agent for both.
- **Personal agents that complete outcomes**: Join Poppy funnel events, such as sign-in and approved operations, to the session to see which personal agents finish real tasks.
- **When the person steps in**: Find sessions where a personal agent started and the person then wrote a message themselves.

## Field mapping

Your agent verifies the `Poppy-Session` header before it relies on any Session claim (spec section 5.3). Amplitude never verifies the header. Map only claims you've already verified.

| Poppy source | Agent Analytics field |
| --- | --- |
| Message `author.type` of `human` (spec section 8.8) | `[Agent] Message Source` = `user` on `[Agent] User Message` |
| Message `author.type` of `agent` (spec section 8.8) | `[Agent] Message Source` = `personal_agent` on `[Agent] User Message` |
| A reply a person at your company wrote, after a handoff (spec section 8.9) | `[Agent] Message Source` = `human_agent` on `[Agent] AI Response` |
| Conversation ID, which your company chooses (spec section 8.2) | `[Agent] Session ID`. Use the ID your chat system already uses for the conversation. |
| Session JWT `sid` | `poppy_session_id` in `[Agent] Context` |
| Session JWT `sub`, the pairwise User ID (spec section 5.1) | With `iss`: `device_id` = `poppy-sha256:` followed by the SHA-256 hex of `iss` and `sub`, on every event |
| The account's user ID, after the person signs in | `user_id` |
| Session JWT `iss`, the personal agent's `client_id` URL | `poppy_personal_agent` in `[Agent] Context` |
| Session JWT `agent_id`, when present | `poppy_agent_id` in `[Agent] Context` |

A Poppy Session isn't a conversation. It covers one person's browsing, API calls, and conversations through one personal agent, and a conversation can continue in a new Session (spec section 5.5). Key Agent Analytics sessions on the Conversation ID so each conversation stays one session, and keep the `sid` in context to join the conversation to the rest of the Poppy Session.

A summary, paraphrase, or translation of what the person said arrives as `author.type` `agent`, so it records as `personal_agent`. Only the person's own words record as `user`.

`[Agent] Message Source` value `agent` means something else: a parent agent in your own system instructing a child agent. The AI SDK provider wrappers set it automatically from the parent agent ID. Don't use it for personal agent messages. Refer to [Instrument multi-agent systems](https://amplitude.com/docs/amplitude-ai/agent-analytics/multi-agent).

## Set up with the AI SDK

Pass the message source and context on each tracked event. The option is `messageSource` in Node and `message_source` in Python. The step-by-step guide, with verification, is the [Personal Agent Protocol integration guide](https://github.com/amplitude/Amplitude-AI-Node/blob/main/docs/integrations/personal-agent-protocol.md).

#### Node

```typescript
import { createHash } from 'node:crypto';

// claims: the verified Session JWT claims. conversationId: the Conversation ID
// in the request URL. msg: the incoming Poppy message.
const context = {
  poppy_personal_agent: claims.iss,
  poppy_session_id: claims.sid,
  ...(claims.agent_id ? { poppy_agent_id: claims.agent_id } : {}),
};

await agent
  .session({
    sessionId: conversationId,
    // sub is unique only within one personal agent, so include iss.
    deviceId: `poppy-sha256:${createHash('sha256').update(`${claims.iss}\n${claims.sub}`).digest('hex')}`,
    userId: accountUserId, // null until the person signs in
  })
  .run(async (s) => {
    s.trackUserMessage(msg.text, {
      messageSource: msg.author.type === 'human' ? 'user' : 'personal_agent',
      context,
    });
    // ... call the model, then track the reply with the same context
  });
```

#### Python

```python
import hashlib

# claims: the verified Session JWT claims. conversation_id: the Conversation ID
# in the request URL. msg: the incoming Poppy message.
context = {"poppy_personal_agent": claims["iss"], "poppy_session_id": claims["sid"]}
if claims.get("agent_id"):
    context["poppy_agent_id"] = claims["agent_id"]

with agent.session(
    session_id=conversation_id,
    # sub is unique only within one personal agent, so include iss.
    device_id="poppy-sha256:" + hashlib.sha256(f"{claims['iss']}\n{claims['sub']}".encode()).hexdigest(),
    user_id=account_user_id,  # None until the person signs in
) as s:
    s.track_user_message(
        msg["text"],
        message_source="user" if msg["author"]["type"] == "human" else "personal_agent",
        context=context,
    )
    # ... call the model, then track the reply with the same context
```

The context properties land in `[Agent] Context`, and Amplitude echoes them onto the Session Record. Filter on them in Agent Analytics with the existing context filters.

When a person at your company takes over the conversation, send their replies as `[Agent] AI Response` events with `[Agent] Message Source` set to `human_agent`, through the HTTP API or your help desk integration. Refer to [Send agent events without the AI SDK](https://amplitude.com/docs/amplitude-ai/agent-analytics/instrument-http-api).

## Link sign-in to the account

Send a `user_id` or a `device_id` on every event. Without either, the session shows as `unknown` and can't join to product analytics.

Before the person signs in, you don't have a product user ID, only the pairwise `sub` (spec section 5.1). The personal agent assigns it. It contains no personal information, it's different for each company, and it stays the same each time the person returns to yours through the same personal agent. It's unique only within that personal agent, so two personal agents can send the same `sub` for different people, and the `device_id` must combine `iss` and `sub`. You choose the format. The examples use `poppy-sha256:` followed by the SHA-256 hex of `iss`, a newline, and `sub`. Leave `user_id` empty until the person signs in. Repeat visits through the same personal agent then group under one anonymous user. A personal agent can also send a new `sub` for each anonymous browsing session, and those visits don't group.

When the person signs in through Poppy, keep the same `device_id` and set `user_id` to the user ID your product analytics uses. Amplitude merges the anonymous events from that device ID into the user. Refer to [Merged users](https://amplitude.com/docs/data/sources/instrument-track-unique-users#merged-users). Don't send the `sub` as the `user_id`, because Amplitude doesn't merge two different user IDs automatically.

## Track funnel events

Send the Poppy steps outside the conversation as regular Amplitude analytics events, from your server with any Amplitude SDK or the HTTP API. These names are recommendations:

| Event | When to send it |
| --- | --- |
| `Poppy Sign In Completed` | The person finishes signing in through the personal agent. |
| `Poppy Scope Granted` | The person approves access scopes for the personal agent. |
| `Poppy Browser Joined` | The personal agent's browser joins the Poppy Session on your website. |
| `Poppy Operation Approved` | The person approves an operation the personal agent asked to run. |

Send them with the same `device_id`, and after sign-in the same `user_id`, as the agent events, with the event properties `poppy_session_id`, set to the `sid`, and `poppy_personal_agent`. These match the context keys on the agent events. You can then build funnels from agent turns to approved operations and split them by personal agent.

## Join website activity

When a browser joins a Poppy Session on your website, add the event property `poppy_session_id` to the events you track there with the [Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2/instrument-and-configure). The browser has its own device ID, so until the person signs in, its events join the agent sessions and funnel events by `poppy_session_id`. After sign-in, set the same user ID in the Browser SDK as on the agent events.

## Send OpenTelemetry traces

If your agent sends OpenTelemetry traces, set `session.id` to the Conversation ID, `amplitude.device_id` to the same device ID as the SDK examples, and `enduser.id` to the account's user ID only after the person signs in. The receiver maps all three. To record the message source, set `amplitude.message.source` to `user` or `personal_agent` on the span. The receiver doesn't map `[Agent] Context`, so filtering on `poppy_personal_agent` requires the Amplitude AI SDK, including its OpenTelemetry exporter. Refer to [OpenTelemetry attribute reference](https://amplitude.com/docs/amplitude-ai/agent-analytics/otlp-reference).

## Chart recipes

- **Quality by personal agent**: In Agent Analytics, filter sessions on the `poppy_personal_agent` context property and compare Task Completed, Response Quality, and User Friction across personal agents, and against sessions without one.
- **Person stepped in**: Count sessions that have `poppy_personal_agent` set and also contain an `[Agent] User Message` with `[Agent] Message Source` `user`.
- **Agent-driven and human-driven outcome rate**: Build a funnel from `[Agent] User Message` to `Poppy Operation Approved` or your own conversion event. Split the first step by `[Agent] Message Source` to compare `personal_agent` with `user`.

For the built-in signals, refer to [Agent Analytics built-in signals](https://amplitude.com/docs/amplitude-ai/agent-analytics/signals). For every Message Source value, refer to the [Agent Analytics taxonomy](https://amplitude.com/docs/amplitude-ai/agent-analytics/taxonomy#common-properties).

The authors of Personal Agent Protocol publish the [specification](https://personalagentprotocol.org/docs/1.0/spec). Amplitude isn't affiliated with or endorsed by the protocol's authors.

