> 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 Go code
category: Go SDK
hideRightSidebar: true
---

`agnt5.Client` calls the AGNT5 gateway from your own Go code: an API server, a job, or a test. It authenticates with a [service key](/docs/build/local-development.md#create-a-service-key).

## `agnt5.NewClient(gatewayURL, opts...)`

```go
client, err := agnt5.NewClient("https://gw.agnt5.com",
	agnt5.WithAPIKey(os.Getenv("AGNT5_API_KEY")),
)
if err != nil {
	log.Fatal(err)
}
```

Pass `""` as the gateway URL to use `AGNT5_GATEWAY_URL`, or `https://gw.agnt5.com` when it isn't set.

| Option | Description |
|---|---|
| `WithAPIKey(key)` | A service key. |
| `WithClientDeploymentID(id)` | The deployment to run against. Leave it out when the key was created for one environment. |

## Run a component

### `client.Run(ctx, component, input, opts...)`

Runs a component, waits for it to finish, and returns a `*RunResponse`. `Output` is the component's return value as raw JSON:

```go
resp, err := client.Run(ctx, "order_workflow", map[string]any{"orderId": "4512"},
	agnt5.WithRunComponentType(agnt5.ComponentTypeWorkflow),
)
if err != nil {
	return err
}

var out OrderResult
if err := json.Unmarshal(resp.Output, &out); err != nil {
	return err
}
```

| `RunResponse` field | Description |
|---|---|
| `RunID` | The run's ID. |
| `Status` | The run's status, for example `completed`. |
| `Output` | The return value, as `json.RawMessage`. |
| `Error` | Error details when the run failed. |
| `DurationMS` | How long the run took. |

### `client.Submit(ctx, component, input, opts...)`

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

| Method | Returns |
|---|---|
| `client.WaitForResult(ctx, runID, timeout, pollInterval)` | The `*RunResponse`, once the run finishes. |
| `client.GetStatus(ctx, runID)` | The run's current status. |
| `client.GetResult(ctx, runID)` | The `*RunResponse` with its output. |
| `client.GetEvents(ctx, runID)` | The run's events, from `run.queued` on. |

```go
sub, err := client.Submit(ctx, "report_workflow", map[string]any{"reportId": "r-1"},
	agnt5.WithSubmitComponentType(agnt5.ComponentTypeWorkflow),
)
if err != nil {
	return err
}
result, err := client.WaitForResult(ctx, sub.RunID, time.Minute, 500*time.Millisecond)
```

## Run a batch

`client.Batch(ctx, component, items)` starts one run per item and returns the `BatchID` and each `RunID`. `client.GetBatchStatus(ctx, batchID, true, timeout)` returns the batch's status and each item's result:

```go
batch, err := client.Batch(ctx, "score_lead", []map[string]any{{"leadId": "a"}, {"leadId": "b"}})
if err != nil {
	return err
}
status, err := client.GetBatchStatus(ctx, batch.BatchID, true, 10*time.Second)
```

## Evaluate a component

`client.Eval()` scores one input and `client.BatchEval()` 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.