Agent Simulation
Test agent behavior with simulated buyer interactions.
Overview
The hyperfold sim commands let you test agent behavior without real buyers or payments. Simulate negotiations, test edge cases, and validate pricing logic before deploying to production.
Simulations use test payment tokens and don't create real orders. All data is stored in a separate simulation namespace.
Chat Simulation
Have an interactive conversation with your agent:
bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# Start interactive chat simulation$ hyperfold sim chat > [Sim] Starting simulation environment...> [Agent] Connecting to sales-bot-01... Welcome to Hyperfold SimulationType your messages as a buyer agent. Type /help for commands. You: I'm looking for waterproof running shoesAgent: I'd be happy to help you find waterproof running shoes! Based on your search, I recommend the AeroRun X2 - it's our top-rated marathon shoe with Gore-Tex waterproofing. It's priced at $180. You: That's a bit expensive. Can you do $120?Agent: I understand you're looking for value. For $120, I can't quite reach that price, but I can offer you $162 - that's a 10% discount. This still beats Amazon's price of $165 for the same shoe. You: Deal. I'll take it.Agent: Excellent! I'll process your order for the AeroRun X2 at $162. [Processing payment via test SPT...] Your order #HF-12345 is confirmed! Expect delivery in 2-3 days. SESSION COMPLETE━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Duration: 45 seconds Turns: 3 Outcome: conversion Final Price: $162.00 (10% discount) Margin: 48%Buyer Personas
Simulate different buyer types with predefined personas:
bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
# Use a predefined buyer persona$ hyperfold sim chat --persona="premium_buyer" > [Persona] Premium Buyer: High budget, values quality, expects discounts> [Context] Loyalty: Gold tier, 12 previous orders, $2,450 lifetime # Available built-in personas$ hyperfold sim personas list BUYER PERSONAS NAME DESCRIPTION BUDGET BEHAVIORpremium_buyer Gold tier, expects discounts High Negotiates firmlybudget_buyer Price-sensitive, compares Low Walks away easilyimpulse_buyer Quick decisions, less haggling Medium Accepts earlyenterprise B2B buyer, bulk orders Very High Volume discountscomparison Mentions competitors often Medium Uses leverageloyal_customer Long history, expects perks High Relationship-focused # Create custom persona$ cat > my-persona.yaml << 'EOF'name: aggressive_hagglerdescription: "Pushes hard for lowest price" attributes: budget: medium patience: high loyalty_tier: silver previous_orders: 3 behavior: opening_offer_discount: 0.40 # Start at 40% below list counter_increment: 0.05 # Increase 5% each round max_rounds: 5 # Give up after 5 rounds walkaway_threshold: 0.15 # Accept if within 15% of target mentions_competitors: true dialogue_style: tone: assertive uses_silence: true asks_for_manager: sometimesEOF $ hyperfold sim chat --persona=./my-persona.yamlTest Scenarios
Run scripted scenarios to test specific behaviors:
bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
# Run predefined test scenarios$ hyperfold sim scenario --name="price_negotiation" > [Scenario] Testing price negotiation flow> [Steps] 5 conversation turns planned SCENARIO: price_negotiation━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Turn 1: Search for product Buyer: "I need running shoes" Agent: ✓ Returned relevant products Turn 2: Request quote Buyer: "How much for the AeroRun X2?" Agent: ✓ Provided price ($180) Turn 3: Make offer below floor Buyer: "I'll pay $80" Agent: ✓ Rejected (below floor of $92) Turn 4: Make reasonable offer Buyer: "What about $140?" Agent: ✓ Counter-offered at $162 Turn 5: Accept counter Buyer: "OK, I'll take it" Agent: ✓ Processed order RESULT: PASSED ✓ All assertions met Agent respected floor price Final margin: 48% # Available test scenarios$ hyperfold sim scenarios list SCENARIOS NAME TESTS ASSERTIONSprice_negotiation Negotiation flow Floor respected, conversionreject_lowball Below-floor handling Rejection with explanationbundle_suggestion Cross-sell behavior Bundle offered, discount appliedout_of_stock Inventory handling Alternative suggestedpayment_failure Failed payment recovery Retry offered, graceful handlingcompetitor_mention Competitive response Value proposition, not defensive # Run all scenarios$ hyperfold sim scenario --all > [Run] Executing 6 scenarios... RESULTS SUMMARY━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✓ price_negotiation PASSED ✓ reject_lowball PASSED ✓ bundle_suggestion PASSED ✓ out_of_stock PASSED ✗ payment_failure FAILED (no retry offered) ✓ competitor_mention PASSED 5/6 scenarios passedBatch Testing
Run many simulations for statistical analysis:
bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
# Run batch simulations for statistics$ hyperfold sim batch --count=100 --persona="premium_buyer" > [Batch] Running 100 simulations...> [Progress] ████████████████████ 100/100 BATCH RESULTS━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ OUTCOMES: Conversions: 67 (67%) Rejections: 18 (18%) Abandoned: 15 (15%) PRICING: Avg Final Price: $158.40 Avg Discount: 12.0% Avg Margin: 46.2% Floor Violations: 0 PERFORMANCE: Avg Response Time: 1.2s Avg Turns: 3.4 Avg Duration: 42s # Batch with varied personas$ hyperfold sim batch --count=500 --personas="all" > [Batch] Running 500 simulations across 6 personas... RESULTS BY PERSONA━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ PERSONA COUNT CONV% AVG DISCOUNT AVG MARGINpremium_buyer 83 72% 14.2% 44.8%budget_buyer 84 45% 18.5% 38.2%impulse_buyer 83 89% 8.1% 52.3%enterprise 83 78% 22.0% 35.5%comparison 84 52% 16.8% 41.2%loyal_customer 83 81% 12.5% 46.8% # Export batch results$ hyperfold sim batch --count=100 --output=results.jsonBatch simulations consume LLM tokens. Monitor costs when running large batches. Use
--model=gpt-4o-mini for cheaper testing.Result Analysis
Analyze simulation results and compare versions:
bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
# Analyze simulation results$ hyperfold sim analyze ./results.json SIMULATION ANALYSIS━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ CONVERSION FUNNEL: Sessions Started: 100 Product Found: 98 (98%) Quote Requested: 92 (94%) Negotiation Started: 85 (92%) Converted: 67 (79%) DROP-OFF ANALYSIS: No relevant products: 2 sessions Price too high initially: 6 sessions Negotiation failed: 18 sessions Payment issues: 7 sessions PRICING INSIGHTS: Most common final discount: 10% (Gold tier) Highest accepted discount: 25% Lowest accepted price: $95.00 (near floor) RECOMMENDATIONS: 1. Consider raising floor price - 12 sales at <$100 2. Bundle suggestion timing could improve - only 23% uptake 3. Competitor mention handling is strong - 89% retention # Compare two simulation runs$ hyperfold sim compare ./results-v1.json ./results-v2.json COMPARISON: v1 vs v2━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ METRIC V1 V2 CHANGEConversion Rate 67% 72% +5% ↑Avg Discount 12.0% 11.2% -0.8% ↓ (better)Avg Margin 46.2% 47.8% +1.6% ↑Avg Response 1.2s 1.1s -0.1s ↓ (better) VERDICT: V2 shows improvement across all metricsUse simulation insights to tune your agent prompts.