> ## 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.

# Generate Trace

> Execute an agent and automatically capture spans, latency, and metadata

> [!WARNING]
>
> You are reading the docs of Galtea 5.14. [Read this page in the latest version](https://docs.galtea.ai/sdk/api/trace/generate.md).

## Overview

The `generate()` method is the recommended way to execute your agent when you want automatic span collection, timing, and trace creation. It handles the complete lifecycle:

1. Initializes span collection
2. Executes your agent with timing measurement
3. Creates/updates the trace with all metadata
4. Saves collected spans to the platform
5. Cleans up span context (prevents memory leaks)

> [!NOTE]
>
> This is the recommended method for production use as it handles all span lifecycle management automatically.

## Agent Options

> [tab] Simple
>
> The quickest way to get started. Your function receives just the latest user message as a string.
>
> ```python theme={"system"}
> def my_agent(user_message: str) -> str:
>     # In a real scenario, call your model here
>     return f"Your model output to: {user_message}"
> ```

> [tab] Chat History
>
> Use this when your agent needs the full conversation context. Your function receives the message list in the OpenAI format (`{"role": "...", "content": "..."}`).
>
> ```python theme={"system"}
> def my_agent(messages: list[dict]) -> str:
>     # messages follows the standard chat format:
>     # [{"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}, ...]
>     user_message = messages[-1]["content"]
>     return f"Your model output to: {user_message}"
> ```

> [tab] Structured
>
> For full control over input and output — including optional usage tracking, cost tracking, retrieval context for RAG evaluations, and answering with files through `output_file_paths` (not in a simulated conversation).
>
> ```python theme={"system"}
> def my_agent(input_data: AgentInput) -> AgentResponse:
>     user_message = input_data.last_user_message_str()
>
>     # Access structured input fields from the first user message's metadata
>     # (e.g. when test case input is {"user_message": "hello", "chat_type": "support"})
>     first_msg = input_data.messages[0] if input_data.messages else None
>     chat_type = first_msg.metadata.get("chat_type") if first_msg and first_msg.metadata else None
>
>     # In a real scenario, call your model here
>     model_output = f"Your model output to: {user_message}"
>     # Return AgentResponse with optional usage/cost tracking
>     return AgentResponse(
>         content=model_output,
>         usage_info={"input_tokens": 100, "output_tokens": 50},
>     )
> ```

> [!NOTE]
>
> All three signatures work with `evaluations.run()`, `traces.generate()`, and `simulator.simulate()`. Both sync and async functions are supported. The SDK auto-detects which signature you're using from the type hint on the first parameter.
>
> Only the **Structured** signature receives the files a test case attaches, as `input_data.input_files`. The other two receive the text alone and fail the trace for a file-only test case. See [Reading attached files](https://docs.galtea.ai/v5.14/sdk/api/agent/input.md#reading-attached-files).
>
> Only the **Structured** signature can answer with files, through `AgentResponse.output_file_paths`. A response carrying files but no text is a real answer, not an empty one. `simulator.simulate()` is the exception: it raises a `ValueError` on a response carrying files, because a simulated conversation carries none yet. See [Output Files](https://docs.galtea.ai/v5.14/concepts/product/version/session/trace.md#trace-properties).
>
> For the full list of fields available on `AgentInput` (including structured input access via message metadata), see the [AgentInput reference](https://docs.galtea.ai/v5.14/sdk/api/agent/input.md).

## Parameters

**agent** `AgentType` *required*

The agent function to execute. Supported signatures:

* **Simple:** `(user_message: str) -> str` — receives last user message
* **Chat History:** `(messages: list[dict]) -> str` — receives full chat history (OpenAI format)
* **Structured:** `(input_data: AgentInput) -> AgentResponse` — structured input/output. See the [AgentInput reference](https://docs.galtea.ai/v5.14/sdk/api/agent/input.md) for all available fields including structured input access via message metadata.

Both sync and async functions are supported. Use the structured signature when you need `usage_info`, `cost_info`, `retrieval_context`, or to answer with `output_file_paths`. Only the structured signature receives the files a test case attaches; the other two fail the trace for a file-only test case.

**session** `Session` *required*

The session object to associate the trace with. Obtain via `galtea.sessions.create()` or `galtea.sessions.get()`.

**input** `str | dict`

The input to send to the agent. Accepts a plain string or a dict with structured fields (e.g. `{"user_message": "hello", "chat_type": "support"}`). Stored in the trace as sent, except a Galtea file in a `content` array: it is stored without its upload signature and checked like a test case input file. To attach local files to a turn you log yourself, use `input_file_paths` on [`traces.create()`](https://docs.galtea.ai/v5.14/sdk/api/trace/create). If not provided and the session is test-based, the test case input is used automatically. Required for production/monitoring sessions. See [Input Schema](https://docs.galtea.ai/v5.14/concepts/product/endpoint-connection-input-schema.md) for how to define the expected field structure on your endpoint connection.

**throw\_if\_empty\_agent\_response** `bool`

If `True`, raises a `ValueError` when the agent returns an empty response. Defaults to `False`.

A response carrying files through `output_file_paths` is not empty, even when `content` is `""` or `None`: the files are the answer.

> [!NOTE]
>
> `context_data` is automatically fetched from the session's test case and passed to the agent via `AgentInput.context_data`. No need to provide it explicitly.

## Returns

Returns a `Trace` object with all captured data.

## Example

```python theme={"system"}
# Define your agent function
def my_agent(user_message: str) -> str:
    return f"Response to: {user_message}"


trace = galtea.traces.generate(agent=my_agent, session=session, input="Generate something")
```

## What Gets Captured

The `generate()` method automatically captures and saves:

| Data | Source | Description |
| - | - | - |
| **Input** | `input` parameter | The user's input (string or structured dict) |
| **Output** | `AgentResponse.content` | The agent's response |
| **Output Files** | `AgentResponse.output_file_paths` | Files the agent answers with. Each entry is a local path the SDK uploads, or a storage URI from an earlier upload. `content` may be empty when the files carry the whole answer, and the turn is still recorded as generated. Evaluators cannot read these files yet, so the API skips a metric that reads the output unless some turn of the session answered with text of its own. On deployments that do not send files to the judge, the evaluator also skips LLM-as-a-judge metrics other than the DeepEval-based ones when any turn they read carries an output file. See [Upload Output File](https://docs.galtea.ai/v5.14/sdk/api/trace/upload-output-file.md). |
| **Retrieval Context** | `AgentResponse.retrieval_context` | Context used (for RAG). Stored as a `RETRIEVER` span, not a readable field on the returned trace. |
| **Latency** | Measured | End-to-end execution time in ms |
| **Usage Info** | `AgentResponse.usage_info` | Token counts (if provided) |
| **Cost Info** | `AgentResponse.cost_info` | Cost data (if provided) |
| **Spans** | `@traced` decorators | All traced operations |

## Providing Usage and Cost Information

Your agent can return usage and cost information in the `AgentResponse`:

```python theme={"system"}
@galtea.traced(name="main", type=SpanType.AGENT)
def my_agent_with_usage(input_data: AgentInput) -> AgentResponse:
    # Your agent logic...

    return AgentResponse(
        content="Response content",
        usage_info={
            "input_tokens": 150,
            "output_tokens": 75,
            "cache_read_input_tokens": 50,
        },
        cost_info={
            "cost_per_input_token": 0.00001,
            "cost_per_output_token": 0.00003,
            "cost_per_cache_read_input_token": 0.000001,
        },
    )
```

## Comparison with Manual Approach

| Feature | `generate()` | Manual with `set_context()` |
| - | - | - |
| Context initialization | Automatic | `set_context()` |
| Agent execution | Automatic | Manual call |
| Timing measurement | Automatic | Manual |
| Trace | Auto-created | `traces.create()` |
| Span export | Automatic | Automatic on `clear_context()` |
| Memory cleanup | Automatic | `clear_context()` |
| Error handling | Built-in | Manual try/finally |

> [!TIP]
>
> Use `generate()` for most use cases. Use manual `set_context()`/`clear_context()` only when you need to manage trace creation separately or have complex multi-step workflows.

## Error Handling

If the agent raises an exception, `generate()` ensures span context is cleaned up:

```python theme={"system"}
def failing_agent(input_data: AgentInput) -> AgentResponse:
    raise ValueError("Agent failed intentionally")


try:
    result = galtea_client.traces.generate(agent=failing_agent, session=session_error, input="test")
except Exception as e:
    # Galtea context is automatically cleaned up
    print(f"Agent failed: {e}")
```

## Related Methods

* [Create Trace](https://docs.galtea.ai/v5.14/sdk/api/trace/create.md) - Manual creation
* [Upload Output File](https://docs.galtea.ai/v5.14/sdk/api/trace/upload-output-file.md) - Attach a file to a turn's answer
* [Span Service](https://docs.galtea.ai/v5.14/sdk/api/span/service.md) - Manual span management
* [Simulating Conversations](https://docs.galtea.ai/v5.14/sdk/tutorials/simulating-conversations.md) - Multi-turn simulations


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.