Update to CrowdStrike AgentWorks

{
  "description": "Invoke Charlotte AI AgentWorks agents and manage invocations. Invoke published agents or specific versions, stream results, get messages, and cancel runs. Uses native FalconPy classes (`AgentInvocation`, `Stream`). TRIGGER when user asks to invoke an agent, run an agent, get agent results/messages, or cancel an invocation. DO NOT TRIGGER for agent creation (use agents skill), knowledge bases (use knowledge-bases skill), or discovery (use discovery skill).\n",
  "included_files": [
    {
      "relative_path": "scripts/cancel_invocation.py",
      "size_in_bytes": 2566
    },
    {
      "relative_path": "scripts/get_messages.py",
      "size_in_bytes": 5548
    },
    {
      "relative_path": "scripts/inspect_invocation.py",
      "size_in_bytes": 8729
    },
    {
      "relative_path": "scripts/invoke_agent.py",
      "size_in_bytes": 4000
    },
    {
      "relative_path": "scripts/invoke_version.py",
      "size_in_bytes": 4078
    },
    {
      "relative_path": "scripts/list_invocations.py",
      "size_in_bytes": 11767
    },
    {
      "relative_path": "scripts/stream_invocation.py",
      "size_in_bytes": 3553
    }
  ],
  "name": "invocation",
  "skill_md_contents": "---\nname: invocation\ndescription: >\n  Invoke Charlotte AI AgentWorks agents and manage invocations.\n  Invoke published agents or specific versions, stream results, get messages, and cancel runs.\n  Uses native FalconPy classes (`AgentInvocation`, `Stream`).\n  TRIGGER when user asks to invoke an agent, run an agent, get agent results/messages, or cancel an invocation.\n  DO NOT TRIGGER for agent creation (use agents skill), knowledge bases (use knowledge-bases skill),\n  or discovery (use discovery skill).\nversion: 1.0.1\nupdated: 2026-10-21\ntags: [agentworks, charlotte, invocation, streaming, falcon]\nauthor: CrowdStrike\nlicense: MIT\ncompatibility: Claude Code >=1.0\nallowed-tools: Bash(cd *), Bash(../../scripts/python.sh:*)\nmetadata:\n  category: agent-execution\n---\n\n# Agent Invocation\n\n> **Read this first.**\n>\n> You are an AI assistant with expertise in Charlotte AI AgentWorks agent invocation.\n> Your role is to help users invoke agents, stream results, get messages, and cancel invocations\n> using native FalconPy classes (`AgentInvocation`, `Stream`).\n>\n> **IMMEDIATE ACTIONS REQUIRED:**\n> 1. Read this entire skill file before taking any action\n> 2. Verify credentials are configured\n> 3. Invoke **published agents** via `invoke_agent.py` OR **specific versions** (including drafts) via `invoke_version.py`\n> 4. Run scripts via `cd ${CLAUDE_PLUGIN_ROOT}/skills/invocation && ../../scripts/python.sh scripts/<script>.py`\n> 5. Parse script output and present results clearly\n>\n> **MUST NOT:**\n> - Invoke unpublished agents using `invoke_agent.py` (will fail with 400) — use `invoke_version.py` instead\n> - Guess invocation IDs — save from invoke response\n> - Poll messages in tight loop (use reasonable intervals)\n\n## Running the scripts\n\n```bash\ncd ${CLAUDE_PLUGIN_ROOT}/skills/invocation\n../../scripts/python.sh scripts/<script_name>.py [args]\n```\n\n- **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.\n- **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.\n\n## Prerequisites\n\n- **Credentials**: Same as other skills\n- **API scopes**: `csrn:charlotte-ai:agent:invocation` (assert/execute)\n- **Agent publishing**:\n  - `invoke_agent.py` requires **published agents** (invokes latest published version)\n  - `invoke_version.py` can invoke **any version** (published or draft) by specifying version_id\n\n## Core Workflow\n\n1. **List recent invocations** → `list_invocations.py --agent-id <agent-id> --limit 10` → shows recent invocation IDs\n2. **Invoke agent** → `invoke_agent.py --id <agent-id> --message \"Hello\"` → returns invocation_id and trace_id\n   - **Optional controls**: `--deadline-seconds <seconds>` (min: 90), `--max-cost <credit-cents>` (100 = 1 credit; max: 10000, integer only) → constrain execution\n3. **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.\n4. **Inspect trace** → `inspect_invocation.py --invocation-id <invocation-id>` → waterfall tree, duration, tool outputs\n5. **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)\n6. **Stream invocation** → `stream_invocation.py --id <invocation-id>` → full conversation once complete (polls; not token-by-token SSE)\n7. **Cancel invocation** → `cancel_invocation.py --id <invocation-id>` → stops in-flight run\n\n## Invocation Controls\n\nWhen invoking agents, you can optionally specify execution constraints:\n\n### Deadline\n\nSet a hard deadline (in seconds) after which the invocation will be terminated:\n\n```bash\n# Stop execution after 5 minutes (300 seconds)\n../../scripts/python.sh scripts/invoke_agent.py \\\n  --id <agent-id> \\\n  --message \"Your task...\" \\\n  --deadline-seconds 300\n```\n\n**Constraints:**\n- **Minimum value: 90 seconds** - Values below 90 are rejected with HTTP 400\n- **Recommended minimum: 120 seconds** for agents with tool calls\n- **Typical values**: 300-600 seconds for standard tasks, 900-1800 for complex operations\n\n**Use cases:**\n- Time-sensitive operations with hard cutoffs\n- Preventing runaway agents from consuming excessive time\n- Integration with external systems that have timeout constraints\n\n### Max Cost\n\nSet a maximum cost in Charlotte credit cents (100 = 1 Charlotte credit) to prevent expensive invocations:\n\n```bash\n# Limit invocation to 10,000 credit cents (100 Charlotte credits — the max allowed)\n../../scripts/python.sh scripts/invoke_agent.py \\\n  --id <agent-id> \\\n  --message \"Your task...\" \\\n  --max-cost 10000\n```\n\n**Constraints:**\n- **Maximum value: 10000 credit cents (100 Charlotte credits)** - Values above 10000 are rejected with HTTP 400\n- **Must be an integer** - The API rejects non-integer values (e.g. `10000.0`) with a generic 400\n\n**Credit Conversion:**\n- **1 Charlotte credit = 100 credit cents**\n- Example values:\n  - `--max-cost 100` = 1 Charlotte credit\n  - `--max-cost 1000` = 10 Charlotte credits\n  - `--max-cost 10000` = 100 Charlotte credits (the maximum allowed)\n\n**Use cases:**\n- Budget control for exploratory or experimental agents\n- Cost caps for user-facing agents in multi-tenant environments\n- Preventing unexpectedly expensive tool calls or excessive LLM usage\n\n### Combined Controls\n\nBoth parameters can be used together:\n\n```bash\n../../scripts/python.sh scripts/invoke_agent.py \\\n  --id <agent-id> \\\n  --message \"Analyze recent detections\" \\\n  --deadline-seconds 600 \\\n  --max-cost 10000\n```\n\n**Behavior when limits are reached:**\n- The invocation is terminated gracefully\n- Partial results (if any) are available via `get_messages.py`\n- Trace shows termination reason in span attributes\n\n**Note:** `max_cost` is expressed in **credit cents** where 100 = 1 Charlotte credit, capped at 10000 (100 Charlotte credits).\n\n### Monitoring Invocation Costs\n\nAfter an invocation completes, you can inspect the actual cost incurred by fetching the\ntrace and reading its `cost.*` attributes -- there is no separate `cost` span_type; cost\nlives directly on the spans a normal trace query already returns (confirmed against a live\ntenant, 2026-09-23):\n\n```bash\n# Get the trace_id from the invocation response, then fetch the full trace.\ncd ${CLAUDE_PLUGIN_ROOT}/skills/discovery\n../../scripts/python.sh scripts/spans_search.py \\\n  --filter \"trace_id:'<trace-id>'+start_time:>='now-24h'\" \\\n  --limit 500\n# Hydrate the returned span IDs with spans_get.py, then read cost.* off the\n# aw_agent_response / llm spans (see below) -- no additional filter needed.\n```\n\n**Cost attributes (on `aw_agent_response`/`llm` spans):**\n- `cost.agg_credit_cents` — total cost for the whole invocation (on the `aw_agent_response` span)\n- `cost.raw_credit_cents` — per-LLM-call cost (on individual `llm` spans)\n- `cost.reserved_credit_cents` — the budget that was *reserved* for the invocation, not what\n  was actually spent (confirmed live: on a failed/timed-out invocation, `agg_credit_cents`\n  was `0` while `reserved_credit_cents` still showed the reserved amount) -- don't mistake it\n  for actual cost.\n- `cost.was_quota_consumed` — whether the invocation was charged against quota vs. credits\n\n**Use cases:**\n- Verify actual cost vs. budget after invocation completes\n- Analyze cost trends across multiple invocations\n- Identify expensive agents or operations for optimization\n- Generate cost reports for billing/accounting\n\n## Script Reference\n\n| Script | Purpose | Key Flags |\n|--------|---------|-----------|\n| `list_invocations.py` | List recent invocations for an agent | `--agent-id <uuid>`, `--limit 10`, `--days 7` |\n| `invoke_agent.py` | Invoke latest **published** version of an agent | `--id <agent-id>`, `--message \"...\"`, `--deadline-seconds <seconds>` (min: 90), `--max-cost <credit-cents>` (100 = 1 credit; max: 10000, integer only) |\n| `invoke_version.py` | Invoke **specific version** (published or draft) | `--agent-id`, `--version-id <uuid>`, `--message`, `--deadline-seconds`, `--max-cost` — returns `invocation_id`; feed that straight into `inspect_invocation.py --invocation-id` (it resolves its own `trace_id`) |\n| `get_messages.py` | Get conversation from invocation | `--id <invocation-id>`, `--wait` (block until terminal status, backoff 5s→20s), `--timeout <seconds>` (default 300, only with `--wait`) |\n| `inspect_invocation.py` | Inspect invocation trace (waterfall + tool outputs) | `--invocation-id` (required), `--tool-output-only`, `--errors-only` (only show tool spans that errored), `--json` |\n| `cancel_invocation.py` | Cancel in-flight invocation | `--id <invocation-id>` |\n| `stream_invocation.py` | Stream invocation results (polls; returns full conversation) | `--id <invocation-id>` |\n\n## Usage Examples\n\n### List recent invocations for an agent\n```bash\n../../scripts/python.sh scripts/list_invocations.py \\\n  --agent-id <agent-id> \\\n  --limit 10\n\n# Shows:\n# - Invocation IDs\n# - Timestamps\n# - Duration\n# - Status (✅ success / ❌ error)\n# - Span count\n```\n\n### Invoke a published agent\n```bash\n../../scripts/python.sh scripts/invoke_agent.py \\\n  --id <agent-id> \\\n  --message \"Investigate detection XYZ for unauthorized access\"\n# Returns: invocation_id and trace_id\n# Use invocation_id with inspect_invocation.py to view execution details\n```\n\n**With execution controls:**\n```bash\n# With deadline (minimum 90 seconds)\n../../scripts/python.sh scripts/invoke_agent.py \\\n  --id <agent-id> \\\n  --message \"Investigate detection XYZ\" \\\n  --deadline-seconds 300\n\n# With max cost (credit cents: 100 = 1 Charlotte credit)\n../../scripts/python.sh scripts/invoke_agent.py \\\n  --id <agent-id> \\\n  --message \"Analyze vulnerabilities\" \\\n  --max-cost 10000\n\n# With both\n../../scripts/python.sh scripts/invoke_agent.py \\\n  --id <agent-id> \\\n  --message \"Comprehensive security audit\" \\\n  --deadline-seconds 900 \\\n  --max-cost 10000\n```\n\n### Invoke a specific version (draft or published), then inspect its trace\n```bash\n../../scripts/python.sh scripts/invoke_version.py \\\n  --agent-id <agent-id> \\\n  --version-id <version-id> \\\n  --message \"Investigate detection XYZ\"\n# Returns: invocation_id (no trace_id printed directly -- inspect_invocation.py\n# resolves its own trace_id from the invocation_id, so this is enough)\n\n../../scripts/python.sh scripts/get_messages.py --id <invocation-id> --wait\n# Blocks until the invocation reaches a terminal status\n\n../../scripts/python.sh scripts/inspect_invocation.py --invocation-id <invocation-id>\n# Waterfall + tool outputs for this specific version's run\n```\n\n### Get invocation messages\n```bash\n../../scripts/python.sh scripts/get_messages.py \\\n  --id abc123-invocation-id\n```\n\n### Inspect full trace (waterfall + tool outputs)\n```bash\n../../scripts/python.sh scripts/inspect_invocation.py \\\n  --invocation-id abc123-invocation-id\n\n# Shows:\n# - Waterfall tree visualization\n# - Total invocation duration\n# - Per-span durations\n# - Tool outputs with attributes\n```\n\n### Inspect invocation cost\n```bash\n# First, get the trace_id from the invocation (returned by invoke_agent.py)\nTRACE_ID=\"<trace-id-from-invocation>\"\n\n# Fetch the full trace using the discovery skill -- cost lives in attributes\n# on the spans this already returns, there is no separate \"cost\" span_type.\ncd ${CLAUDE_PLUGIN_ROOT}/skills/discovery\n../../scripts/python.sh scripts/spans_search.py \\\n  --filter \"trace_id:'${TRACE_ID}'+start_time:>='now-24h'\" \\\n  --limit 500\n\n# Hydrate the returned span IDs, then read cost.agg_credit_cents off the\n# aw_agent_response span (total) or cost.raw_credit_cents off individual\n# llm spans (per-call):\n../../scripts/python.sh scripts/spans_get.py --ids <span-id>\n\n# Shows:\n# - Total cost in credit cents\n# - Cost breakdown by resource type\n# - Model-specific costs\n# - Token usage metrics\n```\n\n### Inspect only tool outputs\n```bash\n../../scripts/python.sh scripts/inspect_invocation.py \\\n  --invocation-id abc123-invocation-id \\\n  --tool-output-only\n```\n\n### Cancel running invocation\n```bash\n../../scripts/python.sh scripts/cancel_invocation.py \\\n  --id abc123-invocation-id\n```\n\n### Stream invocation results\n```bash\n../../scripts/python.sh scripts/stream_invocation.py \\\n  --id abc123-invocation-id\n# Note: FalconPy limitation - returns full conversation after completion, not true SSE\n```\n\n## Common Pitfalls / Counter-Rationalizations\n\n| Thought | Reality |\n|---------|---------|\n| \"I'll invoke the draft agent with invoke_agent.py\" | **Use invoke_version.py for drafts.** `invoke_agent.py` only invokes the latest **published** version. To test draft/unpublished versions, use `invoke_version.py --agent-id <id> --version-id <version-uuid>`. |\n| \"I need a :draft-invocation scope to invoke drafts\" | **No special scope needed.** The base `:invocation` scope covers both published and draft version invocations. Use `invoke_version.py` with the draft's version_id. |\n| \"I'll set a deadline 30 seconds from now for a complex task\" | **Minimum 90 seconds required.** The API rejects `deadline_seconds` values below 90 with HTTP 400. Set realistic deadlines: 120+ for simple tasks, 300-600 for standard operations, 900+ for complex workflows. |\n| \"Max cost is just a suggestion\" | **Max cost is a hard limit.** The invocation terminates when the limit (in credit cents: 100 = 1 Charlotte credit) is reached. Set appropriate budgets or omit the parameter for unbounded execution. |\n| \"I can pass any value for --max-cost\" | **Capped at 10000 and integer-only.** The API rejects values above 10000 credit cents (100 Charlotte credits) with a 400, and rejects non-integer values (e.g. `10000.0`) with a generic \"invalid ... invocation request\" error. |\n| \"Cost is in the invocation response\" | **Cost is in trace span attributes.** Fetch the trace (discovery skill) and read `cost.agg_credit_cents`/`cost.raw_credit_cents` off its spans -- there's no separate `cost` span_type. The invocation response doesn't include cost data. |\n| \"I can see costs in get_messages output\" | **Cost is on the trace's spans.** Use the discovery skill to fetch the trace_id's spans and read `cost.*` attributes. Messages don't contain cost information. |\n| \"Invocation ID = agent ID\" | **Different UUIDs.** Invocation ID is returned from invoke call; don't reuse agent ID. |\n| \"I'll poll messages every 100ms\" | **Rate limit risk.** Use reasonable intervals (1-5s) or use streaming. |\n| \"Streaming uses /agentic-studio base\" | **Wrong base.** Streaming uses `/agentic-studio-streaming/` base path. |\n| \"Tool outputs are in messages\" | **Tool outputs are in trace spans.** Use `inspect_invocation.py` to see invocation waterfall, duration, and raw tool outputs. |\n| \"I need a dedicated endpoint to list invocations\" | **Use spans APIs.** Query spans by `agent_id`, extract `invocation_id` from attributes. Use `list_invocations.py`. |\n\n"
}