Skip to main content

​
SDK Overview

Foil provides official SDKs for JavaScript and Python. Both SDKs offer core functionality for tracing, logging, and feedback collection, with the JavaScript SDK providing additional features for complex agent workflows.

​
Feature Comparison

FeatureJavaScriptPython
Basic LoggingYesYes
OpenAI WrapperYesYes
Distributed TracingYes-
Automatic Span HierarchyYes-
LangChain IntegrationYes-
Vercel AI IntegrationYes-
Tool Call TrackingYesYes
Signal RecordingYes-
Streaming SupportYesYes

​
JavaScript SDK

The JavaScript SDK is our most full-featured SDK, designed for complex AI applications with multiple agents, tools, and nested workflows. Best for:
  • Node.js backend services
  • Next.js applications
  • Complex agent architectures
  • LangChain and Vercel AI integrations
npm install @foil-ai/sdk

JavaScript SDK Docs

Complete JavaScript SDK documentation

​
Key Features

FoilTracer - High-level tracing API with automatic span management: 
import { createFoilTracer, SpanKind } from '@foil-ai/sdk';

const tracer = createFoilTracer({
  apiKey: 'your-api-key',
  agentName: 'my-agent'
});

await tracer.trace(async (ctx) => {
  // Automatic parent-child span relationships
  await ctx.tool('search', async () => {
    return await searchAPI(query);
  });

  const span = await ctx.startSpan(SpanKind.LLM, 'gpt-4o');
  // ... LLM call
  await span.end({ output, tokens });
});
Framework Integrations: 
// LangChain
import { createLangChainCallback } from '@foil-ai/sdk';
const callbacks = createLangChainCallback(tracer);

// Vercel AI SDK
import { createVercelAICallbacks } from '@foil-ai/sdk';
const callbacks = createVercelAICallbacks(tracer);

​
Python SDK

The Python SDK provides a lightweight interface for logging in Python applications, with automatic OpenAI instrumentation. Best for:
  • Python backend services
  • FastAPI/Flask applications
  • Jupyter notebooks
  • Simple LLM integrations
pip install foil-sdk

Python SDK Docs

Complete Python SDK documentation

​
Key Features

OpenAI Wrapper - Automatic tracing for all OpenAI calls: 
from openai import OpenAI
from foil import Foil

client = OpenAI()
foil = Foil(api_key='your-api-key')

# Automatic tracing for all calls
wrapped = foil.wrap_openai(client)
response = wrapped.chat.completions.create(
    model='gpt-4o',
    messages=[{'role': 'user', 'content': 'Hello!'}]
)
Fire-and-Forget Logging: 
foil.log({
    'model': 'gpt-4o',
    'input': messages,
    'output': response,
    'latency': 1200,
    'tokens': {'prompt': 100, 'completion': 50}
})

​
Authentication

Both SDKs use API key authentication. Get your API key from the Foil Dashboard. 
# Environment variable (recommended)
export FOIL_API_KEY=sk_live_xxx_yyy
Never commit API keys to version control. Use environment variables or a secrets manager.

​
Base URL Configuration

By default, SDKs connect to the Foil cloud API. For self-hosted deployments: 
const tracer = createFoilTracer({
  apiKey: 'your-api-key',
  agentName: 'my-agent',
  baseUrl: 'https://your-foil-instance.com/api'
});

​
Debug Mode

Enable debug logging to troubleshoot integration issues: 
const tracer = createFoilTracer({
  apiKey: 'your-api-key',
  agentName: 'my-agent',
  debug: true  // or set FOIL_DEBUG=true
});