Skip to main content

​
Synopsis

runagent run [AGENT_ID] [OPTIONS]

​
Description

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

​
Options

OptionDescriptionDefault
--input, -iJSON input dataRequired
--input-file, -fRead input from file-
--output, -oOutput file pathstdout
--streamEnable streaming outputfalse

​
Examples

​
Basic Usage

# 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

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

​
Input Format

The input must be valid JSON: 
{
  "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: 
{
  "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