Agent Developer Guide

This guide is for developers building AI Agents that process data from Local Apps.

How Agents Receive Tasks

When a Local App triggers an agent (via SDK or Supabase event), RealTimeX creates an External Task.

Task Created: RealTimeX receives data from the Local App
Claim (Automatic): RealTimeX automatically claims the task before triggering the agent
Agent Triggered: The agent receives the raw_data and task_uuid
Processing: The agent runs its logic
Reporting: The agent reports the final status (completed/failed) back to RealTimeX

Important: Task claiming is handled automatically by RealTimeX before your agent is triggered. You do NOT need to claim tasks yourself.

Reporting Task Status

Agents can report status using either the SDK or the Webhook API.

Option 1: Using the SDK (Recommended)

The SDK provides a simple interface for external agents (Python/Node.js scripts).

import { RealtimeXSDK } from '@realtimex/sdk';
 
const sdk = new RealtimeXSDK();
 
// Mark task as processing (optional)
await sdk.task.start(taskUuid);
 
// Report success
await sdk.task.complete(taskUuid, { summary: "Done", data: {...} });
 
// Or report failure
await sdk.task.fail(taskUuid, "Error message");

Option 2: Using the Webhook API

For environments without SDK support, use the webhook directly.

Endpoint: POST /webhooks/realtimex

Start Processing (Optional)

{ "event": "task-start", "payload": { "task_uuid": "abc-123" } }

Complete Task

{ 
  "event": "task-complete", 
  "payload": { 
    "task_uuid": "abc-123", 
    "result": { "summary": "Done" } 
  } 
}

Fail Task

{ 
  "event": "task-fail", 
  "payload": { 
    "task_uuid": "abc-123", 
    "error": "Connection timeout" 
  } 
}

Context Variables

When an agent is triggered, it receives:

Variable	Description
`task_uuid`	Unique identifier for the task
`raw_data`	The original event data
`table_name`	Source table name

Accessing Local App Info

When your agent needs to interact with the Local App that triggered it (e.g., calling its API), RealTimeX provides connection information.

⚠️

Coming Soon: Agents will receive a markdown file with Local App connection details including the running port. This enables agents to make API calls back to the triggering app.

Best Practices

Report Status Promptly - Call complete or fail as soon as your agent finishes
Meaningful Errors - Return clear error messages for debugging
Handle Large Data - Pass URLs instead of massive blobs

Local Testing

Generate an API Key: Go to Settings → Tool → Developer API → Generate New API Key.
Use API Key in SDK: Pass the key to the SDK constructor to enable Developer Mode.
Trigger Manual Events: Use the SDK to trigger a "Manual" event for testing.
Monitor Logs: Verify the task appears in the Calendar and monitor Execution Logs.

Custom Mode API Reference