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

# client.agent_run

## `get`

```python theme={null}
get(agent_id: int, run_id: int) -> AgentRun
```

Get details of a specific agent run.

**Parameters:**

| Name | Type | Description | Default |
| - | - | - | - |
| `agent_id` | `int` | The ID of the agent | *required* |
| `run_id` | `int` | The ID of the run to retrieve | *required* |

## `download_templated_output`

```python theme={null}
download_templated_output(
    agent_id: int,
    run_id: int,
    output_template_id: int,
    output_format: OutputFormat,
    filename: str,
) -> None
```

Download the templated output for a specific agent run to a file.

**Parameters:**

| Name | Type | Description | Default |
| - | - | - | - |
| `agent_id` | `int` | The ID of the agent | *required* |
| `run_id` | `int` | The ID of the run | *required* |
| `output_template_id` | `int` | The ID of the template to use for formatting | *required* |
| `output_format` | `OutputFormat` | The format for the output (e.g., "pdf", "docx") | *required* |
| `filename` | `str` | The file path where the output should be saved | *required* |

## `download_runs_templated_output`

```python theme={null}
download_runs_templated_output(
    agent_id: int,
    output_template_id: Optional[int] = None,
    *,
    filename: str
) -> None
```

Download the templated output for all runs of an agent to a file.

**Parameters:**

| Name | Type | Description | Default |
| - | - | - | - |
| `agent_id` | `int` | The ID of the agent | *required* |
| `output_template_id` | `Optional[int]` | The ID of a multi-run Excel template. The output format (xlsx or xlsm) matches the template file. When omitted, all runs are downloaded as the default xlsx table. | `None` |
| `filename` | `str` | The file path where the output should be saved | *required* |

## `add`

```python theme={null}
add(
    agent_id: int,
    files: Sequence[FileInput],
    user_defined_id: Optional[str] = None,
    due_date: Optional[datetime] = None,
    idempotency_key: Optional[str] = None,
) -> AgentRun
```

Add a new agent run.

Files are streamed to the server without loading their full contents into memory. Each file
may be a path (`str` or `os.PathLike`), an open binary file object, a `bytes` value, or
a `(filename, bytes_or_file_object)` tuple.

**Parameters:**

| Name | Type | Description | Default |
| - | - | - | - |
| `agent_id` | `int` | The ID of the agent | *required* |
| `files` | `Sequence[FileInput]` | List of files to upload with the run | *required* |
| `user_defined_id` | `Optional[str]` | Optional user-defined identifier for the run | `None` |
| `due_date` | `Optional[datetime]` | Optionally specify a due date for the run. When a due date is specified, Kolena will attempt to ensure that all prompts have completed on this run before its due date. | `None` |
| `idempotency_key` | `Optional[str]` | Optional unique key (e.g. a UUID) to prevent duplicate runs. If this agent already has a run with this key, that run is returned instead of creating a new one. Use a new key for each distinct request. A failed run is still returned for its key, so retry it with a new key. Deleting a run releases its key, so the next call with that key creates a new run. | `None` |

## `add_wait`

```python theme={null}
add_wait(
    agent_id: int,
    files: Sequence[FileInput],
    user_defined_id: Optional[str] = None,
    timeout: Optional[int] = None,
    idempotency_key: Optional[str] = None,
) -> AgentRun
```

Add a new agent run and wait for its completion.

This method initiates an agent run and waits for it to complete before returning the result,
combining the functionality of creating a run and waiting for its completion in a single call.

Files are streamed to the server without loading their full contents into memory; see
`add` for the accepted file forms.

**Parameters:**

| Name | Type | Description | Default |
| - | - | - | - |
| `agent_id` | `int` | The ID of the agent | *required* |
| `files` | `Sequence[FileInput]` | List of files to upload with the run | *required* |
| `user_defined_id` | `Optional[str]` | Optional user-defined identifier for the run | `None` |
| `timeout` | `Optional[int]` | Optional timeout in seconds to wait for the run to complete | `None` |
| `idempotency_key` | `Optional[str]` | Optional unique key (e.g. a UUID) to prevent duplicate runs. If this agent already has a run with this key, no new run is created and this waits on the existing run instead. A failed run is still returned for its key, so retry it with a new key. Deleting a run releases its key, so the next call with that key creates a new run. | `None` |

**Returns:**

| Type | Description |
| - | - |
| `AgentRun` | The AgentRun. Its status is still RUNNING if the timeout elapsed before the run completed. |

## `list`

```python theme={null}
list(
    agent_id: int,
    page_number: int = 0,
    page_size: int = 50,
    run_ids: Optional[List[int]] = None,
    status: Optional[AgentRunStatus] = None,
    user_defined_ids: Optional[List[str]] = None,
    created_lte: Optional[datetime] = None,
    created_gte: Optional[datetime] = None,
) -> ListAgentRunsResponse
```

Get a paginated list of agent runs.

**Parameters:**

| Name | Type | Description | Default |
| - | - | - | - |
| `agent_id` | `int` | The ID of the agent | *required* |
| `page_number` | `int` | Page number for pagination (default: 0) | `0` |
| `page_size` | `int` | Number of items per page (default: 50, max: 1000) | `50` |
| `run_ids` | `Optional[List[int]]` | Optional list of run\_id to get. | `None` |
| `status` | `Optional[AgentRunStatus]` | Optional status to filter by (e.g. AgentRunStatus.RUNNING, AgentRunStatus.SUCCESS). | `None` |
| `user_defined_ids` | `Optional[List[str]]` | Optional list of user-defined IDs to filter by. | `None` |

## `delete`

```python theme={null}
delete(agent_id: int, run_id: int) -> None
```

Delete a specific agent run.

**Parameters:**

| Name | Type | Description | Default |
| - | - | - | - |
| `agent_id` | `int` | The ID of the agent | *required* |
| `run_id` | `int` | The ID of the run to delete | *required* |


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