Documentation

Quick start

pip install farol-sdk

python -m venv venv
source venv/bin/activate  # Mac/Linux
venv\Scripts\activate     # Windows
pip install farol-sdk

from farol import trace
from anthropic import Anthropic

client = Anthropic()

@trace(agent_name="my-agent", farol_key="frl_your_key_here")
def my_agent(task, *, run):
    run["topic"] = task

    response = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": task}]
    )
    run["input_tokens"] = response.usage.input_tokens
    run["output_tokens"] = response.usage.output_tokens
    return response.content[0].text

from farol import trace
import httpx

@trace(agent_name="my-agent", farol_key="frl_your_key_here")
def my_agent(task, *, run):
    run["topic"] = task

    response = httpx.post(
        "https://api.anthropic.com/v1/messages",
        headers={
            "x-api-key": "your-anthropic-key",
            "anthropic-version": "2023-06-01"
        },
        json={
            "model": "claude-haiku-4-5",
            "max_tokens": 1024,
            "messages": [{"role": "user", "content": task}]
        }
    ).json()
    run["input_tokens"] = response["usage"]["input_tokens"]
    run["output_tokens"] = response["usage"]["output_tokens"]
    return response["content"][0]["text"]

from farol import trace
from openai import OpenAI

client = OpenAI(
    api_key="your-openai-key"
)

@trace(agent_name="my-agent", farol_key="frl_your_key_here")
def my_agent(task, *, run):
    run["topic"] = task

    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": task}]
    )
    run["input_tokens"] = response.usage.prompt_tokens
    run["output_tokens"] = response.usage.completion_tokens
    return response.choices[0].message.content

from farol import trace
import google.generativeai as genai

genai.configure(api_key="your-gemini-key")
model = genai.GenerativeModel("gemini-1.5-flash")

@trace(agent_name="my-agent", farol_key="frl_your_key_here")
def my_agent(task, *, run):
    run["topic"] = task

    response = model.generate_content(task)
    run["input_tokens"] = response.usage_metadata.prompt_token_count
    run["output_tokens"] = response.usage_metadata.candidates_token_count
    return response.text

from farol import trace
from mistralai import Mistral

client = Mistral(api_key="your-mistral-key")

@trace(agent_name="my-agent", farol_key="frl_your_key_here")
def my_agent(task, *, run):
    run["topic"] = task

    response = client.chat.complete(
        model="mistral-small-latest",
        messages=[{"role": "user", "content": task}]
    )
    run["input_tokens"] = response.usage.prompt_tokens
    run["output_tokens"] = response.usage.completion_tokens
    return response.choices[0].message.content

from farol import trace
from openai import OpenAI

client = OpenAI(
    api_key="your-xai-key",
    base_url="https://api.x.ai/v1"
)

@trace(agent_name="my-agent", farol_key="frl_your_key_here")
def my_agent(task, *, run):
    run["topic"] = task

    response = client.chat.completions.create(
        model="grok-3-mini",
        messages=[{"role": "user", "content": task}]
    )
    run["input_tokens"] = response.usage.prompt_tokens
    run["output_tokens"] = response.usage.completion_tokens
    return response.choices[0].message.content

import { trace } from '@usefarol/sdk';

const myAgent = trace(
  async (run, task: string) => {
    run.topic = task;

    const span = run.startSpan('llm_call', { type: 'llm' });
    try {
      // call your LLM here (Anthropic, OpenAI, Gemini, etc.)
      const response = await yourLlm.call(task);
      span.inputTokens = response.usage.input_tokens;
      span.outputTokens = response.usage.output_tokens;
      run.inputTokens += response.usage.input_tokens;
      run.outputTokens += response.usage.output_tokens;
      span.end();
      return response.text;
    } catch (e) {
      span.end(e instanceof Error ? e : new Error(String(e)));
      throw e;
    }
  },
  {
    agentName: 'my-agent',
    farolKey: 'frl_your_key_here',
  }
);

const result = await myAgent('your task here');

# Just call your function as usual — Farol tracks everything automatically
result = my_agent("your task here")

Webhook integrations

