Set Custom Property

Set or update a user custom property from an agent run.

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.