> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getfoil.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Overview

> Choose the right Foil SDK for your project

# 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

| Feature                  | JavaScript | Python |
| ------------------------ | ---------- | ------ |
| Basic Logging            | Yes        | Yes    |
| OpenAI Wrapper           | Yes        | Yes    |
| OpenAI Agents SDK        | Yes        | Yes    |
| Distributed Tracing      | Yes        | Yes    |
| Automatic Span Hierarchy | Yes        | Yes    |
| Vercel AI Integration    | Yes        | -      |
| Tool Call Tracking       | Yes        | Yes    |
| Signal Recording         | Yes        | Yes    |
| Streaming Support        | Yes        | Yes    |
| Multimodal / Media       | Yes        | Yes    |

<Tip>
  **Examples**: Browse complete, runnable examples for both SDKs at [github.com/getfoil/foil-examples](https://github.com/getfoil/foil-examples).
</Tip>

## 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
* Vercel AI integration

```bash theme={null}
npm install @getfoil/foil-js
```

<Card title="JavaScript SDK Docs" icon="js" href="/sdks/javascript/index">
  Complete JavaScript SDK documentation
</Card>

### Key Features

**Foil** - High-level tracing API with automatic span management:

```javascript theme={null}
import { Foil } from '@getfoil/foil-js';

const foil = new Foil({
  apiKey: 'your-api-key',
  agentName: 'my-agent',
  instrumentModules: { openAI: OpenAI },
});

await foil.trace(async (ctx) => {
  const messages = [{ role: 'user', content: 'Search for recent news' }];

  // LLM calls are auto-instrumented
  let response = await openai.chat.completions.create({
    model: 'gpt-4o', messages, tools,
  });

  // Agentic loop — LLM decides which tools to call
  while (response.choices[0].message.tool_calls) {
    const toolMessages = await ctx.executeTools(response, toolMap);
    messages.push(response.choices[0].message, ...toolMessages);
    response = await openai.chat.completions.create({
      model: 'gpt-4o', messages, tools,
    });
  }

  return response.choices[0].message.content;
});
```

**Framework Integrations:**

```javascript theme={null}
// Vercel AI SDK
import { createVercelAICallbacks } from '@getfoil/foil-js';
const callbacks = createVercelAICallbacks(tracer);
```

## Python SDK

The Python SDK provides tracing, logging, and feedback collection for Python applications, with automatic OpenAI instrumentation.

**Best for:**

* Python backend services
* FastAPI/Flask applications
* Jupyter notebooks
* LLM integrations

```bash theme={null}
pip install foil-sdk
```

<Card title="Python SDK Docs" icon="python" href="/sdks/python/index">
  Complete Python SDK documentation
</Card>

### Key Features

**Foil** - High-level tracing API with automatic span management:

```python theme={null}
from foil import Foil

foil = Foil(
    api_key='your-api-key',
    agent_name='my-agent',
)

def my_workflow(ctx):
    result = ctx.llm_call('gpt-4o', lambda _: openai.chat.completions.create(
        model='gpt-4o',
        messages=[{'role': 'user', 'content': 'Hello!'}],
    ))

    data = ctx.tool('search', lambda _: search_api(query))
    return result.choices[0].message.content

foil.trace(my_workflow, name='my-trace')
```

**OpenAI Wrapper** - Automatic tracing for all OpenAI calls:

```python theme={null}
from openai import OpenAI
from foil import Foil

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

wrapped = foil.wrap_openai(client)
response = wrapped.chat.completions.create(
    model='gpt-4o',
    messages=[{'role': 'user', 'content': 'Hello!'}]
)
```

## Authentication

Both SDKs use API key authentication. Get your API key from the [Foil Dashboard](https://app.getfoil.ai).

```bash theme={null}
# Environment variable (recommended)
export FOIL_API_KEY=sk_live_xxx_yyy
```

<Warning>
  Never commit API keys to version control. Use environment variables or a secrets manager.
</Warning>

## Debug Mode

Enable debug logging to troubleshoot integration issues:

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    const foil = new Foil({
      apiKey: 'your-api-key',
      agentName: 'my-agent',
      debug: true,  // or set FOIL_DEBUG=true
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    foil = Foil(
        api_key='your-api-key',
        agent_name='my-agent',
        debug=True,  # or set FOIL_DEBUG=true
    )
    ```
  </Tab>
</Tabs>