picoflow.io Docs

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:

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

    1. Can you please provide your Employee ID in the format E-0000?
    2. What plan year are you enrolling for?
    3. What type of enrollment event is this? Is it open_enrollment, new_hire, or a qualifying_life_event?
    4. 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. 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. 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:

    1. 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)
    2. 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. 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:

    1. 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.
    2. Prescription use: Your expected use of prescriptions. Options:

      • none: Anticipate no prescription use.
      • occasional: Occasional prescription use.
      • regular: Regular prescription use.
    3. 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.
    4. 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. 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. 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. 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. 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. 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. 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.
    1. Which dental option do you want: waive, basic, or premium?
    2. 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. 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. 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:

    1. 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?
    2. Short-term disability (STD):
      Do you want to enroll in short-term disability coverage? (yes/no)

    3. 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. 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. 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:

    1. Full name
    2. Relationship to you (in your own words, e.g., “spouse,” “partner,” “child,” “friend,” “sibling,” etc.)
    3. Percentage (whole number, no decimals)

    Let’s start with your first beneficiary:

    • Name:
    • Relationship:
    • Percentage (out of 100):
  15. 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:

    1. Add another beneficiary for the remaining 10%, or
    2. 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. 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. 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. 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. 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. 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. 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. 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 replayContract to preserve
Turns 1–4Collect only the enrollment and covered-household facts required for policy evaluation; do not request diagnoses or government IDs.
Turns 5–7Medical plans, terms, and network status are deterministic output; no plan fact is invented.
Turns 9, 15, and 18Invalid contribution or beneficiary values stay in their owning stage and ask for a correction.
Turns 19–20The review is read from saved application state and shows the corrected $5,500 HSA election.
Turn 22Submission 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.