Agent API TypeScript SDK

Official, zero-runtime-dependency TypeScript/JavaScript client for the Byteflyo Agent API.

This SDK implements the stable customer subset of the Anthropic-compatible OpenAPI contract. It provides fully-typed models, messages, Server-Sent Events (SSE) streaming, cooperative cancellation, timeouts, and bounded retries.

• Fast & Lightweight: Zero external runtime dependencies. Built on native fetch and Web Streams.
• Secure: Completely prevents logging of API keys, request content, and raw HTTP response bodies.
• Isomorphic: Runs in Node.js 20+, Edge environments, and the browser.

📦 Install

npm install @byteflyo-agent/sdk

🚀 Quick Start

import { AgentApi, apiKey } from "@byteflyo-agent/sdk";

// 1. Initialize the client
const client = new AgentApi({
  apiKey: apiKey(process.env.API_KEY!),
  // baseUrl defaults to https://aiagent-backend.byteflyo.com
});

// 2. Discover available models
const models = await client.listModels();
console.log("Using model:", models.items[0]?.name);

// 3. Send a message
const response = await client.sendMessage({
  model: models.items[0]!.name,
  max_tokens: 256,
  messages: [{ role: "user", content: "Hello, world!" }],
});

console.log(response.content);

⚡ Streaming

The SDK supports parsing Anthropic-compatible Server-Sent Events (SSE).

streamMessage() returns an iterable stream and also supports an onEvent callback. Iteration automatically handles backpressure.

const abortController = new AbortController();

const stream = client.streamMessage(
  {
    model: "claude-opus-5",
    max_tokens: 128,
    messages: [{ role: "user", content: "Write a poem about the sea." }],
  },
  {
    signal: abortController.signal, // For cancellation
  },
);

for await (const event of stream) {
  if (
    event.type === "content_block_delta" &&
    event.delta.type === "text_delta"
  ) {
    process.stdout.write(event.delta.text);
  }

  if (event.type === "message_stop") {
    break;
  }
}

🛡️ Reliability & Errors

Bounded Retries

To ensure idempotent safety and prevent accidental double-billing, message POST requests and active streams are never automatically retried.

However, safe requests like GET /v1/account/models will automatically retry on transient network failures, timeouts, and HTTP status codes 408, 429, 500, 502, 503, and 504. Retries use capped exponential backoff and respect HTTP Retry-After headers.

You can configure retry limits (default 2, max 5):

const client = new AgentApi({
  apiKey: apiKey("..."),
  maxRetries: 3,
  timeoutMs: 30_000,
});

Typed Error Handling

All errors thrown by the SDK are structured and extend from native Error:

• AgentApiError: Server returned a structured HTTP API error (e.g., Auth, Rate Limit). Contains status, type, code, and requestId.
• AgentApiStreamError: Stream cleanly parsed a terminal error event sent from the server mid-generation.
• AgentApiTimeoutError: Request exceeded timeoutMs.
• AgentApiConnectionError: Network failure, DNS issue, or unparseable JSON/SSE.

🔗 Links

• Documentation: TypeScript SDK API Reference
• Examples: examples/
• Source Code: GitHub Repository

(Note: Replace the GitHub URL above with your actual repository URL before finalizing).