agentlify-js

Official JavaScript/TypeScript SDK for Agentlify.

agentlify-js provides:

• OpenAI-style chat completions through Agentlify routers
• Agent execution APIs with optional local tool callbacks
• Streaming support
• Typed errors and TypeScript definitions

Installation

npm install agentlify-js

Quick Start

const Agentlify = require('agentlify-js');

const client = new Agentlify({
  apiKey: process.env.AGENTLIFY_API_KEY, // required, mp_*
  routerId: process.env.AGENTLIFY_ROUTER_ID, // required
});

const completion = await client.chat.create({
  messages: [{ role: 'user', content: 'Hello!' }],
});

console.log(completion.choices[0].message.content);
console.log('Model used:', completion._meta?.modelUsed);
console.log('Cost:', completion._meta?.cost);

Configuration

const client = new Agentlify({
  apiKey: 'mp_...',
  routerId: 'router_...',
  timeout: 30000,
  maxRetries: 3,
  // optional:
  // baseURL: 'https://modelpilot.co/api'
  // defaultHeaders: { 'X-Custom': 'value' }
});

Notes:

• apiKey must start with mp_
• routerId is required
• default baseURL is https://modelpilot.co/api

Chat API

Standard completion

const res = await client.chat.create({
  messages: [
    { role: 'system', content: 'You are concise.' },
    { role: 'user', content: 'Summarize this paragraph.' },
  ],
  temperature: 0.4,
  max_tokens: 200,
});

Streaming

const stream = await client.chat.create({
  messages: [{ role: 'user', content: 'Write a short story.' }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '');
}

Agents API

agents.run (automatic callback loop)

Use this when you want local callbacks to execute tool calls automatically.

const response = await client.agents.run({
  agentId: 'support-assistant',
  messages: [{ role: 'user', content: 'Check order 12345 status' }],
  tools: [
    {
      type: 'function',
      function: {
        name: 'get_order_status',
        description: 'Fetch order status',
        parameters: {
          type: 'object',
          properties: { orderId: { type: 'string' } },
          required: ['orderId'],
        },
      },
      callback: async ({ orderId }) => {
        return { orderId, status: 'shipped' };
      },
    },
  ],
});

agents.execute (single request, no callback loop)

const response = await client.agents.execute({
  agentId: 'support-assistant',
  messages: [{ role: 'user', content: 'Need help with billing' }],
});

Utility Methods

const routerConfig = await client.getRouterConfig();
const models = await client.getModels();

Error Handling

const { AuthenticationError, RateLimitError, APIError } = require('agentlify-js');

try {
  await client.chat.create({
    messages: [{ role: 'user', content: 'Hello' }],
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error('Rate limited');
  } else if (error instanceof APIError) {
    console.error('API error', error.status, error.message);
  } else {
    console.error(error.message);
  }
}

TypeScript

Types are included in the package (dist/index.d.ts).

import Agentlify from 'agentlify-js';
import type { ChatMessage } from 'agentlify-js';

const client = new Agentlify({
  apiKey: process.env.AGENTLIFY_API_KEY!,
  routerId: process.env.AGENTLIFY_ROUTER_ID!,
});

const messages: ChatMessage[] = [{ role: 'user', content: 'Hello' }];
const completion = await client.chat.create({ messages });

License

MIT