> For the complete documentation index, see [llms.txt](https://docs.algenta.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.algenta.ai/sdks/typescript/agent-runs.md).

# Agent runs

Agent runs drive a task through the engine's tool loop with deterministic, replayable checkpoints. This page is the complete `AlgentaClient` reference for the agent-run surface: every method, its HTTP route, and copy-pasteable examples. All bodies and query parameters stay snake\_case even though the method names are camelCase, mirroring the [HTTP contract](/http-api/overview.md) exactly. For the end-to-end walkthrough, see the [agent runs guide](/guides/agent-runs.md).

Every method here lives on the client you construct once:

```ts
import { AlgentaClient } from "algenta-sdk";

const client = new AlgentaClient({
  apiKey: process.env.ALGENTA_API_KEY ?? process.env.DE_API_KEY,
  baseUrl: process.env.ALGENTA_BASE_URL ?? "https://api.algenta.ai",
});
```

## Launch and stream a run

`createAgentRun` accepts an `AgentRunCreateRequest` (`task`, and optional `context`, `tools`, `max_steps`, `output_format`, `approval_mode`, `start_paused`) and returns an `AgentRunResponse` carrying the `run_id`, `status`, `request_hash`, and `decision_hash`. `streamAgentRunEvents` is an async generator that yields `agent.run.event` messages until a final `agent.run.completed` message.

{% tabs %}
{% tab title="TypeScript" %}

```ts
const run = await client.createAgentRun({
  task: "Summarize the latest incident report and propose a remediation",
  max_steps: 8,
  approval_mode: "auto", // "auto" | "manual"
  start_paused: false,
});

for await (const message of client.streamAgentRunEvents(run.run_id)) {
  if (message.type === "agent.run.completed") {
    console.log("done:", message.status);
    break;
  }
  console.log(message.event?.event_type, message.event?.summary);
}

const finished = await client.getAgentRun(run.run_id);
console.log(finished.status, finished.request_hash, finished.decision_hash);
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl -sS "$ALGENTA_BASE_URL/v1/agent/runs" \
  -H "Authorization: Bearer $ALGENTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Summarize the latest incident report and propose a remediation",
    "max_steps": 8,
    "approval_mode": "auto",
    "start_paused": false
  }'
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
`AgentRunStatus` is one of `running`, `paused`, `requires_approval`, `completed`, or `cancelled`. When a run pauses, `pending_action` is `resume` or `approve`.
{% endhint %}

## Control a run

When a run pauses for a gated action, advance it with `approveAgentRun`; continue a plain paused run with `resumeAgentRun`; stop it early with `cancelAgentRun`. Branch a new run from a checkpoint with `forkAgentRun`, or re-execute deterministically from one with `replayAgentRun`. Both `forkAgentRun` and `replayAgentRun` take an optional `checkpoint_id` — omit it (or pass `null`) to use the latest checkpoint.

```ts
await client.approveAgentRun(run.run_id); // approve the pending gated action
await client.resumeAgentRun(run.run_id);  // continue a paused run
await client.cancelAgentRun(run.run_id);  // stop the run

const branch = await client.forkAgentRun(run.run_id, { checkpoint_id: "ckpt_3" });
const replay = await client.replayAgentRun(run.run_id, { checkpoint_id: "ckpt_3" });
console.log(branch.run_id, replay.status);
```

## Read events, checkpoints, mission events, and telemetry

Per-run readers take the `runId` and an optional `{ limit }`; the `query*` variants scan across runs and accept pagination plus provenance filters such as `request_hash`, `policy_snapshot_id`, and `schema_snapshot_id`.

```ts
// Per-run event log (non-streaming).
const events = await client.getAgentRunEvents(run.run_id, { limit: 500 });
console.log(events.total_events, events.data.length);

// Checkpoints you can fork or replay from.
const checkpoints = await client.listAgentRunCheckpoints(run.run_id);
console.log(checkpoints.total_checkpoints);

// Mission events and telemetry for one run.
const mission = await client.listAgentRunMissionEvents(run.run_id, { limit: 200 });
const telemetry = await client.listAgentRunTelemetry(run.run_id, { limit: 200 });
console.log(mission.data.length, telemetry.total_batches);

// Cross-run history, paginated and filtered.
const page = await client.listAgentRuns({ page: 1, limit: 25, status: "completed" });
const ckptScan = await client.queryAgentRunCheckpoints({ run_id: run.run_id, limit: 50 });
const missionScan = await client.queryAgentRunMissionEvents({ event_type: "tool_call", limit: 50 });
const telemetryScan = await client.queryAgentRunTelemetry({ telemetry_kind: "token_usage", limit: 50 });
console.log(page.total, ckptScan.data.length, missionScan.data.length, telemetryScan.data.length);
```

## Method reference

| Method                                        | HTTP                                             | Notes                                                                                                                                     |
| --------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `createAgentRun(request)`                     | `POST /v1/agent/runs`                            | `request` is an `AgentRunCreateRequest` (`task`, `context`, `tools`, `max_steps`, `output_format`, `approval_mode`, `start_paused`).      |
| `getAgentRun(runId)`                          | `GET /v1/agent/runs/{run_id}`                    | Current `AgentRunResponse`, including `request_hash` and `decision_hash`.                                                                 |
| `listAgentRuns(options?)`                     | `GET /v1/agent/runs`                             | Paginated. Options: `page`, `limit`, `status`, `request_hash`, `policy_snapshot_id`, `schema_snapshot_id`. Defaults `page=1`, `limit=25`. |
| `getAgentRunEvents(runId, { limit })`         | `GET /v1/agent/runs/{run_id}/events`             | Event log; `limit` defaults to 1000.                                                                                                      |
| `streamAgentRunEvents(runId, { limit })`      | `GET /v1/agent/runs/{run_id}/events?stream=true` | Async generator of `AgentRunStreamEventResponse` (`agent.run.event` / `agent.run.completed`).                                             |
| `listAgentRunCheckpoints(runId)`              | `GET /v1/agent/runs/{run_id}/checkpoints`        | Checkpoints available to fork or replay from.                                                                                             |
| `queryAgentRunCheckpoints(options?)`          | `GET /v1/agent/runs/checkpoints`                 | Cross-run checkpoint scan. Options include `run_id`, `checkpoint_id`, `status`, `request_hash`, plus pagination.                          |
| `listAgentRunMissionEvents(runId, { limit })` | `GET /v1/agent/runs/{run_id}/mission-events`     | Mission-level events for one run; `limit` defaults to 1000.                                                                               |
| `queryAgentRunMissionEvents(options?)`        | `GET /v1/agent/runs/mission-events`              | Cross-run mission-event scan. Options include `run_id`, `event_type`, plus pagination.                                                    |
| `replayAgentRun(runId, { checkpoint_id })`    | `POST /v1/agent/runs/{run_id}/replay`            | Deterministic re-execution from a checkpoint; omit `checkpoint_id` for the latest.                                                        |
| `forkAgentRun(runId, { checkpoint_id })`      | `POST /v1/agent/runs/{run_id}/fork`              | New run branched from a checkpoint.                                                                                                       |
| `resumeAgentRun(runId)`                       | `POST /v1/agent/runs/{run_id}/resume`            | Continue a paused run.                                                                                                                    |
| `cancelAgentRun(runId)`                       | `POST /v1/agent/runs/{run_id}/cancel`            | Stop the run.                                                                                                                             |
| `approveAgentRun(runId)`                      | `POST /v1/agent/runs/{run_id}/approve`           | Approve a pending gated action.                                                                                                           |
| `listAgentRunTelemetry(runId, { limit })`     | `GET /v1/agent/runs/{run_id}/telemetry`          | Telemetry batches for one run; `limit` defaults to 1000.                                                                                  |
| `queryAgentRunTelemetry(options?)`            | `GET /v1/agent/runs/telemetry`                   | Cross-run telemetry scan. Options include `run_id`, `telemetry_kind`, `module_name`, plus pagination.                                     |

## Related pages

{% content-ref url="/pages/t04jAJYsxv6GnFNdndsF" %}
[Run an agent](/guides/agent-runs.md)
{% endcontent-ref %}

{% content-ref url="/pages/pGbjtGeuDQ8mo4MvqzUO" %}
[Jobs, triggers & capabilities](/sdks/typescript/jobs-triggers-capabilities.md)
{% endcontent-ref %}

{% content-ref url="/pages/OF5vPGpTFlUCu9cANi4Y" %}
[TypeScript SDK](/sdks/typescript.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.algenta.ai/sdks/typescript/agent-runs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.