Agent Invocation

Read this first.

You are an AI assistant with expertise in Charlotte AI AgentWorks agent invocation. Your role is to help users invoke agents, stream results, get messages, and cancel invocations using native FalconPy classes (AgentInvocation, Stream).

IMMEDIATE ACTIONS REQUIRED:

1. Read this entire skill file before taking any action
2. Verify credentials are configured
3. Invoke published agents via invoke_agent.py OR specific versions (including drafts) via invoke_version.py
4. Run scripts via cd ${CLAUDE_PLUGIN_ROOT}/skills/invocation && ../../scripts/python.sh scripts/<script>.py
5. Parse script output and present results clearly

MUST NOT:

• Invoke unpublished agents using invoke_agent.py (will fail with 400) — use invoke_version.py instead
• Guess invocation IDs — save from invoke response
• Poll messages in tight loop (use reasonable intervals)

Running the scripts

cd ${CLAUDE_PLUGIN_ROOT}/skills/invocation
../../scripts/python.sh scripts/<script_name>.py [args]

• Claude Code: ${CLAUDE_PLUGIN_ROOT} is substituted with the plugin's install path before this text reaches the model. Use the braced form; a bare $CLAUDE_PLUGIN_ROOT is never exported into the Bash tool's shell.
• Other hosts (Codex, Copilot CLI, Cursor, Antigravity): these don't set CLAUDE_PLUGIN_ROOT. cd to the folder you loaded this SKILL.md from (e.g. ~/.agents/skills/invocation) and run ../../scripts/python.sh scripts/<script_name>.py [args] from there.

Prerequisites

• Credentials: Same as other skills
• API scopes: csrn:charlotte-ai:agent:invocation (assert/execute)
• Agent publishing:
  • invoke_agent.py requires published agents (invokes latest published version)
  • invoke_version.py can invoke any version (published or draft) by specifying version_id

Core Workflow

1. List recent invocations → list_invocations.py --agent-id <agent-id> --limit 10 → shows recent invocation IDs
2. Invoke agent → invoke_agent.py --id <agent-id> --message "Hello" → returns invocation_id and trace_id
   • Optional controls: --deadline-seconds <seconds> (min: 90), --max-cost <credit-cents> (100 = 1 credit; max: 10000, integer only) → constrain execution
3. Get messages → get_messages.py --id <invocation-id> --wait → blocks (backoff 5s→20s, default 300s timeout) until the invocation reaches a terminal status, then returns conversation messages. Add --timeout <seconds> to change the max wait. Omit --wait to just fetch the current state once, e.g. for a quick status check without blocking.
4. Inspect trace → inspect_invocation.py --invocation-id <invocation-id> → waterfall tree, duration, tool outputs
5. Inspect cost → Fetch the trace (discovery skill) and read cost.agg_credit_cents/cost.raw_credit_cents off its spans → actual cost in credit cents (no separate cost span_type -- see "Monitoring Invocation Costs" below)
6. Stream invocation → stream_invocation.py --id <invocation-id> → full conversation once complete (polls; not token-by-token SSE)
7. Cancel invocation → cancel_invocation.py --id <invocation-id> → stops in-flight run

Invocation Controls

When invoking agents, you can optionally specify execution constraints:

Deadline

Set a hard deadline (in seconds) after which the invocation will be terminated:

# Stop execution after 5 minutes (300 seconds)
../../scripts/python.sh scripts/invoke_agent.py \
  --id <agent-id> \
  --message "Your task..." \
  --deadline-seconds 300

Constraints:

• Minimum value: 90 seconds - Values below 90 are rejected with HTTP 400
• Recommended minimum: 120 seconds for agents with tool calls
• Typical values: 300-600 seconds for standard tasks, 900-1800 for complex operations

Use cases:

• Time-sensitive operations with hard cutoffs
• Preventing runaway agents from consuming excessive time
• Integration with external systems that have timeout constraints

Max Cost

Set a maximum cost in Charlotte credit cents (100 = 1 Charlotte credit) to prevent expensive invocations:

# Limit invocation to 10,000 credit cents (100 Charlotte credits — the max allowed)
../../scripts/python.sh scripts/invoke_agent.py \
  --id <agent-id> \
  --message "Your task..." \
  --max-cost 10000

Constraints:

• Maximum value: 10000 credit cents (100 Charlotte credits) - Values above 10000 are rejected with HTTP 400
• Must be an integer - The API rejects non-integer values (e.g. 10000.0) with a generic 400

Credit Conversion:

• 1 Charlotte credit = 100 credit cents
• Example values:
  • --max-cost 100 = 1 Charlotte credit
  • --max-cost 1000 = 10 Charlotte credits
  • --max-cost 10000 = 100 Charlotte credits (the maximum allowed)

Use cases:

• Budget control for exploratory or experimental agents
• Cost caps for user-facing agents in multi-tenant environments
• Preventing unexpectedly expensive tool calls or excessive LLM usage

Combined Controls

Both parameters can be used together:

../../scripts/python.sh scripts/invoke_agent.py \
  --id <agent-id> \
  --message "Analyze recent detections" \
  --deadline-seconds 600 \
  --max-cost 10000

Behavior when limits are reached:

• The invocation is terminated gracefully
• Partial results (if any) are available via get_messages.py
• Trace shows termination reason in span attributes

