agentforge-sdk

Official TypeScript SDK for the AgentForge AI Agent Tool Marketplace.

Discover, execute, and manage AI tools from a unified API. Zero dependencies -- uses the built-in fetch API (Node 18+).

Install

npm install agentforge-sdk

Quick Start

import { AgentForge } from 'agentforge-sdk';

const agent = new AgentForge({ apiKey: 'agf_agent_...' });
const tools = await agent.discover({ intent: 'translate text to French' });
const result = await agent.execute(tools.tools[0].id, { text: 'Hello', target: 'fr' });
console.log(result.data);

Features

• Tool Discovery -- search by intent, category, protocol, tags, or price
• Schema Retrieval -- get function-calling compatible schemas for any tool
• Execution -- call any tool with typed parameters and get structured results
• Batch Execution -- run up to 10 tool calls in a single request
• LRU Cache -- built-in cache with configurable TTL for schemas and discovery
• Retry with Backoff -- exponential backoff with jitter, configurable per-call
• Rate Limit Awareness -- parses X-RateLimit-* headers and throttles proactively
• Circuit Breaker -- check tool health before calling unreliable endpoints
• Billing -- check balance, deposit funds, view transaction history
• Zero Dependencies -- uses native fetch and AbortController (Node 18+)

Configuration

const agent = new AgentForge({
  apiKey: 'agf_agent_...',
  baseUrl: 'https://api.agentforge.markets',  // default
  timeout: 30_000,                          // default: 30s
  retry: {
    maxRetries: 3,
    baseDelayMs: 1000,
    maxDelayMs: 10_000,
    jitter: true,
  },
  cache: {
    maxEntries: 100,
    ttlMs: 300_000,       // 5 min for discovery
    schemaTtlMs: 600_000, // 10 min for schemas
  },
});

Disable retry or cache by passing false:

const agent = new AgentForge({ apiKey: '...', retry: false, cache: false });

API Reference

Discovery

const result = await agent.discover({ intent: 'summarize a webpage' });
const cheap = await agent.discover({ category: 'nlp', maxPrice: 0.01 });
const page = await agent.listTools({ limit: 20, offset: 0 });
const schema = await agent.getToolSchema('tool-uuid');

Execution

const result = await agent.execute('tool-uuid', { text: 'Hello world' });

// Batch execution (up to 10 calls)
const batch = await agent.executeBatch([
  { toolId: 'tool-1', parameters: { query: 'AI news' } },
  { toolId: 'tool-2', parameters: { url: 'https://example.com' } },
]);

Billing

const balance = await agent.getBalance();
await agent.deposit(10.00);
const history = await agent.getHistory(20);

Health Check

const health = await agent.checkHealth('tool-uuid');
// health.status: 'CLOSED' (healthy) | 'OPEN' (failing) | 'HALF_OPEN' (testing)

Error Handling

import { AgentForgeError } from 'agentforge-sdk';

try {
  await agent.execute('tool-uuid', { text: 'test' });
} catch (err) {
  if (err instanceof AgentForgeError) {
    console.error(err.code);       // 'INSUFFICIENT_FUNDS', 'TIMEOUT', etc.
    console.error(err.statusCode);  // HTTP status code
    console.error(err.retryable);   // whether the SDK would auto-retry
  }
}

Error Codes

| Code | HTTP | Description | |-----------------------|------|---------------------------------------| | UNAUTHORIZED | 401 | Invalid or missing API key | | FORBIDDEN | 403 | Insufficient permissions | | NOT_FOUND | 404 | Tool or resource not found | | INSUFFICIENT_FUNDS | 402 | Agent balance too low | | VALIDATION_ERROR | 400 | Invalid request parameters | | RATE_LIMITED | 429 | Too many requests | | TIMEOUT | -- | Request exceeded timeout | | NETWORK_ERROR | -- | Connection failure | | SERVER_ERROR | 5xx | AgentForge server error | | CIRCUIT_OPEN | 503 | Tool endpoint failing (circuit open) |

Use with LLMs

The SDK is designed for LLM function-calling workflows. Discover tools, convert schemas to function definitions, and execute the tool the LLM selects:

import Anthropic from '@anthropic-ai/sdk';
import { AgentForge } from 'agentforge-sdk';

const anthropic = new Anthropic();
const forge = new AgentForge({ apiKey: 'agf_agent_...' });

const discovered = await forge.discover({ intent: userMessage });
const tools = await Promise.all(
  discovered.tools.slice(0, 5).map(async (t) => {
    const schema = await forge.getToolSchema(t.id);
    return {
      name: schema.function.name,
      description: schema.function.description,
      input_schema: schema.function.parameters,
    };
  })
);

const response = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  tools,
  messages: [{ role: 'user', content: userMessage }],
});

Full Documentation

Visit agentforge.markets/docs for the complete API reference, guides, and examples.

License

MIT