Skip to main content

​
cast invoke

Send a prompt to a deployed agent and get a response.

​
Usage

cast invoke <slug> [prompt] [options]

​
Arguments

ArgumentDescriptionRequired
slugAgent slugYes
promptThe prompt to sendNo (can use -i instead)

​
Options

OptionDescription
-i, --input <file>Read prompt from a file
-s, --session <id>Session ID for conversation continuity (reuses sandbox)

​
Examples

​
Basic invocation

cast invoke my-agent "What files are in the current directory?"
Output: 
The current directory contains:
- src/index.ts
- package.json
- castari.json
- CLAUDE.md
- README.md

​
Read prompt from a file

cast invoke my-agent -i prompt.txt
Useful for longer prompts or multi-line input.

​
Multi-turn conversations

Use the -s, --session option to maintain conversation history: 
# Start a session
cast invoke my-agent "Create a file called hello.txt" -s my-session

# Continue the same session (sandbox state preserved)
cast invoke my-agent "What's in the file you just created?" -s my-session
With session IDs, the agent’s sandbox persists between invocations, allowing multi-turn conversations and stateful interactions.

​
What Happens During Invoke

  1. Request received — Your prompt is sent to the Castari API
  2. Sandbox activated — A sandbox is spun up (or reused if session specified)
  3. Agent runs — Your agent code executes with the prompt as input
  4. Response collected — Output is captured and returned to you
  5. Cleanup — Without a session, sandbox is destroyed. With a session, it persists.

​
Errors

ErrorCauseFix
Agent not foundInvalid slugCheck cast agents list for correct slug
Agent not activeAgent not deployedRun cast deploy first
Timeout exceededAgent took too longOptimize your agent
Invocation failedAgent errorCheck agent logs in dashboard

​
See Also