Invocations
An invocation is a single request-response cycle with an agent.
What is an Invocation?
When you run:
cast invoke my-agent "What files are here?"
- The prompt you sent
- The response you received
- Tokens used and cost
- Execution time
- Status (completed, failed, timeout)
Invocation Flow
┌──────────┐ prompt ┌──────────────┐ stdin ┌─────────┐
│ You │ ──────────▶ │ Castari API │ ─────────▶ │ Agent │
└──────────┘ └──────────────┘ └─────────┘
▲ │ │
│ response │ stdout │
└───────────────────────────┴──────────────────────────┘
- Request — You send a prompt via CLI, SDK, or API
- Routing — Castari routes to your agent’s sandbox
- Execution — Agent processes prompt, uses tools, generates response
- Response — Output captured and returned to you
- Tracking — Tokens, cost, and duration recorded
Your prompt is passed to the agent via stdin:
// Agent reads from stdin
let prompt = "";
process.stdin.on("data", (chunk) => (prompt += chunk));
process.stdin.on("end", () => {
// Process prompt
});
Output
Agent response is written to stdout:
// Agent writes to stdout
console.log(response);
Only stdout is captured as the response. stderr is logged but not returned.
Invocation Result
Every invocation returns:
{
invocation_id: "inv_abc123",
session_id: "sess_xyz789",
response_content: "The current directory contains...",
input_tokens: 124,
output_tokens: 1110,
total_cost_usd: 0.02,
duration_ms: 2341,
status: "completed"
}
| Field | Description |
|---|
invocation_id | Unique identifier |
session_id | Session identifier |
response_content | Agent’s output |
input_tokens | Tokens in the prompt |
output_tokens | Tokens in the response |
total_cost_usd | Total cost in USD |
duration_ms | Execution time |
status | completed or failed |
Statuses
| Status | Description |
|---|
completed | Agent finished successfully |
failed | Agent encountered an error |
timeout | Execution exceeded time limit |
Timeouts
Default timeout is 120 seconds (2 minutes). Maximum timeout: 600 seconds (10 minutes).
Cost Tracking
Costs are calculated based on:
- Input tokens — Prompt + system instructions
- Output tokens — Agent’s response
- Model — Claude pricing tiers
View your usage:
Concurrency
Multiple invocations can run in parallel:
// These run concurrently in separate sandboxes
const results = await Promise.all([
client.agents.invoke('my-agent', { prompt: 'Task 1' }),
client.agents.invoke('my-agent', { prompt: 'Task 2' }),
client.agents.invoke('my-agent', { prompt: 'Task 3' }),
]);
Error Handling
In CLI
cast invoke my-agent "Bad request"
# Error: Agent execution failed
In SDK
try {
const result = await client.agents.invoke('my-agent', { prompt });
} catch (error) {
if (error instanceof CastariError) {
console.log(error.status); // 500
console.log(error.message); // "Agent execution failed"
}
}
See Also
