Track Personal Agent Protocol traffic in Agent Analytics
このページはまだあなたの言語に翻訳されていません。 現在取り組んでいますので、後でもう一度確認してください。
When a person's personal agent talks to your customer-facing agent over Personal Agent Protocol (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.
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
userto 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_agentto 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.
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.
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
});
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.
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. 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. 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.
Chart recipes
- Quality by personal agent: In Agent Analytics, filter sessions on the
poppy_personal_agentcontext 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_agentset and also contain an[Agent] User Messagewith[Agent] Message Sourceuser. - Agent-driven and human-driven outcome rate: Build a funnel from
[Agent] User MessagetoPoppy Operation Approvedor your own conversion event. Split the first step by[Agent] Message Sourceto comparepersonal_agentwithuser.
For the built-in signals, refer to Agent Analytics built-in signals. For every Message Source value, refer to the Agent Analytics taxonomy.
The authors of Personal Agent Protocol publish the specification. Amplitude isn't affiliated with or endorsed by the protocol's authors.
これは役に立ちましたか?
For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.