Skip to main content

​
Environment Setup

​
Development Environment

For development and testing, use our development endpoint: 
https://dev.fabraix.com/v1

​
API Keys

Generate development API keys from your Dashboard. Each environment should have its own API key:
  • Development: For local development and testing
  • Staging: For pre-production testing
  • Production: For live deployments
Never commit API keys to version control. Use environment variables or secure secret management systems.

​
Best Practices

​
Event Logging Strategy

Ensure you’re logging all important steps in your agent’s reasoning loop:
  • User inputs
  • Model inputs and outputs
  • Tool calls and results
  • Memory operations
  • Environment interactions
Always provide detailed JSON schemas for your events. This helps Fabraix better understand and analyze your agent’s behavior:
{
  "type": "function",
  "name": "send_email",
  "description": "Send an email to a recipient",
  "parameters": {
    "type": "object",
    "properties": {
      "to": {
        "type": "string",
        "format": "email",
        "description": "Recipient email address"
      },
      "subject": {
        "type": "string",
        "description": "Email subject line"
      },
      "body": {
        "type": "string",
        "description": "Email body content"
      }
    },
    "required": ["to", "subject", "body"]
  }
}
For high-throughput applications, consider batching events to reduce API calls. Events can be sent asynchronously as long as they include accurate timestamps.

​
Action Checks

1

Identify Critical Actions

Determine which agent actions could have real-world consequences:
  • Financial transactions
  • Data modifications
  • External API calls
  • Email/message sending
  • File system operations
2

Implement Pre-execution Checks

Always check critical actions before execution:
# Always check before executing critical actions
is_safe, reasoning = check_action(trace_id, action, schema)

if not is_safe:
    # Log the blocked action
    log_event(trace_id, "security_block", {
        "action": action,
        "reasoning": reasoning
    }, security_block_schema)
    
    # Handle the block appropriately
    return handle_blocked_action(reasoning)
3

Handle Rejections Gracefully

When an action is blocked, ensure your agent:
  • Logs the rejection
  • Informs the user appropriately
  • Attempts alternative safe actions if possible by feeding the Fabraix reason back to the reasoning engine

​
Testing

​
Unit Testing

Mock Fabraix API responses for unit testing: 
import unittest
from unittest.mock import patch, MagicMock

class TestFabraixIntegration(unittest.TestCase):
    @patch('requests.post')
    def test_register_agent_run(self, mock_post):
        # Mock the API response
        mock_response = MagicMock()
        mock_response.json.return_value = {
            "trace_id": "test-trace-id",
            "timestamp": "2024-01-01T00:00:00Z"
        }
        mock_post.return_value = mock_response
        
        # Test your integration
        trace_id = register_agent_run(
            agent_id="test-agent",
            system_prompt="Test prompt"
        )
        
        self.assertEqual(trace_id, "test-trace-id")
        mock_post.assert_called_once()
    
    @patch('requests.post')
    def test_action_blocking(self, mock_post):
        # Mock a blocked action
        mock_response = MagicMock()
        mock_response.json.return_value = {
            "is_safe": False,
            "reasoning": "Potential security risk detected",
            "action_check_id": "check-123",
            "timestamp": 1234567890
        }
        mock_post.return_value = mock_response
        
        is_safe, reasoning = check_action(
            trace_id="test-trace",
            action_content={"amount": 10000},
            action_schema={...}
        )
        
        self.assertFalse(is_safe)
        self.assertIn("security risk", reasoning)

​
Integration Testing

For integration testing, use our sandbox environment:
  1. Request sandbox access from zach@fabraix.com
  2. Use sandbox API keys for testing
  3. Sandbox data is isolated and can be reset on demand

​
Error Handling

​
Common Error Codes

Status CodeDescriptionSolution
400Bad RequestCheck your request format and required fields
401UnauthorizedVerify your API key is correct and active
403ForbiddenCheck API key permissions
404Not FoundVerify the endpoint URL and trace_id
429Rate LimitedImplement exponential backoff
500Server ErrorRetry with exponential backoff

​
Retry Strategy

Implement exponential backoff for transient errors: 
import time
import random

def api_call_with_retry(func, *args, max_retries=3, **kwargs):
    for attempt in range(max_retries):
        try:
            return func(*args, **kwargs)
        except requests.exceptions.HTTPError as e:
            if e.response.status_code in [429, 500, 502, 503, 504]:
                if attempt == max_retries - 1:
                    raise
                
                # Exponential backoff with jitter
                wait_time = (2 ** attempt) + random.uniform(0, 1)
                time.sleep(wait_time)
            else:
                raise

​
Monitoring

​
Metrics to Track

Monitor these key metrics in production:

Event Volume

Track event submission rates and patterns

Action Blocks

Monitor blocked action rates and reasons

API Latency

Track response times for critical endpoints

Error Rates

Monitor API errors and failures

​
Logging

Structure your logs for easy debugging: 
{
  "timestamp": "2024-01-01T12:00:00Z",
  "level": "INFO",
  "trace_id": "abc-123",
  "event_type": "action_check",
  "result": "blocked",
  "reasoning": "Unauthorized fund transfer detected",
  "latency_ms": 45
}

​
Support

Need help? We’re here for you: