Customer Agent profile tools

You will learn

What Customer Agent’s profile tools do and how to configure access to them. These tools read or write data on an identified shopper’s Klaviyo profile to personalize responses, answer account-specific questions, and capture new data.

The five profile tools

Customer Agent includes five profile tools. Review their permissions before use: tools can be available directly, only through skills, or blocked. Profile identification and each tool’s configuration requirements still apply.

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

Find these tools in Customer Agent > Connectors. You can also include them in a custom skill when a workflow needs specific instructions.

Before using profile tools

Review permissions in Customer Agent > Connectors. Always allow permits direct use. Only in skills requires the tool to be included in a skill. Blocked prevents use, including through a skill. For writes that need specific policy or consent checks, use Composer to configure a custom skill and appropriate permissions. Test with a test profile before using the workflow with shoppers.

Learn more about tools and permissions.

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 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 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.)

Record custom events from a skill

Use the separate Send Event tool to turn details collected in a conversation into an event on the shopper’s Klaviyo profile. For example, a warranty skill can record a Warranty Claim Started event with the product and reported issue. You can use the metric and its event properties in segments, flows, and reporting. Update Profile Property changes a profile value; Send Event records an activity with properties for that occurrence.

Send Event is in beta and must be available in your account. It requires an authenticated shopper and an existing, active metric in Klaviyo. The metric picker lists existing metrics; it does not create a new one. In web chat, entering an email address in a message alone does not authenticate the shopper.

Configure Send Event

1. Open or create the skill in Customer Agent > Skills. In How to respond, type / and insert Send Event at the point where the event should be recorded. Tell the agent which details to collect before it runs the tool and when it should not record an event.
2. Select the inserted tool to open its configuration. Under Metric, choose the existing metric to record events against.
3. Under Event properties, select Add property for each detail you want to save. Enter a Property name and choose its Source. Keep property names and value formats consistent with the segments and flows that will use them.
   • The agent decides — Choose a Value type (Text, Number, or True or false) and add a Description explaining what the agent should extract from the conversation. For example, use issue_description as Text and describe it as the issue the shopper reported.
   • A fixed value — Enter the Value to send every time this tool runs, such as source = Customer Agent.
   • The customer’s profile — Select a supported Profile field: Klaviyo profile ID, email, phone number, first name, or last name. This selector does not offer arbitrary custom profile properties.
4. Click Save in the tool sidebar and save the skill draft. Review the instructions to ensure the event is recorded only after the necessary information is available.

Example: record a warranty request

Select an existing Warranty Claim Started metric. Add product_name and issue_description with The agent decides as the source and Text as the value type. Add source with A fixed value of Customer Agent. In the skill instructions, tell the agent to collect the product and issue, ask for any missing details, then run Send Event after the shopper confirms the request. Recording the event does not itself create a claim or send a replacement; those actions need their own workflow.

Test and verify the event

Test the skill with a test shopper profile and check both successful and missing-information cases. Treat a Send Event call as a real write: recorded events can trigger flows. Use a test metric or exclude the test profile from production outreach while testing.

In Klaviyo, go to Analytics > Metrics and search for the metric selected in the tool. Open its Activity feed, or open the test shopper’s profile Activity log, and check that the event and property values are correct. Search for your chosen metric name; custom events do not necessarily include “Customer Agent” in their name. Verify the event before making the skill live.

If no event appears, confirm that Send Event is available in your account, the shopper is authenticated, a valid Metric is selected, and the skill instructions reach the inserted tool. Check the tool result before retrying: each successful call records a new event, so repeating the call can create duplicates.

For the built-in events Customer Agent records automatically, see Customer Agent event data reference.

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 Composer to configure the behavior you need. Describe when to read or write profile data and the rules to follow. Composer can adjust tool permissions, draft custom skill instructions, and update guidance for you to review and test. For example: “Use the shopper’s recent cart activity to recommend similar products.”
• 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. 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. To record a custom event during a conversation with an authenticated shopper, use the separate Send Event tool in a Customer Agent skill. Select the metric to write to and configure event properties using model responses, fixed values, or the shopper's profile data.
• 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