Observability
freeact provides observability by tracing agent activities, code executions and model calls, including token usage and accumulated costs.
We currently support Langfuse as the observability backend for storing and visualizing trace data.
Setup
To use tracing in freeact, either setup a self-hosted Langfuse instance or create a Langfuse Cloud account.
Generate API credentials (secret and public keys) from your Langfuse project settings and place the keys together with the Langfuse host information in a .env file:
Agent tracing
Agent tracing in freeact is enabled by calling tracing.configure() at application startup. Once configured, all agent activities are automatically exported to Langfuse.
By default, agent activities of a multi-turn conversation are grouped into a session. For custom session boundaries or a custom session_id use the tracing.session() context manager.
import asyncio
from rich.console import Console
from freeact import CodeActAgent, LiteCodeActModel, execution_environment, tracing
from freeact.cli.utils import stream_conversation
tracing.configure() # (1)!
async def main():
async with execution_environment(
ipybox_tag="ghcr.io/gradion-ai/ipybox:basic",
) as env:
async with env.code_provider() as provider:
skill_sources = await provider.get_sources(
module_names=["freeact_skills.search.google.stream.api"],
)
async with env.code_executor() as executor:
model = LiteCodeActModel(
model_name="anthropic/claude-3-7-sonnet-20250219",
reasoning_effort="low",
skill_sources=skill_sources,
)
agent = CodeActAgent(model=model, executor=executor)
with tracing.session(session_id="session-123"): # (2)!
await stream_conversation(agent, console=Console())
if __name__ == "__main__":
asyncio.run(main())
tracing.configure()configures an application to export agent traces to Langfuse. Accepts all Langfuse configuration options via parameters or as environment variables.- All agent activities within this context are grouped into the session
session-123. UseNoneto generate a random session id.
Info
A shutdown hook in freeact automatically flushes pending traces on application exit. For manual shutdown control, call tracing.shutdown() explicitly.
Example
This example demonstrates tracing of a multi-turn conversation starting with the query What was the first spacecraft to successfully orbit Mars?
The screenshots below show how the collected trace data is displayed in the Langfuse Web UI.
