# Run an app agent

> Start one of the app's declared agents as a test execution. Asynchronous; poll the execution for the outcome.

Source: https://docs.generalinput.com/api/workflows/app-run-agent



<Endpoint method="POST" path="/v1/workflows/:id/app/run-agent" />

<Access scope="workflows:manage" />

An app declares background agents in `app.json` (`agents: [{ name }]`, each with `agents/<name>/`). This starts one the way a button in the app would. The run executes on the agent infrastructure and shows up in the app's Agents tab.

## Body [#body]

| Field       | Type   | Required | Notes                                                  |
| ----------- | ------ | -------- | ------------------------------------------------------ |
| `agentName` | string | yes      | A name declared in `app.json`.                         |
| `variables` | object | no       | The run's input, matching the agent's declared schema. |

## Response [#response]

```json
{ "ok": true, "executionId": "exec_01HX…" }
```

Poll [get an execution](/api/workflows/get-execution) with the app's id. A launch failure is `{ "ok": false, "status": 400, "message": "…" }`.