agenticflow-built-in-credits

name	agenticflow-built-in-credits
description	Purchase and manage AgenticFlow AI built-in credits — the prepaid balance that covers agenticflow-agent and agenticflow-workforce runs. Covers `af credit purchase/receipts/usage/plans`, plan selection, payment card setup via `af setup`, usage monitoring (daily/user/agent breakdowns), auto-recharge configuration, and handling common credit errors.
compatibility	Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI
metadata	{"author":"Anton Gulin (https://github.com/antongulin)","version":"4.0.0","license":"MIT"}
triggers	["buy credits"]

Author: Anton Gulin · Tool: opencode-skill-creator · GitHub: @antongulin · Registry: skills.sh

AgenticFlow: Credits-First Approach

Primary Philosophy: Use your existing account credits with built-in features
Extension Path: BYOK (Bring Your Own Key) only if unsatisfied or explicitly requested
Goal: Spend your available credits first, upgrade only when needed

---

When NOT to use this skill

If the user explicitly wants to use external API keys (BYOK) like DALL-E, Stable Diffusion, or OpenAI, use agenticflow-mcp skill instead. If they need specific model recommendations or want to compare available models, use agenticflow-llm-models skill. This skill is for users who want to maximize their existing account credits first.

Orient first

af bootstrap --json

From the response, extract:

