✨ @aurite-ai/api-client

A production-ready TypeScript client for the Aurite Framework API with comprehensive error handling, retry logic, and full type safety.

Features

• 🔒 Type Safety: Full TypeScript support with comprehensive type definitions
• 🔄 Retry Logic: Intelligent retry mechanisms for network failures
• 🛡️ Error Handling: Comprehensive error categorization and handling
• 📊 Streaming Support: Real-time streaming for agent responses
• 🧪 Testing: Extensive unit and integration test coverage
• 📖 Examples: Comprehensive examples for all API endpoints
• 🚀 Production Ready: Built for production use with robust error handling

Installation

Option 1: Install as NPM Package

npm install @aurite-ai/api-client
# or
yarn add @aurite-ai/api-client
# or
pnpm add @aurite-ai/api-client

Option 2: Development within Workspace

If you're working within the Aurite Framework repository:

# Clone the repository
git clone https://github.com/aurite-ai/aurite-agents.git
cd aurite-agents/frontend

# Install dependencies for all packages
npm install

# Build all packages (required for workspace dependencies)
npm run build

Quick Start

import { createAuriteClient } from '@aurite-ai/api-client';

// Create client instance
const client = createAuriteClient(
  process.env.AURITE_API_URL || 'http://localhost:8000',
  process.env.API_KEY || 'your-api-key'
);

// Run an agent
const result = await client.execution.runAgent('Weather Agent', {
  user_message: 'What is the weather in San Francisco?',
});

console.log(result.final_response?.content);

API Structure

The client provides access to four main API modules:

🤖 Execution (client.execution)

Execute agents and workflows with streaming support.

// Run an agent
const result = await client.execution.runAgent('Weather Agent', {
  user_message: 'What is the weather today?',
});

// Stream agent responses
await client.execution.streamAgent(
  'Weather Agent',
  { user_message: 'Tell me about the weather' },
  event => {
    if (event.type === 'llm_response') {
      console.log(event.data.content);
    }
  }
);

// Execute workflows
const workflowResult = await client.execution.runLinearWorkflow('Data Processing', {
  input_data: { source: 'api', format: 'json' },
});

🔧 Host (client.host)

Manage MCP servers and tools.

// List available tools
const tools = await client.host.listTools();

// Register an MCP server
await client.host.registerServerByName('weather_server');

// Call a tool directly
const toolResult = await client.host.callTool('get_weather', {
  location: 'San Francisco',
});

⚙️ Config (client.config)

Manage configurations for agents, LLMs, and servers.

// List all agent configurations
const agents = await client.config.listConfigs('agent');

// Get a specific configuration
const agentConfig = await client.config.getConfig('agent', 'Weather Agent');

// Create a new configuration
await client.config.createConfig('agent', {
  name: 'New Agent',
  llm: 'gpt-4',
  system_prompt: 'You are a helpful assistant.',
});

🔍 System (client.system)

Monitor system health and manage the framework.

// Get system information
const systemInfo = await client.system.getSystemInfo();

// Check framework version
const version = await client.system.getFrameworkVersion();

// Perform health check
const health = await client.system.comprehensiveHealthCheck();

Advanced Usage

Error Handling

The client provides comprehensive error handling with categorized error types:

import { ApiError, TimeoutError, CancellationError } from '@aurite-ai/api-client';

try {
  const result = await client.execution.runAgent('Weather Agent', {
    user_message: 'What is the weather?',
  });
} catch (error) {
  if (error instanceof ApiError) {
    console.error('API Error:', error.message);
    console.error('Status:', error.status);
    console.error('Category:', error.category);
  } else if (error instanceof TimeoutError) {
    console.error('Request timed out:', error.message);
  } else if (error instanceof CancellationError) {
    console.error('Request was cancelled:', error.message);
  }
}

Streaming Responses

Stream real-time responses from agents:

await client.execution.streamAgent(
  'Weather Agent',
  { user_message: 'Tell me about the weather' },
  event => {
    switch (event.type) {
      case 'llm_response':
        console.log('LLM Response:', event.data.content);
        break;
      case 'tool_call':
        console.log('Tool Call:', event.data.name, event.data.arguments);
        break;
      case 'tool_result':
        console.log('Tool Result:', event.data.result);
        break;
      case 'error':
        console.error('Stream Error:', event.data.message);
        break;
    }
  }
);

Custom Configuration

Configure the client with custom options:

import { createAuriteClient } from '@aurite-ai/api-client';

const client = createAuriteClient('http://localhost:8000', 'your-api-key', {
  timeout: 30000, // 30 second timeout
  retryAttempts: 3, // Retry failed requests 3 times
  retryDelay: 1000, // Wait 1 second between retries
  headers: {
    // Custom headers
    'User-Agent': 'MyApp/1.0.0',
  },
});

Examples

The package includes comprehensive examples in the examples/ directory:

Running Examples

# Run basic examples
npm run example

# Run integration tests (requires running API server)
npm run example:integration

Example Categories

• Configuration Management: examples/config/

  • List and manage configurations
  • Create and update agent configs
  • Reload configurations

• Agent Execution: examples/execution/

  • Basic agent execution
  • Streaming responses
  • Debug and troubleshooting

• Workflow Management: examples/execution/

  • Linear workflow execution
  • Custom workflow handling

• MCP Server Management: examples/mcp-host/

  • Server registration
  • Tool management and execution

• System Operations: examples/system/

  • Health checks
  • System information retrieval

Development

Setup

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

Environment Variables

Create a .env file:

