Local API Overview

The AGNT Local Backend API runs on your machine as part of the desktop application, providing direct access to local resources and agent execution.

Base URL

http://localhost:3333/api

Key Features

🖥️ Local Execution

• Agents run directly on your machine
• No cloud dependency for execution
• Full control over data and privacy

🔧 System Integration

• File system access
• Shell command execution
• Local tool execution
• MCP server integration

🚀 Performance

• No network latency
• Unlimited rate limits
• Direct hardware access

🔒 Security

• Self-signed SSL certificate
• Local-only access by default
• No data leaves your machine (unless explicitly configured)

API Categories

Agent Operations

• Agents - Local agent management and execution (see Local API Endpoints)
• Goals - Goal-based agent execution with evaluation (see Local API Endpoints)
• Orchestrator - Universal chat handler for all agent types (see Local API Endpoints)

Workflow & Execution

• Workflows - Workflow execution and management (see Local API Endpoints)
• Executions - Execution history and details (see Local API Endpoints)

Tools & Integration

• Tools - Tool management and schemas (see Local API Endpoints)
• Custom Tools - Custom tool definitions (see Local API Endpoints)
• MCP - Model Context Protocol server management (see Local API Endpoints)
• NPM - NPM package search for MCP servers (see Local API Endpoints)

AI & Models

• Models - AI model management and selection (see Local API Endpoints)
• Streaming - Real-time AI streaming (see Local API Endpoints)
• Speech - Speech-to-text services (see Local API Endpoints)

User & Settings

• Users - User settings and preferences (see Local API Endpoints)
• Webhooks - Local webhook management (see Local API Endpoints)

Quick Reference

Common Endpoints

Authentication

The local API uses the same JWT token as the remote API. The token is automatically synced from the remote API when you log in.

headers: {
  'Authorization': 'Bearer YOUR_JWT_TOKEN'
}

SSL Certificate

The local API uses a self-signed SSL certificate. You may need to accept the certificate in your browser or configure your HTTP client to trust it.

Node.js Example

const https = require('https');

const agent = new https.Agent({
  rejectUnauthorized: false, // Accept self-signed certificate
});

fetch('http://localhost:3333/api/agents', {
  agent,
  headers: {
    Authorization: 'Bearer YOUR_JWT_TOKEN',
  },
});

Response Format

Success Response

{
  "success": true,
  "data": {
    /* response data */
  }
}

Error Response

{
  "success": false,
  "error": "Error message",
  "details": "Additional error details"
}

File Uploads

Some endpoints support file uploads using multipart/form-data:

const formData = new FormData();
formData.append('message', 'Analyze this file');
formData.append('files', fileBlob, 'document.pdf');

fetch('http://localhost:3333/api/orchestrator/chat', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_JWT_TOKEN',
  },
  body: formData,
});

Server-Sent Events (SSE)

Streaming endpoints use Server-Sent Events for real-time updates:

const eventSource = new EventSource('http://localhost:3333/api/users/connection-health-stream?token=YOUR_JWT_TOKEN');

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Health update:', data);
};

eventSource.onerror = (error) => {
  console.error('SSE error:', error);
  eventSource.close();
};

Health Checks

Most services provide health check endpoints:

GET http://localhost:3333/api/agents/health
GET http://localhost:3333/api/workflows/health
GET http://localhost:3333/api/stream/health
GET http://localhost:3333/api/goals/health

// Response
{
  "status": "OK",
  "timestamp": "2025-11-25T10:00:00Z"
}

CORS

The local API allows CORS from the desktop application's frontend:

Access-Control-Allow-Origin: http://localhost:5173
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type

Rate Limiting

The local API has no rate limits since it runs on your machine.

Common Patterns

Executing an Agent

// 1. List available agents
const agents = await fetch('http://localhost:3333/api/agents', {
  headers: { Authorization: `Bearer ${token}` },
}).then((r) => r.json());

// 2. Chat with an agent
const response = await fetch(`http://localhost:3333/api/agents/${agentId}/chat`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    message: 'What is the weather today?',
    stream: false,
  }),
}).then((r) => r.json());

Running a Workflow

// 1. Get workflow
const workflow = await fetch(`http://localhost:3333/api/workflows/${workflowId}`, {
  headers: { Authorization: `Bearer ${token}` },
}).then((r) => r.json());

// 2. Start workflow
const execution = await fetch(`http://localhost:3333/api/workflows/${workflowId}/start`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    inputs: { query: 'research topic' },
  }),
}).then((r) => r.json());

// 3. Check status
const status = await fetch(`http://localhost:3333/api/workflows/${workflowId}/status`, {
  headers: { Authorization: `Bearer ${token}` },
}).then((r) => r.json());

Using MCP Servers

// 1. List MCP servers
const servers = await fetch('http://localhost:3333/api/mcp/servers', {
  headers: { Authorization: `Bearer ${token}` },
}).then((r) => r.json());

// 2. Add MCP server
const newServer = await fetch('http://localhost:3333/api/mcp/servers', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'weather-server',
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-weather'],
    env: {},
  }),
}).then((r) => r.json());

// 3. Test connection
const test = await fetch('http://localhost:3333/api/mcp/servers/weather-server/test', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}` },
}).then((r) => r.json());

Error Codes

Debugging

Enable Verbose Logging

Set environment variable:

DEBUG=agnt:* npm start

Check Server Logs

Logs are written to:

Windows: %APPDATA%/AGNT/logs/
macOS: ~/Library/Application Support/AGNT/logs/
Linux: ~/.config/AGNT/logs/

Test Connectivity

curl -k http://localhost:3333/api/agents/health

Security Considerations

Local-Only Access

By default, the API only accepts connections from localhost. To allow remote access (not recommended):

// In server configuration
server.listen(3333, '0.0.0.0'); // Listen on all interfaces

Token Security

• Tokens are stored securely in the system keychain
• Never expose tokens in logs or error messages
• Tokens are automatically refreshed when needed

File System Access

• The API has full file system access
• Be cautious with file operations
• Validate all file paths to prevent directory traversal

Next Steps

• Local API Endpoints - Complete endpoint reference
• Remote API Overview - Cloud API features
• Authentication - Auth methods
• Examples - Code examples