# geni app run-agent

> Start one of the app's declared agents as a test execution against the live app.

Source: https://docs.generalinput.com/cli/resource/app/run-agent



```sh
geni app run-agent <name> [id] [flags]
```

An app can declare background agents (`agents: [{ name }]` in `app.json`, each with `agents/<name>/`). This starts one the way a button in the app would. The run is asynchronous: the command prints the execution id and returns; poll [`geni workflow executions`](/cli/resource/workflow/executions) and inspect with [`geni workflow execution <executionId>`](/cli/resource/workflow/execution).

Runs against the **published** app, so [`publish`](/cli/resource/publish) first.

## Synopsis [#synopsis]

```sh
geni app run-agent enrichAccounts --variables '{"accountId":"acc_123"}'
geni app run-agent researchCompany wf_01HX --json
```

| Arg / Flag           | Notes                                                                    |
| -------------------- | ------------------------------------------------------------------------ |
| `<name>`             | An agent name declared in `app.json`.                                    |
| `[id]`               | App id. Omit to use the marker in `--dir`.                               |
| `--variables <json>` | The run's input, matching the agent's declared schema. Defaults to `{}`. |
| `--dir <path>`       | Resource directory. Defaults to cwd.                                     |
| `--json`             | Machine-readable output.                                                 |

## Output [#output]

```
✓ Agent "enrichAccounts" started
Execution: exec_01HX…
It runs in the background. Poll `geni workflow executions wf_01HX`, then inspect with `geni workflow execution exec_01HX…`.
```

A launch the server refuses (an undeclared agent, a schema mismatch) prints the reason and exits `1`.