> ## 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.16. [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.16/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.16/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.16/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.16/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.16/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.16/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 Galtea file reference from an earlier upload. Any other URL raises a `ValueError`. `content` may be empty when the files carry the whole answer, and the turn is still recorded as generated. A metric scores a Galtea file only when its judge model reads that kind of file; see [Upload Output File](https://docs.galtea.ai/v5.16/sdk/api/trace/upload-output-file.md) for the rule. |
| **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.16/sdk/api/trace/create.md) - Manual creation
* [Upload Output File](https://docs.galtea.ai/v5.16/sdk/api/trace/upload-output-file.md) - Attach a file to a turn's answer
* [Span Service](https://docs.galtea.ai/v5.16/sdk/api/span/service.md) - Manual span management
* [Simulating Conversations](https://docs.galtea.ai/v5.16/sdk/tutorials/simulating-conversations.md) - Multi-turn simulations


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