SDK Last updated March 14, 2026

TypeScript SDK

The agentbridge-sdk package is a type-safe, ESM-first client for the AgentBridge API. Install it with one command and start executing MCP tools immediately — no need to construct HTTP requests, manage headers, or parse response envelopes manually.

The SDK is ESM-first and works in Node.js 18+, Deno, Bun, and modern bundlers (Vite, esbuild, Webpack 5). CommonJS (require()) is also supported via a dual-package build.

Installation #

bash — npm 
npm install agentbridge-sdk
bash — yarn 
yarn add agentbridge-sdk
bash — pnpm 
pnpm add agentbridge-sdk

Environment Setup #

Create a .env file (or use your platform's secret management) and add your API key:

.env 
# AgentBridge API Key — never commit this file
AGENTBRIDGE_API_KEY=ab_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Add .env to your .gitignore. If you use dotenv, load it before initializing the SDK. In Node.js 20.6+ you can use the built-in --env-file=.env flag.

Quick Example #

typescript 
import { AgentBridge } from 'agentbridge-sdk';

const bridge = new AgentBridge(process.env.AGENTBRIDGE_API_KEY!);

const result = await bridge.execute({
  provider: 'notion',
  tool:     'create_page',
  params: {
    parent_id: 'abc123',
    title:     'My First Page',
  },
});

console.log(result.status);      // "success"
console.log(result.data);        // { id: '...', url: '...' }
console.log(result.latencyMs);   // 381
console.log(result.executionId); // "exec_01HXZ..."

Constructor Options #

typescript — signature 
new AgentBridge(apiKey: string, options?: AgentBridgeOptions)
apiKey required string Your AgentBridge API key. Must begin with ab_live_. The SDK validates the prefix and throws if malformed.
options.baseUrl optional string Override the API base URL. Defaults to https://api.agentbridge.in. Useful for self-hosted environments, local development proxies, or testing.
options.timeout optional number Request timeout in milliseconds. Defaults to 30000 (30 seconds). Set higher for providers with slow response times.

bridge.execute() #

Execute any tool on any connected provider. This is the primary method you will use.

typescript — signature 
bridge.execute(params: ExecuteParams): Promise<ExecuteResult>
tool required string Either a bare tool name (e.g. "create_issue") paired with provider, or a combined "provider.tool" string (e.g. "github.create_issue") with no provider needed.
provider optional string Provider slug: "notion", "slack", "github", "google-drive", "gmail". Omit when using the "provider.tool" shorthand in tool.
params optional Record<string, unknown> Tool-specific parameters. See the Integrations docs for per-provider schemas.

Both calling styles are supported:

typescript — execute calling styles 
// Shorthand: provider.tool in a single field (recommended for agent routing)
await bridge.execute({
  tool: "github.create_issue",
  params: { repo: "acme/backend", title: "Fix memory leak" },
});

// Explicit: provider and tool as separate fields (backwards compatible)
await bridge.execute({
  provider: "github",
  tool:     "create_issue",
  params:   { repo: "acme/backend", title: "Fix memory leak" },
});

bridge.getTools() #

Returns a sorted list of every tool across all providers as provider.tool strings. Ideal for populating an agent's tool list or building a UI tool-picker without needing to query each provider separately.

typescript — signature 
bridge.getTools(): Promise<string[]>
typescript — example 
const tools = await bridge.getTools();
// [
//   { name: "github.create_issue", description: "Create a new issue in a GitHub repository" },
//   { name: "gmail.send_email",    description: "Send an email via Gmail" },
//   { name: "notion.create_page",  description: "Create a new page in Notion" },
//   { name: "slack.send_message",  description: "Send a message to a Slack channel" },
//   ...
// ]

// Pass descriptions to the LLM, then execute by name — no parsing needed
const chosen = tools.find(t => t.name.startsWith('github'));
await bridge.execute({ tool: chosen!.name, params: { repo: "acme/api", title: "Bug" } });

Other Methods #

bridge.integrations.list() #

List all integrations (connected providers) for the authenticated user.

typescript 
const integrations = await bridge.integrations.list();
// Returns: Integration[]
// [{ id: '...', provider: 'notion', status: 'active', connectedAt: '...' }]

bridge.logs.list() #

Retrieve paginated execution logs for the authenticated user.

typescript 
const logs = await bridge.logs.list({ page: 1, limit: 20 });
// Returns: PaginatedResponse<ExecutionLog[]>

console.log(logs.total);    // 84
console.log(logs.data[0]);  // { id, provider, tool, status, latencyMs, createdAt }

bridge.apiKeys methods #

Manage API keys programmatically. Requires admin scope.

typescript 
// List all API keys (returns metadata only, not the key value)
const keys = await bridge.apiKeys.list();
// [{ id, name, prefix: 'ab_live_aBcD...', scope, createdAt }]

// Create a new API key — the full key is in the response
const newKey = await bridge.apiKeys.create({
  name:  'prod-agent-v2',
  scope: 'write',
});
console.log(newKey.key); // ab_live_... — save this immediately!

// Delete (revoke) an API key by its ID
await bridge.apiKeys.delete('key_01HXZ...');
// Subsequent requests with the deleted key return 401

TypeScript Interfaces #

The SDK ships with full TypeScript type definitions. Here are the core interfaces:

typescript — type definitions 
interface AgentBridgeOptions {
  baseUrl?: string;  // Default: 'https://api.agentbridge.in'
  timeout?: number;  // Default: 30000 (ms)
}

interface ExecuteParams {
  tool:      string;  // bare name or "provider.tool" shorthand
  provider?: string;  // omit when using "provider.tool" in tool
  params:   Record<string, unknown>;
}

interface ExecuteResult {
  status:      'success' | 'error';
  data:        Record<string, unknown>;
  latencyMs:   number;
  executionId: string;
}

interface Integration {
  id:          string;
  provider:    string;
  status:      'active' | 'disconnected';
  connectedAt: string; // ISO 8601
}

interface ExecutionLog {
  id:        string;
  provider:  string;
  tool:      string;
  status:    'success' | 'error';
  latencyMs: number;
  createdAt: string; // ISO 8601
}

interface ApiKey {
  id:        string;
  name:      string;
  prefix:    string;  // e.g. 'ab_live_aBcD...'
  scope:     'read' | 'write' | 'admin';
  createdAt: string;
}

interface PaginatedResponse<T> {
  data:  T;
  total: number;
  page:  number;
  limit: number;
}

class AgentBridgeError extends Error {
  statusCode:     number;
  error:          string;
  providerError?: Record<string, unknown>;
}

Error Handling #

The SDK throws an AgentBridgeError on any non-2xx response. Wrap calls in a try/catch block to handle errors gracefully:

typescript 
import { AgentBridge, AgentBridgeError } from 'agentbridge-sdk';

const bridge = new AgentBridge(process.env.AGENTBRIDGE_API_KEY!);

try {
  const result = await bridge.execute({
    provider: 'notion',
    tool:     'create_page',
    params:   { parent_id: 'bad-id', title: 'Test' },
  });
  console.log('Created:', result.data);
} catch (err) {
  if (err instanceof AgentBridgeError) {
    console.error('Status:', err.statusCode);         // 422
    console.error('Message:', err.message);           // "Provider returned an error"
    console.error('Provider:', err.providerError);    // { object: 'error', code: '...' }

    if (err.statusCode === 429) {
      console.warn('Rate limited. Retry after backoff.');
    }
  } else {
    // Network error, timeout, or unexpected exception
    throw err;
  }
}
err.statusCode number HTTP status code returned by AgentBridge (e.g. 400, 401, 403, 404, 422, 429, 500).
err.message string Human-readable error message from AgentBridge.
err.error string HTTP status text (e.g. "Unauthorized", "Unprocessable Entity").
err.providerError object | undefined Raw error from the upstream provider. Only present on 422 responses. Shape varies by provider.

Usage with Vercel AI SDK #

Use AgentBridge as a tool handler in the Vercel AI SDK's tool() pattern. This lets your AI model call AgentBridge tools naturally during a conversation:

typescript — Vercel AI SDK integration 
import { openai }     from '@ai-sdk/openai';
import { generateText, tool } from 'ai';
import { AgentBridge } from 'agentbridge-sdk';
import { z } from 'zod';

const bridge = new AgentBridge(process.env.AGENTBRIDGE_API_KEY!);

const { text } = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Create a Notion page titled "Weekly Standup" in my workspace.',
  tools: {
    createNotionPage: tool({
      description: 'Creates a new page in the user\'s Notion workspace',
      parameters: z.object({
        parent_id: z.string().describe('Parent page or database ID'),
        title:     z.string().describe('Page title'),
      }),
      execute: async ({ parent_id, title }) => {
        const result = await bridge.execute({
          provider: 'notion',
          tool:     'create_page',
          params:   { parent_id, title },
        });
        return result.data;
      },
    }),
    sendSlackMessage: tool({
      description: 'Sends a message to a Slack channel',
      parameters: z.object({
        channel: z.string().describe('Slack channel ID'),
        text:    z.string().describe('Message text'),
      }),
      execute: async ({ channel, text }) => {
        const result = await bridge.execute({
          provider: 'slack',
          tool:     'send_message',
          params:   { channel, text },
        });
        return result.data;
      },
    }),
  },
});

