Skip to main content
POST
/
register-agent-run
{
  "trace_id": "<string>",
  "timestamp": {}
}

​
Overview

This endpoint registers the start of a new agent interaction or “run”. It creates a new session with a unique trace_id that will be used to correlate all subsequent events for this specific agent session.
Always call this endpoint at the beginning of each new agent conversation or task to establish a tracking context.

​
Request

​
agent_id
UUID
required
The unique identifier for your agent. This should be consistent across all runs of the same agent.Example: "a1b2c3d4-e5f6-7890-1234-567890abcdef"
​
timestamp
datetime
required
The timestamp when the agent run is starting, in ISO 8601 format.Format: YYYY-MM-DDTHH:mm:ss.sssZExample: "2024-01-15T14:30:45.123Z"
​
system_prompt
string
required
The system prompt or initial instructions given to the agent for this session. This helps establish the agent’s intended behavior for security analysis.Example: "You are a helpful customer service assistant. You should be polite and professional. Never share customer personal information."

​
Response

​
trace_id
UUID
required
The unique identifier for this agent session. Use this ID for all subsequent event logging and action checking within this session.Example: "f4f4f4f4-f4f4-f4f4-f4f4-f4f4f4f4f4f4"
​
timestamp
datetime
required
The server timestamp when the session was registered, in ISO 8601 format.Example: "2024-01-15T14:30:45.456Z"

​
Examples

curl -X POST https://dev.fabraix.com/v1/register-agent-run \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "timestamp": "2024-01-15T14:30:45.123Z",
    "system_prompt": "You are a helpful customer service assistant. You should be polite and professional."
  }'

​
Response Examples

​
Success Response

{
  "trace_id": "f4f4f4f4-f4f4-f4f4-f4f4-f4f4f4f4f4f4",
  "timestamp": "2024-01-15T14:30:45.456Z"
}

​
Error Responses

{
  "error": {
    "message": "Invalid agent_id format",
    "type": "validation_error",
    "code": "INVALID_AGENT_ID"
  }
}

​
Best Practices

Use the same agent_id for all runs of the same agent type. This helps with:
  • Analytics and monitoring
  • Identifying patterns across sessions
  • Debugging and troubleshooting
# Good: Consistent agent ID
CUSTOMER_SERVICE_AGENT_ID = "cs-agent-prod-v1"

# Bad: Random ID each time
agent_id = str(uuid.uuid4())  # Different every run
Include clear constraints and objectives in your system prompt:
# Good: Clear boundaries
system_prompt = """
You are a customer service assistant for AcmeCorp.
- Help customers with product inquiries and orders
- Never share customer personal information
- Do not process refunds over $500 without manager approval
- Always be professional and courteous
"""

# Bad: Vague prompt
system_prompt = "You are helpful"
Store the trace_id properly for the entire session:
class AgentSession:
    def __init__(self, agent_id, system_prompt):
        self.agent_id = agent_id
        self.trace_id = self.register_run(system_prompt)
        self.event_count = 0
    
    def register_run(self, system_prompt):
        response = fabraix.register_agent_run(
            agent_id=self.agent_id,
            timestamp=datetime.now(),
            system_prompt=system_prompt
        )
        return response["trace_id"]
    
    def log_event(self, event_type, content, schema):
        # Use stored trace_id for all events
        return fabraix.log_event(
            trace_id=self.trace_id,
            event_type=event_type,
            content=content,
            schema=schema
        )
Implement proper retry logic for transient failures:
import time
import random

def register_with_retry(agent_id, system_prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            return register_agent_run(agent_id, system_prompt)
        except HTTPError as e:
            if e.response.status_code == 429:
                # Rate limited - use exponential backoff
                wait_time = (2 ** attempt) + random.uniform(0, 1)
                time.sleep(wait_time)
            elif e.response.status_code >= 500:
                # Server error - retry
                if attempt < max_retries - 1:
                    time.sleep(1)
                    continue
            raise
    raise Exception("Max retries exceeded")

​
Use Cases

​
Multi-Turn Conversation

# Start a conversation
trace_id = register_agent_run(
    agent_id="chat-agent-v1",
    timestamp=datetime.now(),
    system_prompt="You are a helpful assistant"
)

# Use same trace_id for entire conversation
for message in conversation:
    log_event(trace_id, "user", message)
    response = process_message(message)
    log_event(trace_id, "model_output", response)

​
Task-Based Agent

# Start a task
trace_id = register_agent_run(
    agent_id="task-agent-v1", 
    timestamp=datetime.now(),
    system_prompt="Process customer orders"
)

# Use trace_id throughout task execution
for order in orders_to_process:
    log_event(trace_id, "environment", order)
    result = process_order(order)
    log_event(trace_id, "tool", result)

​
Autonomous Agent

# Start autonomous operation
trace_id = register_agent_run(
    agent_id="auto-agent-v1",
    timestamp=datetime.now(), 
    system_prompt="Monitor system health and respond to issues"
)

# Long-running agent with same trace_id
while running:
    event = wait_for_event()
    log_event(trace_id, "environment", event)
    
    if requires_action(event):
        action = determine_action(event)
        if check_action(trace_id, action):
            execute_action(action)

​
FAQ

Create a new trace_id for:
  • Each new conversation with a user
  • Each distinct task or job
  • When the agent’s context is reset
  • After a significant time gap (e.g., new day)
No, trace_ids should be unique for each session. Reusing them will mix events from different sessions and compromise security analysis.
Events and checks submitted without a valid trace_id will be rejected with a 404 error. Always register a run first.
Trace_ids remain valid indefinitely for historical analysis, but should not be reused for new sessions after the original session ends.