On Builder plans and above (see pricing), you can add a webhook URL in Account settings. Farol sends a JSON POST when a cost anomaly is detected. Use the steps below to wire common destinations.

Farol sends this JSON payload to your webhook URL when a cost anomaly is detected:

{
  "event": "cost_anomaly",
  "agent": "research-agent",
  "topic": "Weekly data pipeline run",
  "reason": "Cost 3.2× above median baseline (median: $0.000078, actual: $0.000248)",
  "cost_usd": 0.000248,
  "timestamp": "2026-04-12T10:00:00.000Z",
  "dashboard": "https://usefarol.dev/app"
}

Farol expects a 2xx response. Failed deliveries are logged in Account settings.

SDK reference

Node.js SDK — Install with npm install @usefarol/sdk. Full TypeScript support. See npmjs.com/package/@usefarol/sdk.

Python’s trace decorator injects a run dict for tokens, timing, and optional steps. The Node SDK’s trace() wraps an async function and passes a Run object with startSpan (see below).

Python @trace parameters

Node.js trace() options

# Prices vary by model — check your provider's pricing page
@trace(
    agent_name="my-agent",
    farol_key="frl_your_key_here",
    cost_per_1k_input_tokens=0.00025,   # Claude Haiku input price
    cost_per_1k_output_tokens=0.00125,  # Claude Haiku output price
)

Spans — Node.js (run.startSpan)

Use run.startSpan(name, { type, metadata }) for tool calls, LLM calls, and other steps. Call span.end() (or span.end(err)) when finished.

const search = run.startSpan('web_search', { type: 'tool', metadata: { url } });
const result = await searchWeb(url);
search.end();

const llm = run.startSpan('llm_call', { type: 'llm' });
try {
  const response = await llmClient.call(prompt);
  llm.inputTokens = response.usage.input_tokens;
  llm.outputTokens = response.usage.output_tokens;
  llm.input = prompt;       // only sent when captureIo: true
  llm.output = response.text;
  llm.end();
} catch (e) {
  llm.end(e instanceof Error ? e : new Error(String(e)));
  throw e;
}

Note: Farol currently supports sequential spans best. Parallel or concurrent spans may not display in the correct order in the trace timeline. Full parallel span support is on the roadmap.

Python — run dict (no run.span)

The Python package passes run as a plain dict. There is no run.span() helper and no capture_io / ingest-url options on @trace. Set run["input_tokens"], run["output_tokens"], run["topic"], etc., and optionally append step summaries to run["steps"] (list of objects, e.g. {"step": "llm_call"}). Use the Node SDK or OpenTelemetry if you need per-span rows in the dashboard.

@trace(agent_name="my-agent", farol_key="frl_your_key_here")
def my_agent(task, *, run):
    run["topic"] = task
    response = llm.call(task)
    run["input_tokens"] = response.usage.input_tokens
    run["output_tokens"] = response.usage.output_tokens
    run["steps"].append({"step": "llm_call"})
    return response.text

Multi-agent tracing

Child agent runs are linked to their parent automatically. When a traced function calls another traced function on the same thread (Python) or within the same async chain (Node), the child run’s parent_trace_id is set from the parent run’s ID so you can reconstruct the full pipeline in Farol. You can still pass parent_trace_id on the decorator to force a specific parent when needed.

@trace(agent_name="research-agent", farol_key="frl_...")
def research_agent(topic, *, run):
    run["topic"] = topic
    # calling market_agent inside here automatically links it
    result = market_agent(topic)
    return result


@trace(agent_name="market-agent", farol_key="frl_...")
def market_agent(topic, *, run):
    run["topic"] = topic
    # parent_trace_id is set automatically
    # do market analysis...

Auto-propagation uses Python’s contextvars (async-safe). Set propagate=False on @trace to disable. Manual parent_trace_id always takes precedence.

In the dashboard, parent runs show their spawned children and total pipeline cost. Child runs show a link back to the parent.

Framework integrations

Farol works with any Python or Node.js framework — wrap your agent’s entrypoint function with @trace and Farol tracks everything automatically. No special integration required.

LangChain observability

Wrap the function that invokes your LangChain chain or agent:

from farol import trace
from langchain.chains import LLMChain