# API Configuration
AURITE_API_URL=http://localhost:8000
API_KEY=your_api_key_here

# Environment
NODE_ENV=development

Workspace Development

When developing within the Aurite Framework workspace, you can also run examples and tests from the frontend root:

# From frontend root directory
npm run example --workspace=packages/api-client
npm run test:integration --workspace=packages/api-client

Building

# Build the package
npm run build

# Build in watch mode
npm run dev

# Clean build artifacts
npm run clean

Testing

# Run all tests
npm run test

# Run tests in watch mode
npm run test:watch

# Run tests with UI
npm run test:ui

# Run tests with coverage
npm run test:coverage

# Run only unit tests
npm run test:unit

# Run only integration tests (requires API server)
npm run test:integration

Code Quality

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Check formatting
npm run format:check

# Type check
npm run typecheck

# Validate everything
npm run validate

API Reference

Client Creation

createAuriteClient(baseUrl: string, apiKey: string, options?: ClientOptions): AuriteApiClient

Client Methods

Execution Client (client.execution)

• getStatus() - Get execution facade status
• runAgent(name, request) - Run an agent synchronously
• streamAgent(name, request, onEvent) - Stream agent responses
• runLinearWorkflow(name, request) - Run a linear workflow
• runCustomWorkflow(name, request) - Run a custom workflow

Host Client (client.host)

• getStatus() - Get MCP host status
• listTools() - List all available tools
• registerServerByName(name) - Register a server by name
• registerServerByConfig(config) - Register a server with custom config
• unregisterServer(name) - Unregister a server
• callTool(name, args) - Call a tool directly

Config Client (client.config)

• listConfigs(type) - List configurations by type
• getConfig(type, name) - Get a specific configuration
• createConfig(type, config) - Create a new configuration
• updateConfig(type, name, config) - Update a configuration
• deleteConfig(type, name) - Delete a configuration
• reloadConfigs() - Reload configurations from disk

System Client (client.system)

• getSystemInfo() - Get detailed system information
• getFrameworkVersion() - Get framework version
• getSystemCapabilities() - Get system capabilities
• getEnvironmentVariables() - Get environment variables
• updateEnvironmentVariables(vars) - Update environment variables
• listDependencies() - List project dependencies
• checkDependencyHealth() - Check dependency health
• getSystemMetrics() - Get system performance metrics
• listActiveProcesses() - List active processes
• comprehensiveHealthCheck() - Run full health check

Type Definitions

The client exports comprehensive TypeScript types:

Core Types

• ApiConfig - Client configuration options
• RequestOptions - Request-specific options
• ConfigType - Configuration type enumeration
• ExecutionStatus - Execution status enumeration

Request Types

• AgentRunRequest - Agent execution request
• WorkflowRunRequest - Workflow execution request
• ToolCallArgs - Tool call arguments

Response Types

• AgentRunResult - Agent execution result
• WorkflowExecutionResult - Workflow execution result
• StreamEvent - Streaming event types
• ToolCallResult - Tool call result

Error Types

• ApiError - API-related errors
• TimeoutError - Request timeout errors
• CancellationError - Request cancellation errors

Troubleshooting

Common Issues

Connection Errors:

// Ensure the API server is running and accessible
const client = createAuriteClient('http://localhost:8000', 'your-key');
try {
  await client.system.getFrameworkVersion();
} catch (error) {
  console.error('Connection failed:', error.message);
}

Authentication Errors:

// Verify your API key is correct
const client = createAuriteClient(baseUrl, 'correct-api-key');

Timeout Issues:

// Increase timeout for long-running operations
const client = createAuriteClient(baseUrl, apiKey, {
  timeout: 60000, // 60 seconds
});

Debug Mode

Enable debug logging:

// Set environment variable
process.env.DEBUG = 'aurite:*';

// Or enable in code
const client = createAuriteClient(baseUrl, apiKey, {
  debug: true,
});

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-feature
3. Make your changes with tests
4. Run validation: npm run validate
5. Commit your changes: git commit -am 'Add new feature'
6. Push to the branch: git push origin feature/new-feature
7. Submit a pull request

Development Guidelines

• Write TypeScript with strict type checking
• Include comprehensive tests for new features
• Follow the existing code style (ESLint + Prettier)
• Update documentation for new features
• Maintain backwards compatibility

📄 Citation

If you use the Aurite API Client in your projects or research, please cite:

@software{aurite_api_client_2025,
  title={Aurite API Client: Production TypeScript Client for AI Agent Framework},
  author={Jiten O and Ryan W and Blake R},
  year={2025},
  url={https://github.com/Aurite-ai/aurite-agents/tree/main/frontend/packages/api-client},
  note={TypeScript client library with streaming support and comprehensive error handling}
}

Core Framework Dependency: This client interfaces with the Aurite Framework. Please also cite:

@software{aurite_agents_2025,
  title={Aurite Agents Framework: A Python Framework for Building and Orchestrating AI Agents},
  author={Ryan W and Blake R and Jiten O},
  year={2025},
  version={0.3.26},
  url={https://github.com/Aurite-ai/aurite-agents},
  note={Configuration-driven AI agent framework with MCP integration and multi-LLM support}
}

License

MIT License - see LICENSE file for details.

Links

• Repository: https://github.com/aurite-ai/aurite-agents
• Documentation: https://github.com/aurite-ai/aurite-agents
• NPM Package: https://www.npmjs.com/package/@aurite-ai/api-client
• Issues: GitHub Issues
• API Reference: API Documentation

Changelog

See CHANGELOG.md for version history and changes.