EmployeeBenefitsFlow tutorial
1. A twenty-two-turn live replay
Start with a completed model-backed enrollment: eligibility, exact plans, recoverable corrections, review, and deterministic submission.
Read this first. The 22 responses below were captured from a successful live EmployeeBenefitsFlow run with the test clock frozen to 2026-11-05. This is a fictional benefits demonstration; all employee and dependent names are test fixtures.
Collection language can vary on another run. Eligibility, plan terms, provider lookup, contribution limits, beneficiary totals, payroll costs, pending requirements, and the final enrollment record are code-owned assertions.
Run it yourself
From the demo repository, with OPENAI_API_KEY and PICOFLOW_KEY configured:
- 1
- 2
cd pico-demo
npm run test:employee-benefits-flow
The test sends all 22 requests to POST /ai/run with one durable session ID, semantically evaluates every response, and reads the final SQLite session document. It verifies the selected HDHP, corrected $5,500 HSA election, ancillary choices, 100% beneficiary allocation, $3,000 dependent-care election, pending evidence-of-insurability requirement, and completed status.
For a fast provider-free check of the same policy rules:
The live scenario uses credentials from .env and is skipped when they are unavailable.
Captured live transcript
-
1 · enrollment scope and identity prompt
You
Hi, I need to enroll in my employee benefits.
Bot
Welcome to your fictional 2027 benefits enrollment demonstration! Let’s start by gathering some information:
- Can you please provide your Employee ID in the format
E-0000?
- What plan year are you enrolling for?
- What type of enrollment event is this? Is it
open_enrollment, new_hire, or a qualifying_life_event?
- If it’s a new-hire or qualifying-life event, what is the event date in
YYYY-MM-DD format? (If it’s open enrollment, we’ll set the event date to null.)
Once you provide this information, we’ll proceed to check your eligibility.
-
2 · eligibility and household tier prompt
You
My employee ID is E-1042. This is 2027 open enrollment.
Bot
Great! Let’s determine the coverage tier for your benefits. Please let me know which coverage tier you’d like to enroll in:
employee_only
employee_spouse
employee_children
family
Once you choose a coverage tier, I’ll gather more specific details if needed.
-
3 · family details prompt
You
I want family coverage for me, my spouse, and our two children.
Bot
To proceed with family coverage, I’ll need the following details for each person:
-
For your spouse:
- Name
- Relationship (should be
spouse or domestic_partner)
- Birth date in
YYYY-MM-DD format
- Does your spouse have access to other medical coverage? (Yes or No)
-
For each of your two children:
- Name
- Relationship (should be
child)
- Birth date in
YYYY-MM-DD format
Please provide all this information in a single response, and we’ll move forward with the enrollment process.
-
4 · care preferences prompt
You
My spouse is Morgan Rivera, born 1987-03-12, and has other medical coverage available. Our children are Sam Rivera, born 2018-04-10, and Riley Rivera, born 2010-09-03.
Bot
Let’s gather some non-diagnostic preferences to help guide your medical plan selection. Please provide the following:
-
Anticipated care use: How often you expect to use medical services. Options:
preventive_only: Generally only need preventive care.
moderate: Some additional visits or services expected.
high: Frequent use of medical services anticipated.
-
Prescription use: Your expected use of prescriptions. Options:
none: Anticipate no prescription use.
occasional: Occasional prescription use.
regular: Regular prescription use.
-
Network preference: Your preference for in-network or out-of-network services. Options:
in_network_only: Prefer to stay within the network.
out_of_network_flexibility: Would like flexibility to go out of network.
-
Plan priorities: Choose one or more of the following priorities:
lowest_payroll_cost: To minimize deductions from payroll.
lower_deductible: Prioritize plans with a lower deductible.
out_of_network_access: Access to out-of-network care.
hsa_savings: Ability to save in a Health Savings Account.
prescription_coverage: Plans with robust prescription coverage.
Once you provide this information, we can proceed with capturing your preferences.
-
5 · deterministic medical plan options
You
We expect moderate use and regular prescriptions. I want out-of-network flexibility, HSA savings, and good prescription coverage.
Bot
2027 medical plans — family
| ID |
Plan |
Per paycheck |
Annual payroll |
Family deductible |
Family out-of-pocket max |
HSA / employer funding |
Out-of-network |
| EPO_VALUE |
Value EPO |
$155.00 |
$3,720.00 |
$2,500.00 |
$9,000.00 |
No |
No |
| HDHP_HSA |
HSA Advantage HDHP |
$125.00 |
$3,000.00 |
$5,000.00 |
$10,000.00 |
Yes / $1,500.00 |
Yes |
| PPO_STANDARD |
Standard PPO |
$220.00 |
$5,280.00 |
$3,000.00 |
$8,000.00 |
No |
Yes |
Rule-based fit: HDHP_HSA
- You prioritized HSA savings and the HDHP includes an employer HSA contribution.
- Compare prescription terms carefully because you reported regular medication use.
Fictional demo terms under rules benefits-demo-2027.1; this is decision support, not financial, tax, or medical advice. Verify the official plan documents and provider directory.
-
6 · exact HDHP and PPO comparison
You
Compare the HSA Advantage HDHP and Standard PPO.
Bot
Medical plan comparison
| Plan |
Per paycheck |
Annual payroll |
Family deductible |
Family OOP max |
Prescription terms |
HSA / employer funding |
Out-of-network |
| HSA Advantage HDHP (HDHP_HSA) |
$125.00 |
$3,000.00 |
$5,000.00 |
$10,000.00 |
20% after deductible |
Yes / $1,500.00 |
Yes |
| Standard PPO (PPO_STANDARD) |
$220.00 |
$5,280.00 |
$3,000.00 |
$8,000.00 |
$10 / $40 / $80 |
No |
Yes |
These are fictional demo terms. Verify official plan documents before enrolling.
-
7 · provider network lookup
You
Is Dr. Maya Chen in network for the Value EPO?
Bot
Dr. Maya Chen is out of network for Value EPO in the fictional demo directory. Recheck before receiving care.
-
8 · select HDHP and ask for HSA contribution
You
Select the HSA Advantage HDHP.
Bot
With your selected medical plan HSA Advantage HDHP, you’re eligible for a Health Savings Account (HSA).
Here’s how your HSA works in this demo:
- Account type: Health Savings Account (HSA)
- Who can contribute: You and your employer
- Employer HSA contribution: $1,500 for the year (already included in the totals below)
- Total annual HSA contribution limit (demo): $9,000
- Your current election: $0 from you + $1,500 from employer = $1,500 total
- Maximum you could still add: $9,000 total limit − $1,500 employer = up to $7,500 from you
You can choose a whole-dollar annual amount you want to contribute for the year (from $0 up to $7,500). This will be spread across your pay periods.
Please enter your annual employee HSA contribution as a whole dollar amount (for example, 0, 500, 1500, 3000, etc.).
If you prefer not to contribute personally, you can enter 0.
-
9 · reject excessive HSA contribution
You
I want to contribute $8,000 to the HSA.
Bot
$8,000 from you would put the HSA over the allowed annual limit for this demo:
- Employer contribution: $1,500
- Your requested contribution: $8,000
- Total: $9,500, which is $500 above the $9,000 combined annual limit
The maximum you can contribute is:
- $9,000 limit − $1,500 employer = $7,500 from you
Please enter a new whole-dollar annual HSA contribution between $0 and $7,500 (for example: 0, 1000, 3000, 7500).
If you’d rather not continue with a health account election right now, tell me you want to stop and I’ll end this part of enrollment.
-
10 · accept HSA and begin ancillary choices
You
Make my HSA contribution $6,000 instead.
Bot
Let’s start with dental and vision. Your coverage tier on file is family.
For dental, you can choose:
- waive (no dental coverage),
- basic, or
- premium.
For vision, you can choose:
- waive (no vision coverage), or
- standard.
- Which dental option do you want:
waive, basic, or premium?
- Which vision option do you want:
waive or standard?
If you’d like details on the difference between basic and premium dental before deciding, tell me and I’ll pull up a comparison.
-
11 · dental option comparison
You
What is the difference between Basic and Premium dental?
Bot
Dental options
| Option |
Per paycheck |
Annual maximum |
Orthodontia |
| Basic |
$28.00 |
$1,500.00 |
Not included |
| Premium |
$48.00 |
$2,500.00 |
50% up to a $2,000.00 lifetime maximum |
| Waive |
$0.00 |
— |
— |
Fictional demo terms; the official certificate controls.
-
12 · life and disability prompt
You
Choose Premium dental and Standard vision.
Bot
Got it: Premium dental and Standard vision for family coverage.
Next, we’ll choose supplemental life and disability:
-
Supplemental life insurance (for you):
You can elect 0×, 1×, 2×, or 3× your annual salary.
- 0× means you’re waiving supplemental life (you may still have basic employer-paid life if your plan includes it).
Which multiple would you like: 0, 1, 2, or 3 times your salary?
-
Short-term disability (STD):
Do you want to enroll in short-term disability coverage? (yes/no)
-
Long-term disability (LTD):
Do you want to enroll in long-term disability coverage? (yes/no)
Please reply with:
- Life: 0× / 1× / 2× / 3×
- STD: yes or no
- LTD: yes or no
-
13 · three-times life explanation
You
How much coverage and payroll cost would 3 times salary provide?
Bot
Supplemental life at 3× salary provides $234,000.00 of fictional demo coverage for $9.36 per paycheck. This amount requires evidence of insurability. The election can be submitted, but coverage above the guaranteed amount remains pending until approved. No health details are collected in this chat.
-
14 · complete ancillary elections
You
Choose 3 times salary life insurance, plus both short-term and long-term disability. Keep Premium dental and Standard vision.
Bot
I can do that. For your supplemental life insurance, I need to record one or more beneficiaries whose percentages add up to exactly 100%.
For each beneficiary, please provide:
- Full name
- Relationship to you (in your own words, e.g., “spouse,” “partner,” “child,” “friend,” “sibling,” etc.)
- Percentage (whole number, no decimals)
Let’s start with your first beneficiary:
- Name:
- Relationship:
- Percentage (out of 100):
-
15 · reject beneficiary allocation below 100
You
Set Morgan Rivera, spouse, to 60 percent and Sam Rivera, child, to 30 percent.
Bot
Right now we have:
- Morgan Rivera — spouse — 60%
- Sam Rivera — child — 30%
That totals 90%, so we still need to allocate the remaining 10% for the supplemental life insurance.
You have two options:
- Add another beneficiary for the remaining 10%, or
- Change the percentages for Morgan and/or Sam so that the total is exactly 100%.
Please tell me which you prefer. Examples:
- “Add Alex Rivera, parent, 10%”
- or “Make Morgan 70% and Sam 30%” (or any whole-number split that totals 100).
-
16 · accept beneficiary correction
You
Correction: Morgan gets 70 percent and Sam gets 30 percent.
Bot
The dependent-care FSA can reimburse eligible work-related childcare expenses under the fictional demo plan. It is separate from a healthcare FSA, has a $5,000 annual demo limit, and tax eligibility should be verified with the official plan materials or a tax adviser. Would you like to elect an annual contribution amount or waive this benefit with $0?
-
17 · dependent care explanation
You
What can the dependent-care FSA pay for?
Bot
The dependent-care FSA can reimburse eligible work-related childcare expenses under the fictional demo plan. It is separate from a healthcare FSA, has a $5,000 annual demo limit, and tax eligibility should be verified with the official plan materials or a tax adviser. Would you like to elect an annual contribution amount or waive this benefit with $0?
-
18 · reject excessive dependent care election
You
Contribute $6,000 to dependent care.
Bot
The dependent-care FSA can reimburse eligible work-related childcare expenses under the fictional demo plan. It is separate from a healthcare FSA, has a $5,000 annual demo limit, and tax eligibility should be verified with the official plan materials or a tax adviser. Would you like to elect an annual contribution amount or waive this benefit with $0?
-
19 · complete elections and show review
You
Use $3,000 for dependent care.
Bot
Benefits enrollment review for Alex Rivera
- Plan year / event: 2027 / open enrollment
- Household: family with Morgan Rivera, Sam Rivera, Riley Rivera
- Medical: HSA Advantage HDHP (HDHP_HSA), $125.00 per paycheck
- Health account: HSA, employee $6,000.00 + employer $1,500.00 annually
- Dental / vision: premium / standard
- Supplemental life: 3× salary ($234,000.00)
- Disability: short-term elected; long-term elected
- Beneficiaries: Morgan Rivera 70%, Sam Rivera 30%
- Dependent-care FSA: $3,000.00 annually
- Ancillary payroll cost: $86.86 per paycheck
- Pending requirements: EVIDENCE_OF_INSURABILITY
Confirm submission or request a contribution correction. Official plan documents control, and pending evidence-of-insurability coverage is not active until approved.
-
20 · review-time HSA correction
You
Before submitting, reduce my HSA contribution to $5,500.
Bot
Benefits enrollment review for Alex Rivera
- Plan year / event: 2027 / open enrollment
- Household: family with Morgan Rivera, Sam Rivera, Riley Rivera
- Medical: HSA Advantage HDHP (HDHP_HSA), $125.00 per paycheck
- Health account: HSA, employee $5,500.00 + employer $1,500.00 annually
- Dental / vision: premium / standard
- Supplemental life: 3× salary ($234,000.00)
- Disability: short-term elected; long-term elected
- Beneficiaries: Morgan Rivera 70%, Sam Rivera 30%
- Dependent-care FSA: $3,000.00 annually
- Ancillary payroll cost: $86.86 per paycheck
- Pending requirements: EVIDENCE_OF_INSURABILITY
Confirm submission or request a contribution correction. Official plan documents control, and pending evidence-of-insurability coverage is not active until approved.
-
21 · pending requirement explanation
You
What does the evidence-of-insurability item mean?
Bot
Evidence of insurability is a separate carrier review for the 3× supplemental-life election. The enrollment can be submitted now, but coverage above the guaranteed amount remains pending. No health details are collected in this chat.
-
22 · confirmed deterministic enrollment · completed
You
Everything is correct. Submit my enrollment.
Bot
Thank you for your time. To recap, enrollment for BEN-2027-61F7824BF5 for the 2027 plan year has been confirmed with the status as submitted_with_pending_requirements. The effective date is set for January 1, 2027, under the medical plan HDHP_HSA. The total estimated payroll deduction is $566.03 per paycheck. There is a pending requirement: EVIDENCE_OF_INSURABILITY. Please note that no payment was taken during this chat. This is a fictional benefits demonstration, and official plan documents control. Coverage remains pending and is not active until all requirements are approved. Should you have any further questions or need additional assistance, feel free to reach out. Have a great day!
The final HTTP response sets completed: true. The terminal step is the last active cursor; an API client must not submit a further employee message to that session.
What to compare when your replay differs
| Point in replay | Contract to preserve |
| Turns 1–4 | Collect only the enrollment and covered-household facts required for policy evaluation; do not request diagnoses or government IDs. |
| Turns 5–7 | Medical plans, terms, and network status are deterministic output; no plan fact is invented. |
| Turns 9, 15, and 18 | Invalid contribution or beneficiary values stay in their owning stage and ask for a correction. |
| Turns 19–20 | The review is read from saved application state and shows the corrected $5,500 HSA election. |
| Turn 22 | Submission is confirmed, pending evidence of insurability remains pending, and no payment or active coverage is claimed. |
Next
2. Designing an enrollment journey maps the stage boundaries, deterministic policy, corrections, and state owners that produce this replay.