Skip to main content
The Trace Service in the Galtea SDK allows you to collect, manage, and persist traces that capture the internal operations of your AI agents during inference. This Service is exposed by the galtea.traces object.
Remember that we will be using the galtea object. More information here.

​
Two Approaches to Trace Collection

The SDK provides two ways to collect traces: Use the @trace decorator or start_trace() context manager with context management: 
from galtea import Galtea, trace, set_context, clear_context, TraceType

galtea = Galtea(api_key="YOUR_API_KEY")

@trace(type=TraceType.TOOL)
def fetch_user_data(user_id: str) -> dict:
    return {"name": "John Doe", "email": "[email protected]"}

@trace(type=TraceType.GENERATION)
def generate_response(prompt: str) -> str:
    return "Generated response..."

# Set context before running traced functions
inference_result = galtea.inference_results.create(session_id=session.id, input="...")
token = set_context(inference_result_id=inference_result.id)

try:
    user = fetch_user_data("user_123")
    response = generate_response("Hello")
finally:
    clear_context(token)  # Flushes traces to Galtea

​
2. Fully Automatic with generate()

When using galtea.inference_results.generate(), trace collection is handled automatically: 
# Traces are collected, saved, and cleaned up automatically
inference_result = galtea.inference_results.generate(
    agent=my_agent,
    session=session,
    user_input="What's the price?"
)

​
3. Manual Collection with Context Management

For full control over the trace lifecycle, use set_context() and clear_context(): 
from galtea import Galtea, trace, set_context, clear_context, TraceType

galtea = Galtea(api_key="YOUR_API_KEY")

@trace(type=TraceType.RETRIEVER)
def search_docs(query: str):
    return [{"doc": "relevant content"}]

@trace(type=TraceType.GENERATION)
def generate(context):
    return "Generated response"

# 1. Create inference result first
inference_result = galtea.inference_results.create(
    session_id="YOUR_SESSION_ID",
    input="What is pricing?"
)

# 2. Set context to associate traces with the inference result
token = set_context(inference_result_id=inference_result.id)

try:
    # 3. Execute traced operations
    context = search_docs("What is pricing?")
    response = generate(context)
    
    # 4. Update inference result with output
    galtea.inference_results.update(
        inference_result_id=inference_result.id,
        output=response
    )
finally:
    # 5. Clear context and flush traces to Galtea
    clear_context(token)  # flush=True by default
Use galtea.inference_results.generate() for automatic trace collection instead of manual collection.

​
Service Methods

​
Context Management

​
Direct API Methods

Trace

Understand how traces capture the internal operations of your AI agents.