Traces

What is a Fairo Trace?

A trace is a complete, time‑stamped record of an agent (or multi‑agent workflow) run:

the original prompt(s) and all intermediate messages
every tool call and its arguments
the final response produced by each agent

You can browse your traces here

Prerequisites

You need	Why it matters	How to provide it
Python 3.11+	Fairo SDK requires 3.11 or newer	`python --version`
Virtual environment	Isolate SDK dependencies	`python -m venv fairo_env && source fairo_env/bin/activate`

1 · Install the SDK

The package is available on PyPI:

pip install fairo

2 · Authentication

Generate your API key and secret here.

Then export them in your environment:

export FAIRO_API_ACCESS_KEY_ID=<your-key>
export FAIRO_API_SECRET=<your-secret>

3 · Create your first agent

`blog_ideas_agent.py`

from langchain.prompts import PromptTemplate
from langchain.chains import LLMChain
from fairo.core.chat import ChatFairo
def ideasforblogpost():
    template = """
    You are an expert Blog-Post Idea Generator.
    When given a topic, you must output a list of 10 creative blog post titles,
    each on its own line.

    Topic: {topic}
    """
    prompt = PromptTemplate(
        input_variables=["topic"],
        template=template
    )
    chain = LLMChain(
        llm=ChatFairo(),
        prompt=prompt,
        verbose=False,
    )
    return chain

4 · Run with `FairoExecutor`

Create a new file to invoke the execution and build your chain.

`execute.py`

from fairo.core.execution.executor import FairoExecutor
from blog_ideas_agent import ideasforblogpost
FairoExecutor(
    agents=[ideasforblogpost],
    input_fields=["topic"]
).run({"topic": "LLMs"})

Input field is required and should contain the keys your agent is expecting to receive

Run your agent

python execute.py

Once your run is completed, you can see your traces here.

See the full example here.

5 · Customising traces

Need	What to do
Custom Experiment	Pass `experiment_name="analytics‑traces"` to `FairoExecutor`.
Silence console output	Set `verbose=False` (default). Trace logging still happens in the background.

6 · Troubleshooting

Symptom	Possible cause	Fix
`401 Unauthorized` on upload	Bad `FAIRO_API_KEY` / `SECRET`	Re‑export correct credentials.