Invoke

The CLI’s agent invoke command sends a payload to a deployed Novita Agent and returns its response. It supports both plain-text prompts and structured JSON input, and can stream the response as it is produced.

Note: Invoke runs from a deployed agent’s project directory. It requires a novita.toml in the current directory (created by agent launch) and the NOVITA_API_KEY environment variable.

Prerequisites

CLI

export NOVITA_API_KEY=<your API key>

# The agent must already be deployed (run from its project directory)
# novita-sandbox-cli agent launch

Usage

CLI

novita-sandbox-cli agent invoke <payload> [options]

Argument / Option	Description
`<payload>`	JSON payload or prompt text (required)
`--agentId <id>`	Agent ID to invoke, in the form `agent_name-template_id`
`--stream`	Stream the response as it is generated
`--timeout <seconds>`	Request timeout in seconds (default: 60)
`--env <key=value>`	Environment variable for this invocation. Repeatable
`--verbose`	Verbose output

Payload

The <payload> is parsed as JSON if possible; otherwise it is treated as plain prompt text.

A string is wrapped as { "query": "...", "prompt": "..." }.
A JSON object is passed through; if it has query but no prompt, prompt is filled in from query.

Agent ID & environment variables

The command resolves which agent to call and what env vars to pass as follows:

Item	Resolution
Agent ID	`--agentId` if given; otherwise `status.agent_id` from `.novita-agent.yaml`
Env vars	`spec.envVars` in `.novita-agent.yaml` merged with `--env` — CLI values override the config file

Streaming vs non-streaming

Without --stream, the command waits for the full result and prints the agent ID, session ID, execution time, and the response body. With --stream, output chunks are written to the terminal as they arrive.

Examples

CLI

novita-sandbox-cli agent invoke "Summarize today's news"

CLI

novita-sandbox-cli agent invoke '{"query": "list files", "path": "/tmp"}'

CLI

novita-sandbox-cli agent invoke "Analyze this repo" \
  --agentId my-agent-tpl_123 \
  --stream \
  --env LOG_LEVEL=debug \
  --timeout 120

Get started

Model APIs

Novita Sandbox

GPUs

Observability

Resources

Prerequisites

Usage

Payload

Agent ID & environment variables

Streaming vs non-streaming

Examples

​Prerequisites

​Usage

​Payload

​Agent ID & environment variables

​Streaming vs non-streaming

​Examples

Prerequisites

Usage

Payload

Agent ID & environment variables

Streaming vs non-streaming

Examples