Skip to main content

​
How Set Custom Property works

Use this tool to write a value to a Flywheel user custom property during an agent run. This is useful when the agent determines something you want to persist, such as qualification status, risk level, lifecycle stage, or routing tags. The property update is applied immediately, making the new value available to downstream tools in the same run and to any future agent runs or segments that reference it.

​
Configuration

Inputs

​
Prompt
string
required
Instructions describing when this tool should be used.
​
User
string
required
The target org user ID to update.
​
Custom Property
string
required
The custom property definition to update.
​
Value
string | number | boolean | object
required
The value to set. Type should match the selected custom property.

Outputs

​
success
boolean
required
Whether the update completed successfully.
​
org_user_id
string
required
The user ID whose property was updated.
​
property_name
string
required
The name of the custom property that was set.
​
previous_value
string | number | boolean | object
The value the property held before this update, if any.
​
new_value
string | number | boolean | object
required
The value that was written to the property.

​
Use Cases

Health Score Tagging 
Condition: Trial user missing key activation events
Property: customer_health
Value: "at_risk"
Use: Flag users for proactive retention outreach
Lifecycle Stage Progression 
Condition: Onboarding milestones completed
Property: lifecycle_stage
Value: "activated"
Use: Move user to the activated segment for upsell workflows
Lead Qualification 
Condition: Agent completes qualification flow
Property: lead_score_bucket
Value: "high"
Use: Route high-intent leads to sales-assist agents or CSMs
Routing Tag Assignment 
Condition: User matched to a specific product vertical
Property: routing_tag
Value: "enterprise_data"
Use: Ensure future agent runs and messages are tailored to the user's vertical

​
Best Practices

Property Design
  • Keep property definitions stable and strongly typed to avoid schema drift.
  • Use clear, descriptive naming conventions so downstream reporting is easy to interpret.
  • Define an expected set of values (e.g. enum-like strings) for properties used in segmentation.
Write Discipline
  • Have the agent write derived values intentionally — not on every run unless a re-evaluation is required.
  • Use conditions in the agent prompt to gate writes (e.g. only set customer_health when the score actually changes).
  • Pair property updates with Find Event to base the written value on real activity data.
Downstream Integration
  • Reference updated properties in subsequent tool calls within the same run for consistent decision-making.
  • Use custom properties as segment criteria to trigger other workflows or broadcasts.
  • Audit property change history to understand how agent-driven updates affect user journeys.