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 5 profile tools

These 5 built-in tools read or write data on the authenticated shopper’s profile. You can add them to custom skills. Some tools require you to select inputs when you add them, such as the event type or profile property.

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

To view these tools, navigate to Customer Agent > Connectors, then select Klaviyo. You can add them to a custom skill from the skill editor.

When to use each one

Get Profile

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

Example: “Hi Sarah! I see the address on your profile ends in 1234. Should we use that one again?”

Get Profile also returns where the shopper is: the country Customer Agent detected for the conversation, and the location on their profile. Use it to handle the same request differently by country.

Example: “Call Get Profile to check the shopper’s country. If the country is Canada, explain that orders ship from our Toronto warehouse.”

To limit a whole skill or a piece of content to some countries, use regions instead. See How to set up Customer Agent for multiple countries and regions.

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 did I recently add to 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, or expected next purchase.

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

Predictions are not available for every profile. Tell the skill what to do when predictive data is missing, such as continue without a prediction-based 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

For Update Profile Property, create the custom property in Klaviyo before adding the tool to a skill. For example, set it on a test profile so it is available in the Profile property selector.

1. Navigate to Customer Agent > Skills and open a custom skill, or click Create skill. For a new skill, enter its name and complete When to use this skill.
2. In How to respond, type / and select a profile tool from the Tools menu.
3. If the tool’s configuration sidebar opens, select its required inputs and any optional settings, then click Save. See Configuring a tool when you attach it below. To change these settings later, click the inserted tool in the editor. Repeat steps 2–3 for each tool you need.
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
5. If you are creating a new skill, click Save as draft to save it and open its details.
6. Review your instructions, then click Publish for a draft skill or Update for a live skill. This makes the changes available in live conversations.

Configuring a tool when you attach it

Some profile tools have inputs you can pre-fill for each tool you insert. Pre-filling locks the value in for every call to that instance of the tool, 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 — the maximum number of events to return. Choose 1, 5, 10, 25, or 50. The default is 10. To retrieve the most recent event, select 1 event and Newest first.
• Sort order — Newest first (the default) 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 event, Sort order = Newest first, Lookback window = 30 days. The agent then doesn’t have to think about those choices — they’re baked in.

Update Profile Property requires you to select Profile property. Choose the existing custom property the tool should update, then click Save. In How to respond, tell the agent which values to save and when to save them.

Get Profile Lists and Segments lets you select Membership type to return lists, segments, or both. The default returns both.

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 only if the tool reports success. If it fails, explain that the preference was not saved.

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 dates and available order details recorded in those events. 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 = 5 events, Sort order = Newest first.)

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 select it under Profile property when you configure the tool.
• 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. After the tool reports success, 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 Composer to wire these up. Describe what you want in plain English and Composer will attach the right tools and draft the skill instructions for you to review and publish. For example: "I want my recommendations skill to look at what was in the shopper's cart to recommend something similar."
• Use regions before branching on country. If a whole skill only applies in some countries, set regions on the skill. Use Get Profile when one skill needs a small difference by country.

What these tools don't do

• They don't work on anonymous conversations directly. In web chat, if the agent needs one of these tools and the shopper isn't identified, it prompts the shopper 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 property must already exist in your account to appear in the Profile property selector. Create it in Klaviyo first (e.g., set it on a test profile or via a flow), then select it when you configure the tool. It does not need to already be set on every shopper’s profile.

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?

In web chat, if the agent needs one of these tools and the shopper isn't identified, it prompts the shopper 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. Saving a custom preference with Update Profile Property does not subscribe the shopper to marketing.

Next steps

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

Related articles