Customer Agent profile tools

You will learn

What Customer Agent’s profile tools are, what each one does, and how to use them in skills. These tools let your agent read from and write to a shopper’s Klaviyo profile during a conversation — so it can personalize responses, answer “what’s my…” questions, and capture new data back to the profile.

The five profile tools

Customer Agent comes with five built-in tools that read or write data on the authenticated shopper’s profile. You don’t set them up — they’re available to attach to any skill.

All five resolve the shopper automatically from the conversation context (their email, phone, or profile ID). They only work for identified shoppers.

You can find all five on the Tools page in Customer Agent, and attach them to any skill from the skill editor.

Note: These tools are in beta. They’re available to every brand on Customer Agent — no separate sign-up required — but the feature is still being expanded and may change.

When to use each one

Get Profile

Use when the agent needs to know who it’s talking to — properties like name, email preferences, last shipping address, or any custom property you store.

Example: “Hi Sarah! I see your last order was shipped to the address ending in 1234. Should we use that one again?”

Get Profile Events

Use when the agent needs to know what the shopper has done. Orders, email opens, form submissions, page views, subscriptions — anything tracked as an event on the profile.

Examples:

• A shopper asks “When was my last order?” The skill attaches Get Profile Events with Event type = Placed Order and responds with the date.
• A shopper asks “What was in my cart?” The skill attaches Get Profile Events with Event type = Added to Cart and lists the items back.

You pick the event type and other settings in the tool sidebar when you attach the tool — see Configuring a tool when you attach it below.

Get Profile Lists and Segments

Use when the agent’s behavior should depend on what audiences the shopper is in. VIP customer? Already on the back-in-stock list? Excluded from promo emails?

Example: If the shopper is in the VIP segment, the agent offers a complimentary upgrade on a return.

Get Profile Predictive Summary

Use when the shopper or skill needs Klaviyo’s predictive insights — customer lifetime value, churn risk, expected next purchase, or customer health score.

Example: A retention skill checks churn risk before offering a save discount — high-risk shoppers get a stronger offer.

Update Profile Property

Use when the agent should write something back to the shopper’s profile during a conversation — quiz answers, preferences, feedback, anything you’d otherwise capture in a form.

Examples:

• A shopper answers a quiz: “I prefer earthy scents.” → The agent writes scent_preference: earthy.
• A shopper gives feedback during a return: “It didn’t fit, ran small.” → The agent saves last_return_reason: sizing.

Once a property is on the profile, every other part of Klaviyo can use it — flows, segments, campaigns, future Customer Agent conversations.

How to use these tools in a skill

1. Open the skill you want to update (or create a new one).
2. In the skill editor, attach the profile tools you need.
3. If the tool has configuration inputs, fill them in (see below).
4. In the How to respond section, tell the skill when and how to use each tool. Be specific:
   • When the agent should call the tool
   • What it should do with the result
   • For Update Profile Property: which property to write, what format the value should be in, and when not to write

Configuring a tool when you attach it

Some profile tools have inputs you can pre-fill at the skill level. Pre-filling locks the value in for every call the skill makes, which gives you tighter control and saves the agent from having to figure it out at runtime.

Get Profile Events is the main example. When you attach it to a skill, you can configure:

• Event type (required) — which metric to fetch (e.g., Placed Order, Checkout Started, Added to Cart, Opened Email, Viewed Product).
• Limit — number of recent events to return. Use 1 if you only need the most recent.
• Sort order — newest first or oldest first.
• Lookback window — how far back to search. Default 90 days.

A skill that needs to look at the shopper’s most recent cart, for example, might attach Get Profile Events with Event type = Checkout Started, Limit = 1, Sort order = Newest first, Lookback window = 30 days. The agent then doesn’t have to think about those choices — they’re baked in.

Example “How to respond” snippet (Update Profile Property):

When the shopper tells you their scent preference, call Update Profile Property to save it to the scent_preference property using one of: floral, earthy, citrus, fresh. Only write if the shopper explicitly confirms. Confirm the save back to the shopper in a single sentence.

Example “How to respond” snippet (Get Profile + Get Profile Events):

When the shopper asks about their recent orders, call Get Profile Events to retrieve their order history. Summarize the results with date, item count, and current status. If the shopper asks who they are or what’s on file, use Get Profile.

(Attach Get Profile Events with Event type = Placed Order, Limit = 3, Sort order.)

Tips

• Read before you write. If you're personalizing a response, attach Get Profile or Get Profile Events first. The agent can't reference data it hasn't pulled.
• The property has to exist first, and it has to be a custom property. Update Profile Property only writes to custom profile properties that already exist on your company's profiles. System fields (Email, First Name, phone number, location subfields) and derived fields (Created, First Active, $id) aren't writable. Create the custom property in Klaviyo first, then point the skill at it by exact name.
• Constrain the value set when writing. Spell out allowed values in the skill instructions ("one of: floral, earthy, citrus, fresh"). Otherwise the agent writes free text and your segments won't match.
• Tell the agent when not to write. "Only write if the shopper explicitly confirms" prevents accidental overwrites.
• Confirm writes to the shopper. A short "Got it, I've saved that as your preference" closes the loop.
• Match the tool to the question. "What did I buy?" → Profile Events. "Am I a VIP?" → Lists and Segments. "How likely am I to churn?" → Predictive Summary.
• Use Agent Builder to wire these up. Describe what you want in plain English and Agent Builder will attach the right tools and write the skill instructions for you. For example: "I want my recommendations skill to look at what was in the shopper's cart to recommend something similar."

What these tools don't do

• They don't work on anonymous conversations directly. If the agent wants to call one of these tools and the shopper isn't identified, the shopper is prompted to log in first. Once they're identified, the tool runs.
• Update Profile Property doesn't create new shoppers. The profile must already exist.
• Update Profile Property doesn't write events. Event-writing will be a separate tool — coming soon.
• None of the read tools modify data. They only fetch.

FAQ

Can I write to any property with Update Profile Property?

Only custom profile properties (the ones you define on profiles, like scent_preference or isMom). System fields — Email, First Name, $phone_number, location subfields like $locale_country, and list-patch fields like Viewed Items — aren't writable today. Derived fields the system computes for you (Created, First Active, $id) are read-only permanently.

What if the property doesn't exist yet?

The tool only reads and writes properties that already exist on profiles. Create the property in Klaviyo first (e.g., set it on a test profile or via a flow), then point the skill at it by name.

Can a skill call multiple profile tools in one turn?

Yes. A skill can call any combination of profile tools in a single response — for example, Get Profile and Get Profile Events together to build a fuller picture before responding.

What happens for anonymous shoppers?

If the agent tries to use one of these tools and the shopper isn't identified, the shopper is prompted to log in. Once they're identified, the tool runs and the conversation continues.

Are these tools subject to the same consent rules as the rest of Klaviyo?

Yes. Data flows through Klaviyo's standard profile and consent model.

Next steps

• Understanding Customer Agent tools
• Understanding skills
• How to create a fully custom skill

Related articles