SDK Reference

The @agentdeploy/sdk package lets you deploy and manage AI agents programmatically.

Installation

npm install @agentdeploy/sdk

Configuration

import { AgentDeploy } from '@agentdeploy/sdk';

const client = new AgentDeploy({
  apiKey: process.env.AGENTDEPLOY_API_KEY!, // Required
  baseUrl: 'https://api.agentdeploy.io',    // Optional, defaults to production
  requestTimeoutMs: 30000,                  // Optional, default 30s
  fetch: customFetch,                       // Optional, for testing
});

Deploy an agent

const deployment = await client.deploy({
  templateId: 42,
  // OR: templateSlug: 'customer-support-bot',
  llmProvider: 'openrouter',
  model: 'openai/gpt-4o-mini',
  region: 'us-central',        // optional
  secrets: {                    // optional, can set later
    LLM_API_KEY: 'your-key...',
  },
});

console.log(deployment.id);    // deployment UUID
console.log(deployment.url);   // worker URL

Chat with an agent

Non-streaming

const response = await client.chat('deployment-id', {
  messages: [
    { role: 'system', content: 'You are helpful.' },
    { role: 'user', content: 'What is 2+2?' },
  ],
  temperature: 0.7,
  max_tokens: 1000,
});

console.log(response.choices[0].message.content);
console.log(`Tokens: ${response.usage.total_tokens}`);
console.log(`Charged: $${response.usage.charged_usd ?? '0.00'}`);

Streaming

for await (const chunk of client.chatStream('deployment-id', {
  messages: [{ role: 'user', content: 'Write a poem' }],
  stream: true,
})) {
  process.stdout.write(chunk);
}

Using the Deployment object

The deploy() method returns a Deployment object with convenience methods:

const deployment = await client.deploy({ ... });

// Chat
const response = await deployment.chat({
  messages: [{ role: 'user', content: 'Hello' }],
});

// Stream
for await (const chunk of deployment.stream({
  messages: [{ role: 'user', content: 'Hello' }],
})) {
  console.log(chunk);
}

// Get details
const details = await deployment.details();
console.log(details.status);
console.log(details.edge_invocations_total);

// Check health
const health = await deployment.health();
console.log(health.provisioned);

// Manage secrets
await deployment.setSecret('LLM_API_KEY', 'your-key...');
await deployment.setSecrets({
  LLM_API_KEY: 'your-key...',
  DATABASE_URL: 'postgres://...',
});
await deployment.deleteSecret('OLD_KEY');

// Check usage
const usage = await deployment.usage();
console.log(`${usage.invocations} invocations`);
console.log(`${usage.cpuTimeMs}ms CPU time`);

// Restart (re-provision)
await deployment.restart();

// Delete
await deployment.destroy();

List deployments

const page1 = await client.listDeployments({ limit: 25, offset: 0 });
console.log(`${page1.total} total deployments`);

for (const dep of page1.items) {
  console.log(`${dep.id} — ${dep.status} — ${dep.model}`);
}

Get a specific deployment

const deployment = await client.getDeployment('dep-abc123');
const details = await deployment.details();

Error handling

import { AgentDeployError } from '@agentdeploy/sdk';

try {
  await client.deploy({ templateId: 999 });
} catch (err) {
  if (err instanceof AgentDeployError) {
    console.error(err.code);      // e.g. 'TEMPLATE_NOT_FOUND'
    console.error(err.status);    // e.g. 404
    console.error(err.message);   // human-readable
    console.error(err.requestId); // for support
  }
}

Common error codes

Code	Status	Meaning
TEMPLATE_NOT_FOUND	404	Template ID doesn't exist
SUBSCRIPTION_REQUIRED	403	No active hosting subscription
ENTITLEMENT_DENIED	403	Haven't purchased this template
EDGE_AGENT_LIMIT_REACHED	409	Plan limit exceeded
CORE_AGENT_LIMIT_REACHED	409	Plan limit exceeded
SDK_TIMEOUT	504	Request timed out

Types

import type {
  EdgeDeployment,
  EdgeDeploymentHealth,
  EdgeUsage,
  DeployInput,
  ChatMessage,
  ChatOptions,
  ChatResponse,
  PagedResult,
} from '@agentdeploy/sdk';