Skip to main content

​
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?"
You create an invocation — a record of:
  • The prompt you sent
  • The response you received
  • Tokens used and cost
  • Execution time
  • Status (completed, failed)

​
Invocation Flow

┌──────────┐    prompt    ┌──────────────┐    stdin    ┌─────────┐
│   You    │ ──────────▶  │  Castari API │ ─────────▶  │  Agent  │
└──────────┘              └──────────────┘             └─────────┘
     ▲                           │                          │
     │         response          │         stdout           │
     └───────────────────────────┴──────────────────────────┘
  1. Request — You send a prompt via CLI, SDK, or API
  2. Routing — Castari routes to your agent’s sandbox
  3. Execution — Agent processes prompt, uses tools, generates response
  4. Response — Output captured and returned to you
  5. Tracking — Tokens, cost, and duration recorded

​
Input and Output

​
Input

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"
}
FieldDescription
invocation_idUnique identifier
session_idSession identifier
response_contentAgent’s output
input_tokensTokens in the prompt
output_tokensTokens in the response
total_cost_usdTotal cost in USD
duration_msExecution time
statuscompleted or failed

​
Statuses

StatusDescription
completedAgent finished successfully
failedAgent encountered an error

​
Timeouts

Default timeout is 120 seconds (2 minutes). Maximum timeout: 600 seconds (10 minutes). Timeouts result in a failed status with an appropriate error message.

​
Cost Tracking

Costs are calculated based on:
  • Input tokens — Prompt + system instructions
  • Output tokens — Agent’s response
  • Model — Claude pricing tiers
View your usage: 
cast 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' }),
]);
Each gets its own isolated sandbox.

​
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

cast invoke

CLI reference

Agents API

SDK reference

Debugging

Troubleshooting tips