Usage with LangChain #

Wrap AgentBridge tools as LangChain DynamicStructuredTool instances for use with any LangChain agent:

typescript — LangChain integration 
import { DynamicStructuredTool } from 'langchain/tools';
import { AgentBridge } from 'agentbridge-sdk';
import { z } from 'zod';

const bridge = new AgentBridge(process.env.AGENTBRIDGE_API_KEY!);

const slackTool = new DynamicStructuredTool({
  name: 'send_slack_message',
  description: 'Send a message to a Slack channel via AgentBridge',
  schema: z.object({
    channel: z.string().describe('Slack channel ID (e.g. C012AB3CD)'),
    text:    z.string().describe('Message text to send'),
  }),
  func: async ({ channel, text }) => {
    const result = await bridge.execute({
      provider: 'slack',
      tool:     'send_message',
      params:   { channel, text },
    });
    return JSON.stringify(result.data);
  },
});

const githubTool = new DynamicStructuredTool({
  name: 'create_github_issue',
  description: 'Create a new issue in a GitHub repository',
  schema: z.object({
    repo:   z.string().describe('Repository in owner/repo format'),
    title:  z.string().describe('Issue title'),
    body:   z.string().optional().describe('Issue body (markdown)'),
    labels: z.array(z.string()).optional().describe('Labels to apply'),
  }),
  func: async ({ repo, title, body, labels }) => {
    const result = await bridge.execute({
      provider: 'github',
      tool:     'create_issue',
      params:   { repo, title, body, labels },
    });
    return JSON.stringify(result.data);
  },
});

// Use with any LangChain agent:
// const agent = createOpenAIFunctionsAgent({ llm, tools: [slackTool, githubTool], prompt });