> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
last_verified: 2026-10-09
title: Client
description: Run components, follow runs, run batches, and evaluate components from your own Python code
category: Python SDK
hideRightSidebar: true
---

`Client` calls the AGNT5 gateway from your own code: an API server, a script, or a test. `AsyncClient` has the same methods for `async` code. Both authenticate with a [service key](/docs/build/local-development.md#create-a-service-key).

## `Client(...)`

```python
from agnt5 import Client

client = Client(api_key="agnt5_sk_...")
```

| Parameter | Description |
|---|---|
| `gateway_url` | The gateway. Defaults to `AGNT5_GATEWAY_URL`, then `https://gw.agnt5.com`. |
| `api_key` | A service key. Defaults to `AGNT5_API_KEY`. |
| `deployment_id` | The deployment to run against. Leave it out when the key was created for one environment. |

## Run a component

### `client.run(component, input, component_type=...)`

Runs a component, waits for it to finish, and returns a response with `status`, `output`, and `run_id`:

```python
result = client.run("order_workflow", {"order_id": "4512"}, component_type="workflow")
print(result.status, result.output)
```

`component_type` is `"function"` (default), `"workflow"`, `"tool"`, or `"agent"`.

### `client.submit(component, input, component_type=...)`

Starts a run and returns at once with its `run_id`. Follow it with:

| Method | Returns |
|---|---|
| `client.wait_for_output(run_id, timeout=...)` | The output, once the run finishes. |
| `client.get_status(run_id)` | The run's current status. |
| `client.get_result(run_id)` | The run's result, with its `output`. |
| `client.get_output(run_id)` | The output of a finished run. |

```python
submitted = client.submit("report_workflow", {"report_id": "r-1"}, component_type="workflow")
report = client.wait_for_output(submitted.run_id, timeout=60)
```

### `client.stream_events(component, input, component_type=...)`

Starts a run and yields its events as they happen, from `run.queued` to `run.completed`:

```python
for event in client.stream_events("order_workflow", {"order_id": "4512"}, component_type="workflow"):
    print(event.event_type)
```

## Run a batch

`client.batch(component, items)` starts one run per item and returns its `batch_id`. `client.get_batch_status(batch_id, include_results=True)` returns the batch's status and each item's `run_id`, `status`, and `output`:

```python
batch = client.batch("score_lead", [{"lead_id": "a"}, {"lead_id": "b"}])
status = client.get_batch_status(batch.batch_id, include_results=True)
```

## Evaluate a component

`client.eval()` scores one input and `client.batch_eval()` scores many, with built-in scorers or LLM-judge presets. See [Batch eval](/docs/improve/batch-eval.md).

## Next steps

* [Run status and output](/docs/api-reference/runs-and-traces/list-gateway-runs.md): the gateway API behind these methods.
* [Batch eval](/docs/improve/batch-eval.md): evaluate components from code.