@trace(agent_name="langchain-agent", farol_key="frl_your_key_here")
def run_chain(query, *, run):
    run["topic"] = query

    result = chain.invoke({"query": query})
    run["steps"].append({"step": "chain_invoke"})
    return result

result = run_chain("summarise last quarter earnings")

CrewAI monitoring

Wrap the crew kickoff to track the entire crew run as one traced agent:

from farol import trace
from crewai import Crew

@trace(agent_name="crewai-agent", farol_key="frl_your_key_here")
def run_crew(topic, *, run):
    run["topic"] = topic

    result = crew.kickoff(inputs={"topic": topic})
    run["steps"].append({"step": "crew_kickoff"})
    return result

result = run_crew("market analysis for Q2 2026")

Vercel AI SDK (Node.js)

Wrap the function that calls generateText or streamText:

import { trace } from '@usefarol/sdk';
import { generateText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';

const runAgent = trace(
  async (run, prompt: string) => {
    run.topic = prompt;

    const span = run.startSpan('generate', { type: 'llm' });
    try {
      const { text, usage } = await generateText({
        model: anthropic('claude-haiku-4-5'),
        prompt,
      });
      span.inputTokens = usage.promptTokens;
      span.outputTokens = usage.completionTokens;
      span.end();
      return text;
    } catch (e) {
      span.end(e instanceof Error ? e : new Error(String(e)));
      throw e;
    }
  },
  { agentName: 'vercel-ai-agent', farolKey: 'frl_your_key_here' }
);

Cursor SDK (Node.js)

Wrap Cursor agent runs to track cost, duration, and errors automatically:

import { trace } from '@usefarol/sdk';
import { CursorClient } from '@cursor/sdk';

const client = new CursorClient({ apiKey: process.env.CURSOR_API_KEY });

const runAgent = trace(
  async (run, prompt: string) => {
    run.topic = prompt;

    const span = run.startSpan('cursor_agent', { type: 'tool' });
    try {
      const result = await client.agent.run({ prompt });
      span.end();
      return result;
    } catch (e) {
      span.end(e instanceof Error ? e : new Error(String(e)));
      throw e;
    }
  },
  { agentName: 'cursor-agent', farolKey: 'frl_your_key_here' }
);

await runAgent('scaffold a new Express API with TypeScript');

Works with any framework

If your agent is a Python or Node.js function, wrap it with @trace (Python) or trace() (Node). This includes AutoGen, Haystack, LlamaIndex, smolagents, and custom loops. In Python, update the run dict with tokens and optional steps; in Node, use run.startSpan() for a per-span timeline.

OpenTelemetry integration Beta

If you already use OpenTelemetry, point your OTLP/HTTP exporter at Farol — no SDK changes required.

Python — opentelemetry-sdk

from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import BatchSpanProcessor

exporter = OTLPSpanExporter(
    endpoint="https://usefarol.dev/otel",
    headers={"x-farol-key": "frl_your_key_here"}
)
tracer_provider.add_span_processor(BatchSpanProcessor(exporter))

Node.js — @opentelemetry/sdk-node

import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

const exporter = new OTLPTraceExporter({
  url: 'https://usefarol.dev/otel',
  headers: { 'x-farol-key': 'frl_your_key_here' },
});

Dashboard

The dashboard has four sections:

• Overview — KPI cards (total runs, success rate, avg duration with p95, total cost) and 4 charts. Filter by period (7/30/90 days) and agent.
• Runs — full runs table. Columns: Agent, Topic, Model, Status, Quality, Anomaly, Steps, Duration, Tokens, Cost, Error, Timestamp. Click any row to open the trace timeline showing all spans. Search by topic, filter by agent, export to CSV (Starter+). Quality ratings act as lightweight evals — rate outputs directly from the trace modal and track trends over time.
• Agents — one card per agent showing total runs, success rate, avg cost, avg duration, last run. Click a card to open a detailed modal with charts and runs filtered to that agent.
• Alerts — seven alert types: cost anomaly, duration anomaly, p95 latency, regression, quality trend, budget, and proactive trend alerts. Grouped alerts show when multiple agents are affected simultaneously. Clicking an alert opens the trace or filters runs to the affected agent.

FAQ