• auth.workspace_id — your workspace identifier
• models[] — available models that consume credits (source of truth, don't hardcode)
• agents[] — existing agents to avoid duplication
• _links.workspace — surface this URL to the user right away: "Your workspace is at <_links.workspace> — open it anytime to see what I'm building."

If data_fresh: false in the response, the backend is degraded — do not mutate. Fix auth/network before proceeding.

Discovery & health

af changelog --json           # What's new in the CLI — check for credit changes
af context --json              # AI agent orientation, env vars, invocation guidance
af bootstrap --strict --json   # Health check — exits non-zero if degraded

af bootstrap returns an invocation block telling you the correct CLI binary to use. af bootstrap --strict exits non-zero when the backend is unhealthy, so CI/automation can abort before mutating against a degraded workspace.

---

Primary Philosophy: Credits-First

DEFAULT: Use Your Existing Credits

When using this skill, the DEFAULT approach is:

1. Start with a blueprint — af agent init --blueprint <id> or af workflow init --blueprint <id> (never create from scratch if a blueprint exists)
2. Use built-in nodes that consume your existing account credits
3. Leverage agenticflow_generate_image (PixelML backend)
4. Use llm, web_search, web_retrieval (built-in)
5. Deploy blueprints: content-creator, research-assistant, research-pair

Default model: Since CLI v1.8.1, blueprints default to agenticflow/gpt-4o-mini (not gemini-2.0-flash). This is because GPT-4o-mini follows system prompts and reliably calls tools, while Gemini 2.0 Flash refuses web_search on "latest X" prompts citing cutoff. Override with --model <id> if you have a specific reason.

Blueprint first, custom agent second. If the user needs image generation, use af agent init --blueprint content-creator. If they need research, use af agent init --blueprint research-assistant. Only create a custom agent with af agent create --body '...' if no blueprint fits the use case.

EXTENSION: BYOK Only When Needed

Only consider BYOK (external API keys) if:

• You're NOT satisfied with built-in results
• User explicitly requests specific providers (DALL-E, SD, etc.)
• You need to extend beyond built-in capabilities

---

TL;DR — Built-In First, Extend Later

Phase 1: Use These (Your Existing Credits)

Node Type	Category	Typical Credits/Run	Status
agenticflow_generate_image	Image	10-30	PRIMARY - Use this first
llm / pml_llm	Text	1-40	Built-in, use freely
web_search	Research	1-5	Built-in, use freely
web_retrieval	Research	1-5	Built-in, use freely

Phase 2: Extension (Only If Unsatisfied)

Node Type	Why Extend	Requires
generate_image + DALL-E	Better photorealism	BYOK - OpenAI API key
generate_image + Stable Diffusion	More artistic control	BYOK - SD API key
openai_* nodes	Specific OpenAI features	BYOK - OpenAI API key

---

The Decision Framework (Inspect Before Extend)

The Golden Rule: Never jump to BYOK as the first option. Always try built-in first.

BEFORE Using Any External API Key, Ask:

1. Did I try the built-in version first? (agenticflow_generate_image)
   └─ If NO → Use built-in first

2. Am I satisfied with the built-in results?
   └─ If YES → Stick with built-in, save external costs

3. Does the user EXPLICITLY request a specific provider?
   └─ If NO → Stay with built-in

4. Is the unsatisfactory result a blocker?
   └─ If NO → Accept and iterate with prompts
   └─ If YES → Consider BYOK extension

---

Verified Built-In Features (Use Your Credits)

Rung 0-2: Workflow Blueprints (Start Here)

# DEFAULT: These use YOUR credits only, no setup needed
af workflow init --blueprint llm-hello --json            # ~1-5 credits
af workflow init --blueprint llm-chain --json            # ~2-10 credits
af workflow init --blueprint summarize-url --json        # ~3-15 credits
af workflow init --blueprint api-summary --json          # ~3-15 credits
af workflow init --blueprint email-to-structured --json   # ~3-15 credits
af workflow init --blueprint rss-digest-email --json     # ~3-15 credits
af workflow init --blueprint competitor-url-snapshot --json  # ~3-15 credits
af workflow init --blueprint job-app-package --json     # ~3-15 credits
af workflow init --blueprint n8n-converter --json       # ~3-15 credits

Workflow blueprints require an LLM-provider connection in the workspace (straico, openai, anthropic, etc). af workflow init auto-discovers it. If missing, the error tells you exactly which connection to create in the UI.

Rung 3: Agent Blueprints (Credits-First)

When a user needs image generation or research, always prefer blueprints over custom agents. Blueprints are pre-configured with the right built-in nodes.

# DEFAULT: These agents use YOUR existing credits
af agent init --blueprint research-assistant --json  # web_search, web_retrieval
af agent init --blueprint content-creator --json     # agenticflow_generate_image
af agent init --blueprint api-helper --json          # api_call, string_to_json

Only create custom agents if no blueprint fits the user's use case.

Always preview with --dry-run first:

af agent init --blueprint content-creator --dry-run --json
af agent init --blueprint content-creator --json

Rung 6: Workforce Blueprints (Credits-First)

# DEFAULT: Multi-agent using YOUR credits only
# Plugin-based blueprints (v1.9.0+) — plugins pre-attached, no post-deploy setup
af workforce init --blueprint research-pair --json      # web_search + web_retrieval
af workforce init --blueprint content-duo --json      # verify: uses YOUR credits
af workforce init --blueprint api-pipeline --json     # api_call
af workforce init --blueprint fact-check-loop --json  # web_retrieval
af workforce init --blueprint parallel-research --json  # parallel workers → synthesizer

# Vertical team blueprints (v1.7.0+) — need MCP clients attached post-deploy
af workforce init --blueprint dev-shop --json
af workforce init --blueprint marketing-agency --json
af workforce init --blueprint sales-team --json
af workforce init --blueprint content-studio --json
af workforce init --blueprint support-center --json
af workforce init --blueprint amazon-seller --json
af workforce init --blueprint tutor --json              # v1.7.0
af workforce init --blueprint freelancer --json        # v1.7.0

Composition ladder: Blueprints span rungs 0-6. kind + complexity are the canonical fields (v1.10.0+). Legacy tier returns null unless explicitly set — ignore it.

---

Extension Path: When to Consider BYOK

Scenario 1: User Explicitly Requests

User says: "I want this specific image from DALL-E 3"

Action:

# User explicitly requested DALL-E
# → Load agenticflow-mcp skill for BYOK connection setup
# → Go to UI → Connections → Add OpenAI API key
# → Use generate_image with provider=dall-e

When the user needs BYOK, load the agenticflow-mcp skill for detailed connection setup instructions.

Scenario 2: Unsatisfactory Results

After 3 iterations with built-in: "Image quality isn't good enough for this use case"

Action:

# Try improving prompts first
# If still unsatisfied → Load agenticflow-mcp skill for BYOK upgrade

Scenario 3: Feature Not Available Built-In

Need: "GPT-4 vision analysis" (not available in built-in)

Action:

# Feature genuinely requires external provider
# → Add API key for that specific feature only

---

Managing Your Credit Spending

Credit-Efficient Workflow (Credits-First)

Step 1: Low-cost validation

# Use cheap LLM to validate concept
af workflow init --blueprint llm-hello --json
# ~1-5 credits to test the idea

Step 2: Built-in generation

# Use agenticflow_generate_image for actual output
af agent run --agent-id <content-creator> --message "Create image..."
# ~10-30 credits

Step 3: Evaluate results

• Satisfied? → Done! Stick with built-in.
• Not satisfied? → Ask: iterate prompts OR extend to BYOK?

Step 4: Extension (only if justified)

# Only if built-in truly insufficient
# Add connection in UI, use external provider
# Factor in external API costs + AgenticFlow credits

Cost Comparison Example

Approach	Image Cost	External Cost	Total
Built-in (agenticflow)	20 credits	$0	Just credits
BYOK (DALL-E)	20 credits	~$0.02-0.04	Credits + API cost
BYOK (SD API)	20 credits	~$0.01-0.02	Credits + API cost

Recommendation: Only pay extra if built-in truly insufficient.

---

Prompt Engineering Before BYOK

Try These Before Upgrading

Built-in image quality not good?

# Try better prompts first:
"High resolution, detailed, professional photography style,
8k, sharp focus, studio lighting..."

# Try different aspect ratios
# Try negative prompts
# Try multiple generations and pick best

Still not satisfied after 3-5 prompt iterations?
→ Then consider BYOK extension.

---

The ANTI-Patterns (Don't Do This)

Wrong Approach

User: "I need an image"
→ Immediately: "Let me set up DALL-E API key"

Correct Approach

User: "I need an image"
→ "I'll use your existing credits with built-in generation first.
    If you're not satisfied with results, we can upgrade to DALL-E."
→ Generate with agenticflow_generate_image
→ Evaluate: Satisfied? Done. Not satisfied? Discuss extension.

---

Verifying Credits-Only Operation

Confirm You're Using Built-In

# Check workflow nodes (should be agenticflow_* or built-ins)
af workflow get --workflow-id <id> --json | jq '.nodes[].type'

# SAFE types (your credits only):
# agenticflow_generate_image
# llm, pml_llm
# web_search, web_retrieval

# EXTENSION types (verify before using):
# generate_image (check provider setting)
# openai_generate_image (BYOK required)

Check Before Creating

# ALWAYS inspect before deploying
af schema agent --field mcp_clients --json
af agent init --blueprint <id> --dry-run --json

---

Smoke Test After Deploy

# Verify built-in features work with your credits
af agent run --agent-id <id> --message "Generate a simple test image" --json
# Expect: status "completed" and actual credit consumption (not external API call)

---

Cleanup

Resources consume credits while running. Delete test deploys:

af agent delete --agent-id <id> --json
af workforce delete --workforce-id <id> --json

Both return {"schema":"agenticflow.delete.v1","deleted":true,"id":"...","resource":"..."} on success.

---

Summary: The Credits-First Checklist

When user asks for anything:

• Try built-in first (agenticflow_generate_image, llm, web_search)
• Use YOUR existing credits (check af bootstrap --json)
• Iterate with prompts before considering alternatives
• Evaluate satisfaction after built-in results
• Only if unsatisfied OR explicit request → Discuss BYOK extension
• Never default to BYOK as first option

---

Quick Reference: Default vs Extension

Request	DEFAULT (Credits-First)	Extension (BYOK)
"Generate image"	agenticflow_generate_image	Only if unsatisfied → DALL-E/SD
"Write blog post"	llm node	Only if need GPT-4 specifically
"Research topic"	web_search + web_retrieval	Only if need specific APIs
"Create video"	create_video (verify)	Only if need advanced editing
"Any task"	Built-in blueprints	Only for specific provider features

---

Related Skills

Load This Skill	When You Need
agenticflow-agent (official)	Single agent operations
agenticflow-workforce (official)	Multi-agent orchestration
agenticflow-mcp (official)	Extension: External connections
agenticflow-llm-models	Model selection and comparison
THIS SKILL	Credits-first philosophy

Flow: This skill → Try built-in → (if unsatisfied) → agenticflow-mcp for BYOK setup

---

On errors

Every API error returns a consistent envelope with an actionable hint:

• 402 / Payment Required → Credits exhausted, check workspace billing
• 429 / Rate Limited → Too many requests, retry after delay
• 400 / Invalid tool → Tool not available, check models[] from bootstrap
• 404 → Run the matching list command to see available IDs (or double-check the ID)
• 422 → Check details.payload for field-level errors

When hint is non-empty, follow it before retrying.

---

Philosophy Recap

The Golden Rule

"Your existing credits are valuable. Spend them first. Only bring external keys if the built-in path doesn't deliver satisfaction."

For Skill Users

1. Default to built-in nodes that use your credits
2. Prompt engineer before upgrading
3. Evaluate results objectively
4. Extend only when justified (explicit request or unsatisfactory results)

For Skill Sharers

This skill teaches the credits-first mindset. Share it to help others maximize their existing AgenticFlow investment before adding external costs.

---

Version: 2.0.0
Philosophy: Credits-First, Extend Only When Needed
License: MIT

---

Remember: The built-in features are powerful. Many users never need BYOK. Start with what you have, extend only when you must.