# Run an Agent Through the API

Use **POST /api/v1/agents/AGENT_ID/runs** to run an agent you set up in Redbelt.
HTTP **202** means Redbelt accepted the request; the answer arrives later.

## Before you start

Complete the [API quickstart](/quickstart/). Create and configure the agent in
Redbelt, then share it with the identity behind your API key. A service key runs
as its service user. Access granted to the human who created the key is insufficient.
The organization needs a configured provider and available budget.

Call **GET /api/v1/agents** to discover accessible agents and
**GET /api/v1/agents/AGENT_ID** to read the selected definition's name and description.
Set **REDBELT_AGENT_ID** to its UUID. Each request needs a UUIDv7 **request_id**;
this example uses Python **3.14**, whose standard library can generate one. On
older versions, use any UUIDv7 library.

## Submit an input

Save this as **start_conversation.py**:

```python
"""Submit a UI-created agent; retain request_id for an exact retry."""

import json
import os
from urllib.request import Request, urlopen
from uuid import uuid7

api_url = os.environ.get("REDBELT_API_URL", "https://redbelt.ai/api").rstrip("/")
agent_id = os.environ["REDBELT_AGENT_ID"]
request_id = str(uuid7())
payload = {"request_id": request_id, "input": "Turn these project notes into a short action checklist.", "model": "auto"}
# Persist request_id and this exact payload before sending. A timeout does not
# mean rejection: retry this payload with the same ID, never a new UUID.
request = Request(
    f"{api_url}/v1/agents/{agent_id}/runs",
    data=json.dumps(payload).encode(),
    headers={"Authorization": f"Bearer {os.environ['REDBELT_API_KEY']}", "Content-Type": "application/json"},
    method="POST",
)
with urlopen(request, timeout=60) as response:
    submitted = json.load(response)
print(json.dumps(submitted, indent=2))
print("Status:", f"{api_url}/v1/executions/agent/{submitted['id']}")

```

Run **python3 start_conversation.py**. Save the returned **id** and **thread_id**.
The **id** identifies your input; **run_id** appears once the agent starts working
on it. A request ID belongs to its thread, so retry with the same ID and the same
**thread_id**. The same ID on a different thread counts as a new input.

For reliable retries, save the generated **request_id** and exact request body
before sending. Reuse them after a timeout. Running the example again generates
a new request and can perform the work again.

## Continue and supply Knowledge

Send a fresh UUIDv7 **request_id**, the returned **thread_id**, and only the new
**input** to the same agent submission endpoint. Redbelt retains thread history.
Use **model: "auto"** for normal agent model selection, or an available model slug.

Optional **upload_ids** and **folder_ids** contain UUIDs of Knowledge that this
identity can access. Share required resources with a service user before
submitting; sharing an agent does not share its author's private documents or
third-party credentials. Configure plugin access on the agent in Redbelt.

## Retrieve the result

Call **GET /api/v1/executions/agent/EXECUTION_ID**. Inspect **status**, **output**,
**wait_id**, and **error_code**. Add **?wait=30** to wait for the next status. For artifacts, questions, approvals and
cancellation, follow [Track Runs and Retrieve Results](/api/results/).

For a key owned by your human user, you can also open **/thread/THREAD_ID** in
Redbelt while signed in as that same owner. Threads created by a service user
remain owned by that identity; retrieve their results through its API key.
The key's creator-sharing setting does not grant access to these threads.

## Troubleshooting

A **404** can mean an inaccessible agent or thread. A **409** can mean the same
request ID was reused with changed input. A run accepted earlier can fail later
because permissions, connections, budget or provider availability changed. Read
its status before deciding to submit another request.
