# `KapsoEx.Agent.Runs`
[🔗](https://github.com/rocket4ce/kapso_ex/blob/v0.1.0/lib/kapso_ex/agent/runs.ex#L1)

Trigger and control [Kapso Agent](https://docs.kapso.ai/docs/kapso-agent/api)
runs.

Runs are asynchronous: poll `get/2` (or the returned `status_url`) or
subscribe to the `kapso_agent.run.*` project webhooks. When a run is
`waiting_for_approval`, approve or reject the pending tool call.

# `result`

```elixir
@type result() :: {:ok, map()} | {:error, KapsoEx.Error.t()}
```

# `approve`

```elixir
@spec approve(KapsoEx.Client.t(), String.t(), String.t()) :: result()
```

Approves a pending tool call.

# `cancel`

```elixir
@spec cancel(KapsoEx.Client.t(), String.t()) :: result()
```

Cancels a run.

# `create`

```elixir
@spec create(KapsoEx.Client.t(), map() | keyword()) :: result()
```

Creates a run.

Attributes: `mode` and `input` (`%{prompt: ...}` or `%{finding_id: ...}`)
are required; pass `conversation_id` to continue a session (same API key
and mode), and `metadata` for your own references.

Built-in modes that accept API runs: `"auto"`, `"api"`, `"workflows"`,
`"findings"`, `"findings-investigator"`, `"meta-onboarding"`,
`"whatsapp-templates"` and `"whatsapp-flow"`, plus custom modes with the
`api` surface. Other modes return `422`.

    Runs.create(client, %{mode: "api", input: %{prompt: "How many conversations failed today?"}})

# `get`

```elixir
@spec get(KapsoEx.Client.t(), String.t()) :: result()
```

Gets a run. Only runs created with the same API key are visible.

# `pause`

```elixir
@spec pause(KapsoEx.Client.t(), String.t()) :: result()
```

Pauses a run.

# `reject`

```elixir
@spec reject(KapsoEx.Client.t(), String.t(), String.t()) :: result()
```

Rejects a pending tool call.

# `resume`

```elixir
@spec resume(KapsoEx.Client.t(), String.t()) :: result()
```

Resumes a paused run.

---

*Consult [api-reference.md](api-reference.md) for complete listing*