Note: max_cost is expressed in credit cents where 100 = 1 Charlotte credit, capped at 10000 (100 Charlotte credits).

Monitoring Invocation Costs

After an invocation completes, you can inspect the actual cost incurred by fetching the trace and reading its cost.* attributes -- there is no separate cost span_type; cost lives directly on the spans a normal trace query already returns (confirmed against a live tenant, 2026-09-23):

# Get the trace_id from the invocation response, then fetch the full trace.
cd ${CLAUDE_PLUGIN_ROOT}/skills/discovery
../../scripts/python.sh scripts/spans_search.py \
  --filter "trace_id:'<trace-id>'+start_time:>='now-24h'" \
  --limit 500
# Hydrate the returned span IDs with spans_get.py, then read cost.* off the
# aw_agent_response / llm spans (see below) -- no additional filter needed.

Cost attributes (on aw_agent_response/llm spans):

• cost.agg_credit_cents — total cost for the whole invocation (on the aw_agent_response span)
• cost.raw_credit_cents — per-LLM-call cost (on individual llm spans)
• cost.reserved_credit_cents — the budget that was reserved for the invocation, not what was actually spent (confirmed live: on a failed/timed-out invocation, agg_credit_cents was 0 while reserved_credit_cents still showed the reserved amount) -- don't mistake it for actual cost.
• cost.was_quota_consumed — whether the invocation was charged against quota vs. credits

Use cases:

• Verify actual cost vs. budget after invocation completes
• Analyze cost trends across multiple invocations
• Identify expensive agents or operations for optimization
• Generate cost reports for billing/accounting

Script Reference

Usage Examples

List recent invocations for an agent

../../scripts/python.sh scripts/list_invocations.py \
  --agent-id <agent-id> \
  --limit 10

# Shows:
# - Invocation IDs
# - Timestamps
# - Duration
# - Status (✅ success / ❌ error)
# - Span count

Invoke a published agent

../../scripts/python.sh scripts/invoke_agent.py \
  --id <agent-id> \
  --message "Investigate detection XYZ for unauthorized access"
# Returns: invocation_id and trace_id
# Use invocation_id with inspect_invocation.py to view execution details

With execution controls:

# With deadline (minimum 90 seconds)
../../scripts/python.sh scripts/invoke_agent.py \
  --id <agent-id> \
  --message "Investigate detection XYZ" \
  --deadline-seconds 300

# With max cost (credit cents: 100 = 1 Charlotte credit)
../../scripts/python.sh scripts/invoke_agent.py \
  --id <agent-id> \
  --message "Analyze vulnerabilities" \
  --max-cost 10000

# With both
../../scripts/python.sh scripts/invoke_agent.py \
  --id <agent-id> \
  --message "Comprehensive security audit" \
  --deadline-seconds 900 \
  --max-cost 10000

Invoke a specific version (draft or published), then inspect its trace

../../scripts/python.sh scripts/invoke_version.py \
  --agent-id <agent-id> \
  --version-id <version-id> \
  --message "Investigate detection XYZ"
# Returns: invocation_id (no trace_id printed directly -- inspect_invocation.py
# resolves its own trace_id from the invocation_id, so this is enough)

../../scripts/python.sh scripts/get_messages.py --id <invocation-id> --wait
# Blocks until the invocation reaches a terminal status

../../scripts/python.sh scripts/inspect_invocation.py --invocation-id <invocation-id>
# Waterfall + tool outputs for this specific version's run

Get invocation messages

../../scripts/python.sh scripts/get_messages.py \
  --id abc123-invocation-id

Inspect full trace (waterfall + tool outputs)

../../scripts/python.sh scripts/inspect_invocation.py \
  --invocation-id abc123-invocation-id

# Shows:
# - Waterfall tree visualization
# - Total invocation duration
# - Per-span durations
# - Tool outputs with attributes

Inspect invocation cost

# First, get the trace_id from the invocation (returned by invoke_agent.py)
TRACE_ID="<trace-id-from-invocation>"

# Fetch the full trace using the discovery skill -- cost lives in attributes
# on the spans this already returns, there is no separate "cost" span_type.
cd ${CLAUDE_PLUGIN_ROOT}/skills/discovery
../../scripts/python.sh scripts/spans_search.py \
  --filter "trace_id:'${TRACE_ID}'+start_time:>='now-24h'" \
  --limit 500

# Hydrate the returned span IDs, then read cost.agg_credit_cents off the
# aw_agent_response span (total) or cost.raw_credit_cents off individual
# llm spans (per-call):
../../scripts/python.sh scripts/spans_get.py --ids <span-id>

# Shows:
# - Total cost in credit cents
# - Cost breakdown by resource type
# - Model-specific costs
# - Token usage metrics

Inspect only tool outputs

../../scripts/python.sh scripts/inspect_invocation.py \
  --invocation-id abc123-invocation-id \
  --tool-output-only

Cancel running invocation

../../scripts/python.sh scripts/cancel_invocation.py \
  --id abc123-invocation-id

Stream invocation results

../../scripts/python.sh scripts/stream_invocation.py \
  --id abc123-invocation-id
# Note: FalconPy limitation - returns full conversation after completion, not true SSE

Common Pitfalls / Counter-Rationalizations