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

# cast invoke

> Invoke a deployed agent

# cast invoke

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

## Usage

```bash theme={null}
cast invoke <slug> [prompt] [options]
```

## Arguments

| Argument | Description        | Required                  |
| -------- | ------------------ | ------------------------- |
| `slug`   | Agent slug         | Yes                       |
| `prompt` | The prompt to send | No (can use `-i` instead) |

## Options

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

## Examples

### Basic invocation

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
# 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

| Error               | Cause               | Fix                                       |
| ------------------- | ------------------- | ----------------------------------------- |
| `Agent not found`   | Invalid slug        | Check `cast agents list` for correct slug |
| `Agent not active`  | Agent not deployed  | Run `cast deploy` first                   |
| `Timeout exceeded`  | Agent took too long | Optimize your agent                       |
| `Invocation failed` | Agent error         | Check agent logs in dashboard             |

## See Also

* [cast deploy](/cli/deploy) — Deploy an agent
* [SDK invoke](/sdk/agents#invokeslug-options) — Invoke programmatically