beam-ai-team/beam-credit-analysis

Beam Credit Analysis

Analyze a Beam.ai agent's credit consumption and cost across all execution paths, based on the latest Beam pricing model.

Purpose

Given a Beam agent URL (or graph JSON), this skill:

1. Fetches the agent graph from the Beam API
2. Traces all possible execution paths from entry to exit
3. Generates a mermaid flow diagram of the architecture
4. Calculates node counts, credit consumption, and cost per path
5. Produces a structured markdown report with per-branch breakdowns

Pricing source: Beam Credits (New Agent OS)

Time Estimate: 2-3 minutes

---

Safety Contract

This skill is read-only for Beam state. Before saving or sharing cost reports, show the workspace, agent ID or graph file, output destination, pricing assumptions, and any customer-sensitive details included. Require explicit user approval in the current turn before exporting reports outside the local workspace. Do not create tasks, update graphs, publish changes, or alter pricing data from this skill.

---

Workflow

Step 1: Get Agent URL

Ask user for the Beam agent URL. Accepted formats:

• https://app.beam.ai/{workspace_id}/{agent_id}/flow
• https://app.enterprise.beam.ai/{workspace_id}/{agent_id}/flow
• Or separate workspace ID + agent ID
• Or a path to an already-downloaded graph JSON file

If URL contains enterprise.beam, the script auto-detects and uses https://api.enterprise.beamstudio.ai.

---

Step 2: Check for Model Overrides

Ask if any models in the agent have been changed from their defaults. Common scenario: a node originally using Gemini 3 Pro was switched to GPT 5.2.

If overrides exist, pass them to the script as --model-override OLD=NEW.

Example: --model-override GEMINI_3_PRO=GPT_5_2

---

Step 3: Verify Configuration

Check that BEAM_API_KEY exists in .env:

grep "BEAM_API_KEY" .env

If missing, ask user to provide it and add to .env.

Skip this step if user provides a --graph-file instead of a URL.

---

Step 4: Run Analysis Script

Execute the analysis script:

From URL:

python3 03-skills/beam-credit-analysis/scripts/analyze_agent_credits.py "AGENT_URL" --model-override GEMINI_3_PRO=GPT_5_2

From local graph file:

python3 03-skills/beam-credit-analysis/scripts/analyze_agent_credits.py --graph-file ./path/to/graph.json

With custom output directory:

python3 03-skills/beam-credit-analysis/scripts/analyze_agent_credits.py "AGENT_URL" --output ./custom/path

For JSON output (programmatic):

python3 03-skills/beam-credit-analysis/scripts/analyze_agent_credits.py "AGENT_URL" --json

---

Step 5: Review Output

The script generates a markdown file containing:

1. Credit Rates — Rates used for calculation with source reference
2. Architecture Overview — Branch descriptions and mermaid flow diagram
3. Per-Branch Tables (for each branch):
   • Node Count — Flash, Premium, Integration, Trigger counts per path
   • Credit Consumption — Credits per node type per path
   • Cost — Dollar cost per node type per path (using actual model rates from Notion pricing)
4. Summary — All paths with total nodes, credits, and cost
5. Eval Impact — Credits and cost if eval is enabled on all GPT nodes
6. Step-by-Step Breakdowns — Top 3 most expensive paths with per-node detail
7. Node Inventory — All Custom GPT and Integration nodes with models and rates

---

Step 6: Present Results to User

Show the user:

• File path of the generated analysis
• Summary table (all paths with total nodes, credits, cost)
• The mermaid diagram (renders in GitHub markdown)
• Highlight the cheapest and most expensive paths
• Note any assumptions (e.g., GPT 5.2 pricing estimated from GPT 5)

---

Script Reference

analyze_agent_credits.py

Arguments:

| Argument | Required | Description | |----------|----------|-------------| | url | Yes* | Beam agent URL | | --workspace-id | Alt* | Workspace ID (if not using URL) | | --agent-id | Alt* | Agent ID (if not using URL) | | --graph-file | Alt* | Path to local graph JSON (skip API) | | --base-url | No | API base URL override | | --output | No | Output directory | | --model-override | No | Model name override (repeatable) | | --pricing-file | No | Custom pricing.json path | | --json | No | Output raw JSON instead of markdown |

*One of: URL, workspace+agent IDs, or graph-file is required.

Exit codes:

• 0 = Success
• 1 = Error (auth, network, missing config)

---

Pricing Updates

The pricing reference is stored at references/pricing.json. To update:

1. Check the Beam Credits Notion page for changes
2. Update references/pricing.json with new rates
3. Update the last_updated field in _meta

The script supports both UPPER_CASE and lower-case model name formats for flexibility.

---

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | BEAM_API_KEY not found | Missing from .env | Add to .env file | | Auth failed (401) | Invalid or expired API key | Check BEAM_API_KEY | | Graph fetch failed (404) | Invalid agent/workspace ID | Verify URL is correct | | No paths found | Graph has no entry nodes | Check agent is properly configured | | Model not in pricing | New model not yet in pricing.json | Update pricing.json or use --model-override |

---

Resources

scripts/

• analyze_agent_credits.py — Main analysis engine (fetch, trace, calculate, generate)

references/

• pricing.json — Beam credit rates per model and node type (from Notion)

---

Related Skills

• get-beam-agent-graph — Fetch and save agent graph JSON (used internally)
• calculate-beam-agent-pricing — Design node architecture and calculate pricing from requirements