> ## 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.

# Introduction

> Monitor, debug, and improve your AI agents with Foil

# Welcome to Foil

Foil is an observability platform purpose-built for AI applications. Get complete visibility into your LLM calls, agent workflows, and AI pipelines with distributed tracing, real-time alerting, and actionable analytics.

## Why Foil?

Building AI applications is hard. Debugging them is harder. Foil gives you the tools to understand what your AI is doing, why it's failing, and how to make it better.

<CardGroup cols={2}>
  <Card title="Distributed Tracing" icon="diagram-project">
    Track every LLM call, tool execution, and agent step with full context and parent-child relationships.
  </Card>

  <Card title="Real-time Alerting" icon="bell">
    Get notified instantly when your AI hallucinates, gets stuck, or produces low-quality outputs.
  </Card>

  <Card title="Cost Analytics" icon="chart-line">
    Monitor token usage, latency, and costs across all your models and agents.
  </Card>

  <Card title="Custom Signals" icon="signal">
    Track user feedback, quality scores, and custom metrics tied to your traces.
  </Card>
</CardGroup>

## How It Works

Choose the integration method that works best for you:

<Tabs>
  <Tab title="Recommended">
    Full tracing with nested span trees — works with **any LLM provider**.

    <Steps>
      <Step title="Install the SDK">
        ```bash theme={null}
        npm install @getfoil/foil-js
        ```
      </Step>

      <Step title="Instrument Your Code">
        Wrap your AI calls with `foil.trace()` and use `ctx.llmCall()` for LLM spans.

        ```javascript theme={null}
        const { Foil } = require('@getfoil/foil-js');
        const OpenAI = require('openai');

        const foil = new Foil({
          apiKey: process.env.FOIL_API_KEY,
          agentName: 'my-agent',
        });
        const openai = new OpenAI();

        const toolMap = {
          search: async (args) => searchAPI(args.query),
        };

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

          // LLM call with function calling
          let response = await ctx.llmCall('gpt-4o', async () => {
            return 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 ctx.llmCall('gpt-4o', async () => {
              return await openai.chat.completions.create({
                model: 'gpt-4o', messages, tools,
              });
            });
          }
        }, { name: 'search-agent' });

        await foil.shutdown();
        ```
      </Step>

      <Step title="View in Dashboard">
        See your traces, metrics, and alerts in the Foil dashboard.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Auto-Instrumentation">
    Zero-code tracing for OpenAI, Anthropic, and other supported providers.

    <Steps>
      <Step title="Install the SDK">
        ```bash theme={null}
        npm install @getfoil/foil-js
        ```
      </Step>

      <Step title="Initialize Foil">
        Pass `instrumentModules` to auto-trace LLM calls. Use `ctx.executeTools()` for agentic tool calling.

        ```javascript theme={null}
        const OpenAI = require('openai');
        const { Foil } = require('@getfoil/foil-js');

        const foil = new Foil({
          apiKey: process.env.FOIL_API_KEY,
          agentName: 'my-agent',
          instrumentModules: { openAI: OpenAI },
        });

        const openai = new OpenAI();
        const toolMap = { search: async (args) => searchAPI(args.query) };

        await foil.trace(async (ctx) => {
          const messages = [{ role: 'user', content: 'Search for recent AI news' }];
          let response = await openai.chat.completions.create({
            model: 'gpt-4o', messages, tools,
          });

          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,
            });
          }
        }, { name: 'search-agent' });
        ```
      </Step>

      <Step title="View in Dashboard">
        See your traces, metrics, and alerts in the Foil dashboard.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Features

### Traces & Spans

Every AI interaction is captured as a **trace** containing multiple **spans**. Spans represent individual operations like LLM calls, tool executions, or retrieval steps. Foil automatically tracks:

* Input and output content
* Token usage (prompt, completion, total)
* Latency and time-to-first-token
* Errors and status codes
* Custom metadata

### Intelligent Alerting

Foil uses LLM analysis to detect issues that traditional monitoring misses:

**Content Evaluations:**

* **Hallucination Detection** - Identifies fabricated facts, fake entities, made-up citations
* **Quality Analysis** - Catches off-topic, unhelpful, or incoherent responses
* **Loop Detection** - Alerts when agents get stuck repeating themselves
* **Satisfaction Analysis** - Detects responses likely to leave users unsatisfied
* **Frustration Detection** - Identifies user frustration signals in conversations
* **Content Safety** - Flags inappropriate, explicit, or harmful content

**Security Evaluations:**

* **Prompt Injection** - Detects attempts to override instructions or extract system prompts
* **PII Leakage** - Identifies exposed personal data (SSN, credit cards, phone numbers)
* **Jailbreak Detection** - Catches bypass attempts like DAN, roleplay exploits

### Signals & Feedback

Capture user feedback and custom metrics directly tied to your traces:

* Thumbs up/down ratings
* Star ratings
* Sentiment analysis
* Goal completion tracking
* Custom metrics

## Quick Links

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get up and running in 5 minutes
  </Card>

  <Card title="Auto-Instrumentation" icon="circle-nodes" href="/sdks/javascript/index#auto-instrumentation">
    Zero-code auto-instrumentation
  </Card>

  <Card title="JavaScript SDK" icon="js" href="/sdks/javascript/index">
    Full-featured SDK with tracing support
  </Card>

  <Card title="Python SDK" icon="python" href="/sdks/python/index">
    Lightweight SDK for Python apps
  </Card>
</CardGroup>