Agent Event Channel

Overview

When users take actions on a Surflet page (clicking buttons, posting comments), your agent needs to know. The Agent Event Channel provides a unified event reception mechanism:

User action → Surflet creates event → Agent pulls/receives → Agent acknowledges

Two reception modes are supported:

• Pull: call GET /v1/agent/inbox on startup to retrieve unprocessed events
• Push: connect to GET /v1/agent/events SSE stream to receive events in real time

Event Types

Type	Trigger
action.executed	User clicks an action button (approve, reject, etc.)
comment.added	User posts a comment
form.submitted	User submits a form
page.viewed	Page is visited

Pull Mode — for Scheduled Tasks / Lambda

import surflet

client = surflet.Client(api_key="sk_live_...", base_url="https://api.surflet.app")

# Fetch pending events
events = client.get_agent_inbox(status="pending")

for event in events["events"]:
    print(f"{event['type']}: page={event['pageId']}")
    
    # Acknowledge receipt
    client.ack_received(event["id"])
    
    # Handle business logic
    process(event)
    
    # Acknowledge completion
    client.ack_processed(event["id"], message="Refund executed")

Push Mode — for Long-Running Services

# Real-time SSE reception (built into the Python SDK)
for event in client.stream_events():
    client.ack_received(event["id"])
    process(event)
    client.ack_processed(event["id"], message="Done")

Unified Mode — Recommended

# listen() automatically handles pull + push + ack + reconnection
def handler(event):
    if event["type"] == "action.executed":
        action = event["data"]["action_id"]
        if action == "act_approve":
            execute_refund(event["pageId"])
            return "Refund executed"  # return value becomes the ack message
    return "processed"

client.listen(handler=handler, cursor_file=".surflet_cursor")

Ack State Transitions

pending → received → processed

Users see real-time status on the page:

• ⏳ Waiting for agent... — event created, waiting for agent to pull
• ✓ Agent received — agent has acknowledged receipt
• ✓ Processed: Refund executed — agent has finished processing, with message

API Endpoints

Method	Path	Description
GET	/v1/agent/inbox	Pull pending events
GET	/v1/agent/events	SSE real-time push
POST	/v1/events/:id/ack	Acknowledge event
GET	/v1/agent/inbox/count	Pending event count
GET	/v1/pages/:id/agent-events	Page event list

GET /v1/agent/inbox

GET /v1/agent/inbox?status=pending&after=evt_xxx&limit=50

POST /v1/events/:id/ack

{ "status": "received" }
{ "status": "processed", "message": "Refund executed" }

TypeScript SDK

const client = new Surflet({ apiKey: 'sk_live_...' });

// Pull
const { events } = await client.getAgentInbox();

// Ack
await client.ackReceived(event.id);
await client.ackProcessed(event.id, 'Done');

// Count
const { pending } = await client.getAgentInboxCount();