User profiles

When one agent serves many people, it needs to know who it is talking to: their name, language, time zone, plan, and what it learned about them last time. User profiles hold that once, so you do not rebuild it into every session’s first message.

What a profile holds

Using a profile

{
  "agent_id": "agt_01JC4R8W6Q2N9X3T5V7Y",
  "user_profile_id": "ext:cust-4821",
  "input": [{ "type": "user.message", "content": "Where is my replacement?" }]
}

The agent receives the profile as a short block in its context, after its own instructions:

<user_profile>
name: Dana Lee
locale: en-GB · timezone: Europe/London (now 10:00, Thursday)
plan: gold · region: uk-south
</user_profile>

Setting user_profile_id also sets the session’s memory_scope unless you pass one explicitly.

Privacy

• Attributes are shown to the model, so do not store secrets in them.
• Delete a profile with delete_memories=true to erase everything the agents remembered about the person.
• Profiles respect zero data retention: in ZDR organizations, profiles hold only external_id, locale and timezone.

Keeping profiles current

Update profiles from your own system when facts change (plan upgrades, address moves) with Update a profile. Running sessions see the new values at their next turn.