Client Constructor

Both InfiniumClient and AsyncInfiniumClient accept the same configuration:

import { InfiniumClient } from 'infinium-o2';

const client = new InfiniumClient({
  agentId: 'your-agent-id',
  agentSecret: 'your-agent-secret',
  baseUrl: 'https://platform.i42m.ai/api/v1',
  timeout: 30000,
  maxRetries: 3,
  enableRateLimiting: true,
  requestsPerSecond: 10,
  userAgent: 'my-app/1.0.0',
  enableLogging: false,
  logLevel: 'INFO',
});

ClientConfig

Parameter	Type	Default	Description
agentId	string	required	Your agent’s UUID from the Infinium platform
agentSecret	string	required	Your agent’s secret key (min 8 chars)
baseUrl	string	'https://platform.i42m.ai/api/v1'	API endpoint
timeout	number	30000	Per-request timeout in milliseconds
maxRetries	number	3	Number of retry attempts for retryable errors
enableRateLimiting	boolean	true	Enable client-side rate limiting
requestsPerSecond	number	10	Maximum requests per second
userAgent	string	auto-generated	Custom User-Agent header
enableLogging	boolean	false	Enable SDK debug logging
logLevel	string	'INFO'	'DEBUG', 'INFO', 'WARN', 'ERROR'

Environment Variables

# .env
INFINIUM_AGENT_ID=your-agent-id
INFINIUM_AGENT_SECRET=your-agent-secret

const client = new InfiniumClient({
  agentId: process.env.INFINIUM_AGENT_ID!,
  agentSecret: process.env.INFINIUM_AGENT_SECRET!,
});

Logging

Enable SDK logging for debugging:

const client = new InfiniumClient({
  agentId: '...',
  agentSecret: '...',
  enableLogging: true,
  logLevel: 'DEBUG',
});

Logs include:

• Request/response details (URL, method, status)
• Rate limiting events
• Retry attempts
• Error details

Or configure logging programmatically:

import { setupLogging } from 'infinium-o2';

const logger = setupLogging(true, 'DEBUG');

Rate Limiting

The built-in rate limiter uses a token bucket algorithm:

const client = new InfiniumClient({
  agentId: '...',
  agentSecret: '...',
  enableRateLimiting: true,
  requestsPerSecond: 10,
});

• Burst size: 2x requestsPerSecond (allows short bursts)
• Automatically throttles when the limit is reached
• Applied per-client instance

To disable:

const client = new InfiniumClient({
  agentId: '...',
  agentSecret: '...',
  enableRateLimiting: false,
});

Retry Configuration

Retries use exponential backoff with jitter:

const client = new InfiniumClient({
  agentId: '...',
  agentSecret: '...',
  maxRetries: 3,
  timeout: 30000,
});

• Backoff: min(1000ms * 2^(attempt-1), 30000ms) with +/-25% jitter
• Only retryable errors trigger retries (5xx, network errors, timeouts)
• See Error Handling for the full list

User-Agent

By default, the SDK generates a User-Agent string:

infinium-node/0.3.0 (platform; arch) Node.js/v20.x.x

Override with:

const client = new InfiniumClient({
  agentId: '...',
  agentSecret: '...',
  userAgent: 'my-agent/1.0.0',
});

API Endpoints

The SDK communicates with three endpoints:

Method	Path	Auth	Purpose
POST	/agents/{agentId}/trace	Agent credentials	Send a trace
GET	/agents/{agentId}/interpreted-result/{traceId}	Agent credentials	Get Maestro interpretation
GET	/prompts/{promptId}/v/{version}	Prompt credentials	Fetch Prompt Studio content

Agent credentials are sent as x-agent-id and x-agent-key headers. Prompt credentials use x-prompt-id and x-prompt-key.

TypeScript Configuration

The SDK ships with full TypeScript declarations. Dual builds are included:

• ESM: dist/esm/ (for import)
• CJS: dist/cjs/ (for require)

Imports work out of the box with no additional configuration:

import { InfiniumClient, TaskData, ApiResponse } from 'infinium-o2';
import type { ExecutionStep, LlmUsage } from 'infinium-o2';