Hyperfold AI

Agent Logs

Stream and analyze agent activity, decisions, and reasoning in real-time.

Overview

The hyperfold agent logs command provides real-time visibility into agent behavior. Watch negotiations unfold, understand pricing decisions, and debug issues as they happen.

Logs are stored in Cloud Logging and retained for 30 days by default. Configure longer retention in your project settings.

Stream Logs

Watch agent activity in real-time:

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# Stream live logs from an agent
$ hyperfold agent logs sales-bot-01
 
[2025-12-19 14:30:15] [INFO] Session started: sess_abc123
[2025-12-19 14:30:15] [INFO] Buyer: openai_gpt4_buyer | User: user_xyz
[2025-12-19 14:30:16] [ACP] Search request: "waterproof running shoes"
[2025-12-19 14:30:17] [DATA] Found 8 products (confidence: 0.91)
[2025-12-19 14:30:18] [ACP] Quote request: prod_aero_x2, offer=$120
[2025-12-19 14:30:19] [CALC] Floor: $92, List: $180, Competitor: $165
[2025-12-19 14:30:19] [DECISION] Counter-offer: $162 (10% gold discount)
[2025-12-19 14:30:20] [ACP] Response: counter_offer, price=162.00
[2025-12-19 14:30:45] [ACP] Accept received: price=162.00
[2025-12-19 14:30:46] [PAYMENT] Processing SPT: spt_live_xxx
[2025-12-19 14:30:47] [SUCCESS] Order created: order_789
[2025-12-19 14:30:47] [INFO] Session complete: revenue=$162.00
 
# Follow logs (like tail -f)
$ hyperfold agent logs sales-bot-01 --follow
 
# Show logs from all agents
$ hyperfold agent logs --all --follow

Log Levels

LevelDescription
DEBUGDetailed internal state (development only)
INFONormal operations, session events
WARNUnusual conditions, near-limit situations
ERRORFailures requiring attention

Session Logs

View complete logs for a specific negotiation session:

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
# View logs for a specific session
$ hyperfold agent logs sales-bot-01 --session="sess_abc123"
 
SESSION: sess_abc123
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
Started:    2025-12-19T14:30:15Z
Duration:   32 seconds
Status:     completed
Outcome:    conversion
 
BUYER INFO:
  Agent:        openai_gpt4_buyer
  User:         user_xyz (Gold tier)
  History:      12 previous orders, $2,450 total
 
CONVERSATION:
  Turn 1: Search "waterproof running shoes"
          → 8 products returned
 
  Turn 2: Quote prod_aero_x2 @ $120
          → Counter: $162 (10% discount applied)
 
  Turn 3: Accept $162
          → Order created
 
PRICING DECISIONS:
  List price:     $180.00
  Buyer offer:    $120.00
  Floor price:    $92.00
  Final price:    $162.00
  Discount:       10% (Gold tier)
  Margin:         45%
 
PAYMENT:
  Method:         Stripe SPT
  Amount:         $162.00
  Status:         succeeded
  Charge ID:      ch_xyz123

Reasoning Logs

See the agent's chain of thought for pricing decisions:

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
# Show agent reasoning (chain of thought)
$ hyperfold agent logs sales-bot-01 --reasoning
 
[14:30:18] [REASONING] Processing quote request...
 
  INPUT CONTEXT:
    Product: AeroRun X2 ($180 list)
    Buyer offer: $120
    Customer: Gold tier, 12 orders, $2,450 lifetime
    Inventory: 847 units (overstock)
    Competitor: $165 (Amazon)
 
  THOUGHT PROCESS:
    1. Buyer offered $120, which is 33% below list price
    2. My floor price is $92 (cost $80 × 1.15 margin)
    3. The offer is above floor, so it's technically acceptable
    4. However, I can do better for my margin
    5. Customer is Gold tier → 10% discount applies
    6. Competitor is at $165, so I should stay below that
    7. Optimal price: $162 (10% off, beats competitor by $3)
 
  DECISION: counter_offer
  PRICE: $162.00
  REASONING TO BUYER: "I can do $162 for you as a Gold member -
                       that's 10% off and beats Amazon's price."
 
# Verbose reasoning with all context
$ hyperfold agent logs sales-bot-01 --reasoning --verbose
 
# Reasoning for specific decision types
$ hyperfold agent logs sales-bot-01 --reasoning --filter="decision:reject"
Reasoning logs contain detailed decision context. Enable withENABLE_REASONING_LOG=true in agent configuration. This adds latency and storage costs.

Filtering & Search

Find specific logs with powerful filtering:

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
# Filter by log level
$ hyperfold agent logs sales-bot-01 --level=error
$ hyperfold agent logs sales-bot-01 --level=warn
 
# Filter by time range
$ hyperfold agent logs sales-bot-01 --since="1h"
$ hyperfold agent logs sales-bot-01 --since="2025-12-19T10:00:00Z"
$ hyperfold agent logs sales-bot-01 --until="2025-12-19T12:00:00Z"
 
# Filter by event type
$ hyperfold agent logs sales-bot-01 --filter="type:payment"
$ hyperfold agent logs sales-bot-01 --filter="type:acp"
$ hyperfold agent logs sales-bot-01 --filter="type:error"
 
# Search log content
$ hyperfold agent logs sales-bot-01 --search="floor price"
$ hyperfold agent logs sales-bot-01 --search="prod_aero_x2"
 
# Filter by outcome
$ hyperfold agent logs sales-bot-01 --filter="outcome:conversion"
$ hyperfold agent logs sales-bot-01 --filter="outcome:rejected"
$ hyperfold agent logs sales-bot-01 --filter="outcome:abandoned"
 
# Combine filters
$ hyperfold agent logs sales-bot-01 \
  --since="24h" \
  --filter="outcome:rejected" \
  --level=info

Export & Analysis

Export logs for offline analysis or external tools:

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
# Export logs to file
$ hyperfold agent logs sales-bot-01 --since="24h" --output=logs.json
 
> [Export] Fetching logs from last 24 hours...
> [Write] Writing 1,247 log entries to logs.json
✓ Exported to logs.json
 
# Export as CSV for analysis
$ hyperfold agent logs sales-bot-01 --since="7d" --format=csv --output=logs.csv
 
# Export session summaries
$ hyperfold agent logs sales-bot-01 --sessions --since="24h" --output=sessions.json
 
{
  "sessions": [
    {
      "session_id": "sess_abc123",
      "started_at": "2025-12-19T14:30:15Z",
      "duration_seconds": 32,
      "outcome": "conversion",
      "revenue": 162.00,
      "discount_percent": 10,
      "turns": 3
    }
  ],
  "summary": {
    "total_sessions": 127,
    "conversions": 42,
    "conversion_rate": 0.33,
    "total_revenue": 8450.00,
    "avg_discount": 12.3
  }
}
 
# Stream to external logging
$ hyperfold agent logs sales-bot-01 --follow | tee -a agent.log
 
# Send to BigQuery for analysis
$ hyperfold agent logs export --destination=bigquery --dataset=agent_logs
For advanced analytics, set up Operational Dashboards.