> ## Documentation Index
> Fetch the complete documentation index at: https://docs.galtea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Trace Service

> Trace Service API methods in the Galtea SDK

The Trace Service in the Galtea SDK allows you to collect, manage, and persist [traces](/concepts/product/version/session/trace) that capture the internal operations of your AI agents during inference.

This Service is exposed by the `galtea.traces` object.

<Info>
  Remember that we will be using the `galtea` object. More information [here](/sdk/api/galtea).
</Info>

## Two Approaches to Trace Collection

The SDK provides two ways to collect traces:

### 1. Automatic Collection with with `generate()`

When using `galtea.inference_results.generate()`, trace collection is handled automatically:

```python theme={"system"}
@trace(type=TraceType.TOOL)
def fetch_user_data(user_id: str) -> dict:
    return {"name": "John Doe", "email": "john@example.com"}


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


def my_overview_agent(input_data: AgentInput) -> AgentResponse:
    user = fetch_user_data("user_123")
    response = generate_response("Hello")
    return AgentResponse(content=response)


# Use generate() for automatic trace context management
inference_result = galtea.inference_results.generate(
    agent=my_overview_agent,
    session=session,
    input="Show me user data",
)
```

### 2. Manual Collection with Context Management

For full control over the trace lifecycle, use `set_context()` and `clear_context()`:

Set context before running traced functions:

```python theme={"system"}
trace_context = set_context(inference_result_id=inference_result_id)
```

Then run your traced functions within this context set/open.

Once done, clear the context to [flush](sdk/api/trace/clear-context#param-flush) and detach:

```python theme={"system"}
clear_context(trace_context)
```

<Tip>
  Use `galtea.inference_results.generate()` for automatic trace collection instead of manual collection.
</Tip>

## Service Methods

### Context Management

* [@trace Decorator](/sdk/api/trace/trace-decorator)
* [start\_trace](/sdk/api/trace/start-trace)
* [set\_context](/sdk/api/trace/set-context)
* [clear\_context](/sdk/api/trace/clear-context)

### Direct API Methods

* [Create Trace](/sdk/api/trace/create)
* [Create Trace Batch](/sdk/api/trace/create-batch)
* [List Traces](/sdk/api/trace/list)
* [Get Trace](/sdk/api/trace/get)
* [Delete Trace](/sdk/api/trace/delete)

## Related

<Card title="Trace" icon="sitemap" iconType="solid" href="/concepts/product/version/session/trace">
  Understand how traces capture the internal operations of your AI agents.
</Card>