> ## Documentation Index
> Fetch the complete documentation index at: https://docs.run-agent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# runagent run

> Run a deployed agent

## Synopsis

```bash theme={null}
runagent run [AGENT_ID] [OPTIONS]
```

## Description

Execute a deployed agent with input data and receive the response.

## Options

| Option               | Description             | Default  |
| -------------------- | ----------------------- | -------- |
| `--input`, `-i`      | JSON input data         | Required |
| `--input-file`, `-f` | Read input from file    | -        |
| `--output`, `-o`     | Output file path        | stdout   |
| `--stream`           | Enable streaming output | false    |

## Examples

### Basic Usage

```bash theme={null}
# Run with inline input
runagent run agent-123 --input '{"query": "Hello"}'

# Run with file input
runagent run agent-123 --input-file request.json

# Save output to file
runagent run agent-123 --input '{"query": "Test"}' --output result.json
```

### Streaming

```bash theme={null}
# Stream responses
runagent run agent-123 --input '{"query": "Tell me a story"}' --stream
```

## Input Format

The input must be valid JSON:

```json theme={null}
{
  "query": "Your question here",
  "parameters": {
    "temperature": 0.7,
    "max_tokens": 150
  }
}
```

## Response Format

The CLI and SDK now return a minimal payload when the execution completes:

```json theme={null}
{
  "success": true,
  "data": "{\"type\": \"string\", \"payload\": \"...\"}",
  "message": "Agent execution completed successfully",
  "error": null,
  "timestamp": "2025-11-12T22:23:35.216480",
  "request_id": "adffa696-6273-4c5b-a933-883d830fd72c"
}
```

* `data` contains the agent output encoded with `serialize_object_to_structured`, so the CLI/SDK can deterministically decode every result type.
* Full execution metadata (runtime, VM, invocation ID, etc.) remains available through the local invocation history endpoints and the RunAgent dashboard/middleware.

Error responses keep the same envelope but include an `error` object with diagnostic fields.

## See Also

* [`runagent deploy`](/cli/commands/deploy) - Deploy an agent first
* [`runagent status`](/cli/commands/status) - Check agent status