From eb9d8cbc926c74e0affa494527350d925628fc76 Mon Sep 17 00:00:00 2001 From: Anton Gulin Date: Mon, 20 Apr 2026 09:53:29 -0700 Subject: [PATCH 1/5] docs: add AGENTS.md for AI agent development guidance Repository structure, build/test commands, code conventions, and common tasks for AI coding agents contributing to this codebase. --- AGENTS.md | 182 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..7c610d4 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,182 @@ +# AGENTS.md + +> For AI agents contributing to this repository. If you're using the AgenticFlow CLI, see [CONTEXT.md](CONTEXT.md) instead. + +## Repository Overview + +AgenticFlow CLI — a Node.js monorepo publishing two npm packages: +- **`@pixelml/agenticflow-cli`** (`af` / `agenticflow`) — Command-line interface for the AgenticFlow platform +- **`@pixelml/agenticflow-sdk`** — Typed HTTP client for the AgenticFlow API + +Language: TypeScript (strict mode, ESM-only, target ES2022) +License: Apache-2.0 +Node: >=18 + +## Repository Structure + +``` +agenticflow-cli/ +├── packages/ +│ ├── cli/ # @pixelml/agenticflow-cli (v1.10.4) +│ │ ├── src/ +│ │ │ ├── bin/ +│ │ │ │ └── agenticflow.ts # Entry point (#!/usr/bin/env node) +│ │ │ └── cli/ +│ │ │ ├── main.ts # Commander program — ALL command definitions (~7700 lines) +│ │ │ ├── client.ts # HTTP request builder helpers +│ │ │ ├── spec.ts # OpenAPI spec loader +│ │ │ ├── local-validation.ts # Pre-flight payload validation +│ │ │ ├── operation-ids.ts # Operation ID → CLI command mapping +│ │ │ ├── changelog.ts # Changelog rendering +│ │ │ ├── playbooks.ts # 14 playbook definitions +│ │ │ ├── company-blueprints.ts # 6 built-in workforce blueprints +│ │ │ ├── company-io.ts # YAML export/import/diff/merge +│ │ │ ├── blueprint-to-agent.ts # Blueprint → agent conversion +│ │ │ ├── blueprint-to-workflow.ts # Blueprint → workflow conversion +│ │ │ ├── blueprint-to-workforce.ts # Blueprint → workforce conversion +│ │ │ ├── pack.ts # Pack management +│ │ │ ├── pack-registry.ts # Pack registry +│ │ │ ├── platform-catalog.ts # Platform model catalog +│ │ │ ├── skill.ts # Skill definitions +│ │ │ ├── policy.ts # Policy definitions +│ │ │ ├── template-cache.ts # Template caching +│ │ │ ├── template-duplicate.ts # Template duplication +│ │ │ ├── data/ +│ │ │ │ ├── openapi.json # Embedded OpenAPI spec (~28K lines) +│ │ │ │ └── public_ops_manifest.json # Public ops manifest +│ │ │ ├── gateway/ +│ │ │ │ ├── server.ts # Gateway server (Express-like) +│ │ │ │ ├── connector.ts # ChannelConnector interface +│ │ │ │ └── connectors/ # linear.ts, webhook.ts, paperclip.ts +│ │ │ └── utils/ +│ │ │ ├── deprecation.ts # Deprecation warning helpers +│ │ │ ├── mcp-inspect.ts # MCP client classification +│ │ │ ├── models.ts # Model ID helpers +│ │ │ └── patch.ts # Partial update (merge) logic +│ │ └── tests/ # 19 vitest test files (mirror cli/ structure) +│ └── sdk/ # @pixelml/agenticflow-sdk (v1.6.0) +│ └── src/ +│ ├── index.ts # Public exports + createClient() factory +│ ├── core.ts # AgenticFlowSDK class — request/call/get/post/put/patch/delete/stream +│ ├── http.ts # DeterministicHTTPClient +│ ├── streaming.ts # Vercel AI SDK Data Stream v1 parser, AgentStream class +│ ├── exceptions.ts # Error hierarchy (AgenticFlowError → APIError → ValidationError, …) +│ ├── types.ts # APIResponse interface +│ └── resources/ +│ ├── index.ts # Barrel exports +│ ├── agents.ts # AgentsResource — CRUD, stream, run, patch, upload +│ ├── agent-threads.ts # AgentThreadsResource +│ ├── connections.ts # ConnectionsResource — CRUD, categories, health +│ ├── database.ts # DatabaseResource +│ ├── knowledge.ts # KnowledgeResource — CRUD, rows, search +│ ├── marketplace.ts # MarketplaceResource, templates +│ ├── mcp-clients.ts # McpClientsResource — list, get +│ ├── node-types.ts # NodeTypesResource — list, get, search, dynamic-options +│ ├── paperclip.ts # PaperclipResource — companies, agents, goals, issues +│ ├── triggers.ts # TriggersResource +│ ├── uploads.ts # UploadsResource +│ ├── workflows.ts # WorkflowsResource — CRUD, run, run-status +│ └── workforces.ts # WorkforcesResource + versions + publish sub-resources +├── .github/workflows/ +│ ├── ci.yaml # CI: Python tests + Node smoke test +│ └── release-node.yaml # Tag-triggered npm publish (cli-v* / sdk-v*) +├── docs/ # Design docs, planning, SOPs +├── scripts/ # Release readiness, minion orchestrator +├── CONTEXT.md # How to USE the AgenticFlow CLI (not this repo) +└── README.md # Human-facing docs +``` + +## Build & Test + +```bash +# Install dependencies +npm ci + +# Build SDK first (CLI depends on it), then CLI +npm run build + +# Run all tests +npm run test + +# Build/test individual packages +npm run build -w packages/sdk +npm run build -w packages/cli +npm run test -w packages/sdk +npm run test -w packages/cli + +# Clean build artifacts +npm run clean +``` + +Build order matters: **SDK must be built before CLI** since CLI imports from `@pixelml/agenticflow-sdk`. + +## Common Tasks + +### Add a new CLI command + +1. Add the Commander command definition in `packages/cli/src/cli/main.ts` +2. If the command needs helper logic, create a new module in `packages/cli/src/cli/` +3. Add the operation ID mapping in `packages/cli/src/cli/operation-ids.ts` if it wraps an API endpoint +4. Add tests in `packages/cli/tests/` — file naming mirrors `src/cli/` (e.g., `main.test.ts`, `client.test.ts`) +5. Build and test: `npm run build -w packages/cli && npm run test -w packages/cli` + +### Add a new SDK resource + +1. Create `packages/sdk/src/resources/.ts` — export a class extending the resource pattern +2. Add barrel export in `packages/sdk/src/resources/index.ts` +3. Register on the SDK class in `packages/sdk/src/core.ts` +4. Build and test: `npm run build -w packages/sdk && npm run test -w packages/sdk` + +### Add a new workforce blueprint + +1. Define the blueprint in `packages/cli/src/cli/company-blueprints.ts` +2. Add conversion logic in `packages/cli/src/cli/blueprint-to-workforce.ts` +3. Add tests + +## Code Conventions + +- **TypeScript strict mode** — `strict: true` in tsconfig +- **ESM-only** — `"type": "module"`, `NodeNext` module resolution +- **Commander.js** for CLI argument parsing +- **Vitest** for testing — test files in `tests/**/*.test.ts`, 10s timeout +- **Error format** — JSON with `schema: "agenticflow.error.v1"` discriminator, always include `hint` for recovery +- **Output format** — `--json` flag produces machine-readable output with `schema:` discriminators +- **Never print secrets** in logs or command output +- **No comments** in code unless explaining non-obvious behavior + +## Testing Patterns + +- Test files live in `packages/cli/tests/` and `packages/sdk/src/__tests__/` +- File naming: `.test.ts` mirrors the source module name +- Framework: Vitest (`vitest run` for non-watch mode) +- Tests are unit tests — no live API calls in CI + +## Release Process + +Releases are tag-triggered via GitHub Actions: + +| Tag pattern | Publishes | Workflow | +|---|---|---| +| `cli-v*` | `@pixelml/agenticflow-cli` | `.github/workflows/release-node.yaml` | +| `sdk-v*` | `@pixelml/agenticflow-sdk` | `.github/workflows/release-node.yaml` | + +Steps: tag push → build → test → version set → npm publish (with provenance) → GitHub Release (auto notes) + +## Key Files to Know + +| File | Purpose | +|---|---| +| `packages/cli/src/cli/main.ts` | All CLI command definitions (~7700 lines) | +| `packages/cli/src/cli/data/openapi.json` | Embedded OpenAPI spec — the source of truth for API operations | +| `packages/cli/src/cli/company-blueprints.ts` | 6 workforce blueprints (dev-shop, marketing-agency, etc.) | +| `packages/cli/src/cli/playbooks.ts` | 14 playbook definitions | +| `packages/sdk/src/core.ts` | SDK client class — all HTTP methods | +| `packages/sdk/src/resources/` | SDK resource classes (one per API domain) | +| `CONTEXT.md` | Guide for AI agents **using** the CLI (not developing it) | + +## Gotchas + +- **Build order**: SDK must be built before CLI. Root `npm run build` handles this. +- **`main.ts` is large** (~7700 lines) — it contains all Commander command registrations. When adding commands, add them in the same file following the existing pattern. +- **`af.sh`** at repo root runs the local build directly for dev convenience. +- **CONTRIBUTING.md** references a Python setup — the repo has legacy Python CI artifacts; the active codebase is TypeScript. \ No newline at end of file From f7f4861161f1f922476ad87834e0f409028ab3f5 Mon Sep 17 00:00:00 2001 From: Anton Gulin Date: Mon, 20 Apr 2026 10:12:29 -0700 Subject: [PATCH 2/5] docs: add sister repo section for agenticflow-skill Reference the skills repo (agenticflow-agent, agenticflow-workforce, agenticflow-mcp) and note the sync requirement when CLI commands change. --- AGENTS.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 7c610d4..96ae183 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -174,6 +174,20 @@ Steps: tag push → build → test → version set → npm publish (with provena | `packages/sdk/src/resources/` | SDK resource classes (one per API domain) | | `CONTEXT.md` | Guide for AI agents **using** the CLI (not developing it) | +## Sister Repository: AgenticFlow Skills + +The [`agenticflow-skill`](https://github.com/PixelML/agenticflow-skill) repo defines SKILL.md files that teach other AI tools (Claude Code, Cursor, Codex, Gemini CLI) how to *use* the `af` CLI. It lives in a separate repo and is maintained independently. + +Three skills auto-route based on user intent: + +| Skill | Purpose | +|---|---| +| `agenticflow-agent` | Single agent create/run/iterate (`af agent *`) | +| `agenticflow-workforce` | Multi-agent team deploy (`af workforce *`, blueprints) | +| `agenticflow-mcp` | MCP tool attach/inspect (`af mcp-clients *`) | + +**When making CLI changes** that add, rename, or change command behavior, check whether the skill repo's SKILL.md files reference the affected commands — they may need updating to stay in sync. + ## Gotchas - **Build order**: SDK must be built before CLI. Root `npm run build` handles this. From b151a512e68655289e794442718c8cb7063ad654 Mon Sep 17 00:00:00 2001 From: Anton Gulin Date: Mon, 20 Apr 2026 10:14:08 -0700 Subject: [PATCH 3/5] docs: add CLAUDE.md redirecting to AGENTS.md --- CLAUDE.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file From 8be94b433fb7891c01cb5d6d6b7d15de579a6499 Mon Sep 17 00:00:00 2001 From: Anton Gulin Date: Mon, 20 Apr 2026 12:13:13 -0700 Subject: [PATCH 4/5] docs: add skills/ with 3 SKILL.md files, deprecate agenticflow-skill repo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Skills live next to the commands they document so one PR updates both. The separate agenticflow-skill repo should be deprecated — it causes sync drift and AI agents won't proactively clone it. --- AGENTS.md | 27 +++-- skills/agenticflow-agent/SKILL.md | 136 ++++++++++++++++++++++++ skills/agenticflow-mcp/SKILL.md | 108 +++++++++++++++++++ skills/agenticflow-workforce/SKILL.md | 144 ++++++++++++++++++++++++++ 4 files changed, 406 insertions(+), 9 deletions(-) create mode 100644 skills/agenticflow-agent/SKILL.md create mode 100644 skills/agenticflow-mcp/SKILL.md create mode 100644 skills/agenticflow-workforce/SKILL.md diff --git a/AGENTS.md b/AGENTS.md index 96ae183..f4917f1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -77,6 +77,10 @@ agenticflow-cli/ │ ├── uploads.ts # UploadsResource │ ├── workflows.ts # WorkflowsResource — CRUD, run, run-status │ └── workforces.ts # WorkforcesResource + versions + publish sub-resources +├── skills/ # SKILL.md files for AI tools (agent, workforce, mcp) +│ ├── agenticflow-agent/SKILL.md # Single agent create/run/iterate +│ ├── agenticflow-workforce/SKILL.md # Multi-agent team deploy + blueprints +│ └── agenticflow-mcp/SKILL.md # MCP tool attach/inspect ├── .github/workflows/ │ ├── ci.yaml # CI: Python tests + Node smoke test │ └── release-node.yaml # Tag-triggered npm publish (cli-v* / sdk-v*) @@ -174,19 +178,24 @@ Steps: tag push → build → test → version set → npm publish (with provena | `packages/sdk/src/resources/` | SDK resource classes (one per API domain) | | `CONTEXT.md` | Guide for AI agents **using** the CLI (not developing it) | -## Sister Repository: AgenticFlow Skills +## Skills -The [`agenticflow-skill`](https://github.com/PixelML/agenticflow-skill) repo defines SKILL.md files that teach other AI tools (Claude Code, Cursor, Codex, Gemini CLI) how to *use* the `af` CLI. It lives in a separate repo and is maintained independently. +SKILL.md files teach other AI tools (Claude Code, Cursor, Codex, Gemini CLI) how to *use* the `af` CLI. They live in this repo under `skills/` — next to the commands they document — so a single PR can update both the command implementation and the skill. -Three skills auto-route based on user intent: +| Skill | Path | Purpose | +|---|---|---| +| `agenticflow-agent` | `skills/agenticflow-agent/SKILL.md` | Single agent create/run/iterate (`af agent *`) | +| `agenticflow-workforce` | `skills/agenticflow-workforce/SKILL.md` | Multi-agent team deploy (`af workforce *`, blueprints) | +| `agenticflow-mcp` | `skills/agenticflow-mcp/SKILL.md` | MCP tool attach/inspect (`af mcp-clients *`) | -| Skill | Purpose | -|---|---| -| `agenticflow-agent` | Single agent create/run/iterate (`af agent *`) | -| `agenticflow-workforce` | Multi-agent team deploy (`af workforce *`, blueprints) | -| `agenticflow-mcp` | MCP tool attach/inspect (`af mcp-clients *`) | +### Sister repo deprecation: agenticflow-skill + +The [`agenticflow-skill`](https://github.com/PixelML/agenticflow-skill) repo previously held these same skills in a separate repository. It should be deprecated in favor of the `skills/` directory here because: -**When making CLI changes** that add, rename, or change command behavior, check whether the skill repo's SKILL.md files reference the affected commands — they may need updating to stay in sync. +- **Skills describe CLI commands** — they must change when commands change. Keeping them in the same repo means one PR updates both, eliminating sync drift. +- **AI agents discover skills automatically** when they're local files. A separate repo requires agents to proactively clone it (they won't). +- **The separate repo adds maintenance overhead** with no upside — same content, two locations, constant risk of divergence. +- **Zero sync burden**: Commands and skills live together. A CLI PR that renames or changes a command updates the skill in the same commit. ## Gotchas diff --git a/skills/agenticflow-agent/SKILL.md b/skills/agenticflow-agent/SKILL.md new file mode 100644 index 0000000..a5f3668 --- /dev/null +++ b/skills/agenticflow-agent/SKILL.md @@ -0,0 +1,136 @@ +--- +name: agenticflow-agent +description: "Create, run, and iterate on a single AgenticFlow AI agent — one chat endpoint, one assistant, one persona. Use when the user wants a customer-facing bot, a support assistant, a single task agent, or a prompt experiment. Choose this skill over agenticflow-workforce when there's no orchestration between roles (no handoff, no coordinator → workers). Covers `af agent create/update/run/delete`, the `--patch` partial-update pattern for iteration, `af schema agent --field ` for nested payload shapes (including suggested_messages, mcp_clients, response_format), the `model_user_config` / `code_execution_tool_config` settings, and safe iteration loops." +compatibility: Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI +metadata: + author: PixelML + version: "3.0.0" + license: MIT +triggers: + - "create an agent" + - "build an agent" + - "agent configuration" + - "system prompt" + - "support bot" + - "customer-facing bot" + - "single agent" + - "agent persona" + - "agent update" + - "patch agent" + - "iterate on agent" + - "agent run" + - "agent delete" +--- + +# AgenticFlow Agent + +A single AI agent with a system prompt, model, optional MCP tool attachments, and an optional code-execution sandbox. Use this when one chat surface + one set of rules is enough. + +## When NOT to use this skill + +If the user needs **multiple agents that hand off to each other** (research → write, triage → specialist, a pre-built team template), use `agenticflow-workforce` instead. Don't over-engineer — a support bot with "if billing/refunds/privacy, escalate to email" is one agent, not three. + +## Orient first + +```bash +af bootstrap --json +``` + +From the response, extract: + +- `auth.project_id` — **required** on agent create (server does not auto-inject for agents, unlike workforces) +- `auth.workspace_id` +- `_links.workspace` — **surface this URL to the user right away**: *"Your AgenticFlow workspace is at `<_links.workspace>` — open it anytime to see what I'm building."* Anchors a human-first mental model before any mutation +- `models[]` — use as source of truth for model ids (don't hardcode — they change between CLI releases) +- `agents[]` — so you don't duplicate existing work + +If `data_fresh: false` in the response, the backend is degraded — don't mutate. Run `af doctor --json --strict` and fix auth/network first. + +## Inspect payload shape before writing + +```bash +af schema agent --json +af schema agent --field mcp_clients --json # Nested attach shape +af schema agent --field suggested_messages --json # {title, label, action} — NOT strings +af schema agent --field response_format --json # Structured output config +af schema agent --field update --json # Update + null-rejected fields list +``` + +The `--field` drilldown returns the documented shape for a single field. Use it instead of guessing. + +## Create (always preview first) + +```bash +af agent create --body @agent.json --dry-run --json +af agent create --body @agent.json --json +``` + +Minimum valid payload: + +```json +{ + "name": "My Support Assistant", + "tools": [], + "project_id": "", + "model": "agenticflow/gemini-2.0-flash", + "system_prompt": "You are ..." +} +``` + +**Available models** live in `af bootstrap --json > models[]` — always read from there rather than hardcoding a list in your logic (models ship between CLI releases). The CLI validates your model string at create time: typos fail fast with an actionable hint listing the known set. If you pass a `vendor/model-name`-shaped string not in the known list, it warns-but-proceeds so brand-new models work before the CLI is updated. + +## Run (smoke test) + +```bash +af agent run --agent-id --message "Test prompt" --json +# Returns {response, thread_id, status}. + +af agent run --agent-id --thread-id --message "continue" --json +# Pass the same thread_id to keep conversation context; omit it to start fresh. +``` + +Use `af agent stream` for SSE token-level streaming if you need it; `run` is better for scripted tests. + +## Iterate with --patch (the cornerstone pattern) + +Never round-trip the full agent body to change one field: + +```bash +# WRONG — full-body replace loses attached MCPs / tools / code_exec config if omitted +af agent update --agent-id --body @updated.json + +# RIGHT — partial update, everything else preserved +af agent update --agent-id --patch --body '{"system_prompt":"new prompt"}' --json +af agent update --agent-id --patch --body '{"model":"agenticflow/gpt-4o-mini"}' --json +af agent update --agent-id --patch --body '{"mcp_clients":[{"mcp_client_id":"","run_behavior":"auto_run","tools":{}}]}' --json +``` + +The CLI auto-strips null-rejected fields (`knowledge`, `recursion_limit`, `task_management_config`, `suggest_replies_*`, `file_system_tool_config`, `attachment_config`, `response_format`, `skills_config`). Stripped fields are logged to stderr so bots don't think they cleared a field they didn't. + +## Attach an MCP tool provider + +See the `agenticflow-mcp` skill for the full inspect-before-attach flow. Short version: + +```bash +af mcp-clients list --name-contains "google sheets" --fields id,name --json +af mcp-clients inspect --id --json +# Only proceed if pattern != "pipedream" with write_capable_tools +af agent update --agent-id --patch --body '{"mcp_clients":[{...}]}' --json +``` + +## Cleanup + +```bash +af agent delete --agent-id --json +# Returns {"schema":"agenticflow.delete.v1","deleted":true,"id":"...","resource":"agent"} +``` + +## On errors + +Every API error returns a consistent envelope with an actionable `hint`. Common 4xx and their hints: + +- **404** → "Run the matching `list` command to see available IDs" (or double-check the ID) +- **422** → "Check `details.payload` for field-level errors" (pydantic returns the offending field) +- **401** → "Run `af whoami` / `af login`" + +When `hint` is non-empty, follow it before retrying. \ No newline at end of file diff --git a/skills/agenticflow-mcp/SKILL.md b/skills/agenticflow-mcp/SKILL.md new file mode 100644 index 0000000..f90eba8 --- /dev/null +++ b/skills/agenticflow-mcp/SKILL.md @@ -0,0 +1,108 @@ +--- +name: agenticflow-mcp +description: "Attach external tool providers (Google Docs, Google Sheets, Slack, Notion, GitHub, Apify, etc.) to an AgenticFlow agent via MCP clients. Use when the user wants their agent to read or write external data, call third-party APIs, save outputs to a doc/sheet, or use any tool beyond the model's built-in knowledge. Covers `af mcp-clients list --name-contains`, `af mcp-clients inspect --id` (classify pattern before attach), and the Pipedream vs Composio write-capability distinction — critical for parametric writes. Route traffic through the `af` CLI; the standalone `agenticflow-mcp` server repo lags the CLI and is not recommended." +compatibility: Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI +metadata: + author: PixelML + version: "3.0.0" + license: MIT +triggers: + - "mcp" + - "mcp client" + - "attach tools" + - "give my agent tools" + - "google docs" + - "google sheets" + - "notion" + - "slack" + - "github" + - "apify" + - "external tool" + - "tool integration" + - "pipedream" + - "composio" +--- + +# AgenticFlow MCP + +> **Do NOT install the legacy `agenticflow-mcp` standalone server repo.** It is stale (last release lags the current platform by many versions) and is **not the recommended integration path**. Everything below uses the `af` CLI (install via `npm install -g @pixelml/agenticflow-cli`), which covers MCP operations comprehensively and stays in lockstep with platform changes. + +MCP (Model Context Protocol) clients are the tool-provider layer that lets an agent read or write external systems — Google Docs, Google Sheets, Slack, Notion, GitHub, Apify, Gmail, Pinterest, YouTube, and many more. A workspace usually has many MCP clients already configured; your job is to **pick the right one and verify it's safe before attaching** to an agent. + +## Orient first + +Before touching MCP clients, run: + +```bash +af bootstrap --json +``` + +Extract `auth.workspace_id` + `_links.mcp` (the web UI URL for MCP management). **Surface `_links.mcp` to the user**: *"Your MCP connections live at `<_links.mcp>` — you can add or re-authenticate providers there if any inspections fail."* If `data_fresh: false`, the backend is degraded — don't mutate. + +## The one pattern that matters: inspect before attach + +Not all MCP clients are equal. There are two major families, and one of them breaks on writes. + +```bash +af mcp-clients list --name-contains "google sheets" --fields id,name,is_authenticated --json +af mcp-clients inspect --id --json +``` + +`inspect` classifies the tool set and returns a `pattern` field: + +| pattern | Meaning | Safe to attach? | +| --- | --- | --- | +| `composio` | Structured schemas with multiple named fields (e.g. `spreadsheetId`, `range`, `values`) | Yes — writes work reliably | +| `pipedream` | Every tool has a single `{instruction: string}` input | Read-only tools fine. Parametric writes (`add-row`, `update-cell`, `append`) may get stuck in a `configure_props__props` loop — the tool configures but never executes | +| `mixed` | Some structured, some instruction-only | Restrict allowlist to the structured (Composio-style) tools only | +| `unknown` | Tool list couldn't be enumerated | **Do not attach.** Check `classification_reason` + `fetch_error` in the response. Re-auth via the web UI if needed | + +`inspect` also returns `known_quirks[]` — read it. If it contains a warning about `configure_props__props`, you've been warned; do not attach that client for writes. + +## Attach shape (use `--patch`, not full-body update) + +```bash +af agent update --agent-id --patch --body '{ + "mcp_clients": [ + { + "mcp_client_id": "", + "run_behavior": "auto_run", + "description": "Google Sheets for logging outputs", + "timeout": 150, + "tools": { + "GOOGLESHEETS_SPREADSHEETS_VALUES_APPEND": {"allowed": true}, + "GOOGLESHEETS_VALUES_UPDATE": {"allowed": true}, + "GOOGLESHEETS_DELETE_SHEET": {"allowed": false} + } + } + ] +}' --json +``` + +`tools` is a per-tool allow/block map. Block destructive ops (`DELETE_*`, `CLEAR_*`) unless the use case explicitly needs them. The CLI's `--patch` merges this over the current agent — existing MCP clients and other config are preserved. + +## Verify auth state (list vs. get can disagree) + +`af mcp-clients list` returns a cached `is_authenticated` that can be stale. If something is off, reconcile: + +```bash +af mcp-clients list --verify-auth --json +# For each row, also calls `get` and adds verified_is_authenticated + verified_auth_mismatch. +# N+1 call — use when debugging, not on every run. +``` + +If `classification_reason` in `inspect` is `fetch_failed` or `unauthenticated`, re-auth the client in the web UI at `/workspaces//mcp/` before attaching. + +## Smoke test after attach + +```bash +af agent run --agent-id --message "Try writing 'hello' to row 1" --json +# Expect status: "completed" + a response that actually shows the write happened. +# If the model claims success without a real write, you're probably on a broken MCP — re-inspect. +``` + +## On failures + +- `pattern: "pipedream"` + write attempt → `TOOL_CONFIGURATION_COMPLETED` or `configure_props__props` in the response. Switch to a Composio-backed client (many workspaces have both). +- `mcp-clients inspect` returns `classification_reason: "fetch_failed"` → the MCP provider's backend is down or the OAuth session expired. Open the web UI, re-auth, retry. +- Silent success (model says "done" but no actual write) → 99% of the time it's a Pipedream write quirk. Re-inspect, switch provider. \ No newline at end of file diff --git a/skills/agenticflow-workforce/SKILL.md b/skills/agenticflow-workforce/SKILL.md new file mode 100644 index 0000000..83fba50 --- /dev/null +++ b/skills/agenticflow-workforce/SKILL.md @@ -0,0 +1,144 @@ +--- +name: agenticflow-workforce +description: "Deploy and operate a multi-agent AgenticFlow workforce — a DAG of agents that hand off to each other (trigger → coordinator → worker agents → output). Use when the user asks for a team, pipeline, or multi-agent system: research-then-write, triage-then-specialist, dev shop, marketing agency, sales team, content studio, support center, Amazon seller team. Choose this skill over agenticflow-agent when the ask mentions 'team', 'workforce', 'pipeline', 'multiple agents', 'delegation', 'handoff', or names a built-in blueprint. Provides the `af workforce *` command surface, blueprint decisions, graph wiring, MCP attach recipes, and public URL publishing." +compatibility: Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI +metadata: + author: PixelML + version: "3.0.0" + license: MIT +triggers: + - "workforce" + - "multi-agent" + - "agent team" + - "deploy a team" + - "agent pipeline" + - "research-then-write" + - "triage-then-specialist" + - "dev shop" + - "marketing agency" + - "sales team" + - "content studio" + - "support center" + - "amazon seller" + - "blueprint" +--- + +# AgenticFlow Workforce + +A workforce is an AgenticFlow-native **DAG of agents** — typically `trigger → coordinator agent → worker agents → output` — that hand off structured results to each other. Use this when orchestration between roles matters. + +## When NOT to use this skill + +If the user wants a **single chat endpoint, a customer-facing bot, one assistant, or routing-by-prompt inside one agent**, use `agenticflow-agent` instead. A single-agent solution with rules in the system prompt is simpler, cheaper, and easier to iterate on. Workforces are for genuine multi-role orchestration. + +## Orient first + +```bash +af bootstrap --json +``` + +Returns `auth`, `agents`, `workforces`, `blueprints`, `commands`, `playbooks`, `whats_new`, `_links`. Extract: + +- `auth.project_id` — required for agent creation (the agents inside your workforce) +- `auth.workspace_id` +- `_links.workspace` — **surface this URL to the user right away**: *"Your workspace is at `<_links.workspace>` — open it anytime to see the workforce I'm building."* The user needs a human-first anchor before the first mutation +- `blueprints[]` — the built-in team templates, each with required/optional slot counts +- `workforces[]` — any existing workforces in the workspace (empty initially is normal; check `data_fresh` if false — that means the backend was unreachable, not the workspace empty) + +If `data_fresh: false` in the bootstrap response, the backend is degraded — **do not mutate**. Run `af doctor --json --strict` and fix auth/network before proceeding. + +## The built-in blueprints + +| Blueprint | Required slots | Optional | +| --- | --- | --- | +| `dev-shop` | ceo, engineer | designer, qa | +| `marketing-agency` | ceo, cmo, designer | researcher | +| `sales-team` | ceo, researcher, general | — | +| `content-studio` | ceo, cmo, engineer | designer | +| `support-center` | ceo, general | researcher | +| `amazon-seller` | ceo, cmo, engineer, researcher | general | +| `tutor` | ceo, cmo, engineer, researcher | general | +| `freelancer` | ceo, cmo, engineer, researcher | general | + +## One-command deploy (v1.6+) + +Always preview with `--dry-run` first: + +```bash +af workforce init --blueprint --name "" --dry-run --json +af workforce init --blueprint --name "" --json +``` + +`init` creates the workforce + one real agent per required slot + the wired graph — in a single atomic call. On failure, every resource is rolled back automatically; inspect `details.rolled_back_agents` and `details.rolled_back_workforce` in the error. + +Use `--include-optional-slots` to fill every slot, not just required ones. Use `--model ` (e.g. `agenticflow/gemini-2.0-flash`) to override the default model for all auto-created agents. + +## Custom workforce (no blueprint fits) + +If the user's ask is a precise custom pipeline that no blueprint matches (e.g. a 2-step researcher → writer flow that doesn't fit the 3–5-agent blueprints), skip blueprints: + +1. Inspect the expected graph shape: + ```bash + af schema workforce --field schema --json + ``` +2. Create metadata only: + ```bash + af workforce create --body '{"name":"Raul Content Pipeline","description":"..."}' --json + ``` +3. Create each agent separately via `af agent create` (see `agenticflow-agent` skill). +4. Build a graph JSON with `trigger → researcher (agent node, agent_id from step 3) → writer (agent node) → output`. +5. Deploy the graph atomically: + ```bash + af workforce deploy --workforce-id --body @graph.json --json + ``` +6. Validate: + ```bash + af workforce validate --workforce-id --json + ``` + +Edge `connection_type` is one of `next_step`, `condition`, `ai_condition`. Agent nodes **require** a real `agent_id` in `input`. + +## Run + publish + +```bash +af workforce run --workforce-id --trigger-data '{"message":"..."}' +# Streams SSE events — each line is one JSON event. The CLI auto-wraps your +# payload in {trigger_data: ...} — don't wrap it yourself. + +af workforce publish --workforce-id --json +# Mints a public_key + public_url — hand this to teammates so they can run the +# workforce without platform auth. + +af workforce versions publish --workforce-id --version-id --json +# Snapshot + publish a specific version (draft/published/restore workflow). +``` + +## Attach MCP tools per agent (not per workforce) + +MCP clients attach to individual agents, not to the workforce graph. After `init`, use: + +```bash +af mcp-clients list --name-contains "google sheets" --fields id,name --json +af mcp-clients inspect --id --json # Check pattern before attach +af agent update --agent-id --patch --body '{"mcp_clients":[{"mcp_client_id":"","run_behavior":"auto_run","tools":{}}]}' --json +``` + +See the `agenticflow-mcp` skill for the Pipedream vs Composio write-safety distinction. + +## Cleanup + +Workforces + agents are billed while they exist. Delete test deploys: + +```bash +af workforce delete --workforce-id --json +# For each auto-created agent id captured from init: +af agent delete --agent-id --json +``` + +Both return `{"schema":"agenticflow.delete.v1","deleted":true,"id":"...","resource":"..."}` on success. + +## On errors + +All API errors return `{schema: "agenticflow.error.v1", code, message, hint, details}`. Read `hint` first — it points at the recovery command (e.g. `af list` on a 404). For 422s, inspect `details.payload.detail` for field-level errors. + +`workforce run` occasionally returns a backend `Failed to retrieve user info for user_id: api_key:...` 400 — this is a known server-side issue with API-key auth, not a CLI bug. \ No newline at end of file From 25eda07f5e187b385abc1acc834c74fd99d70db6 Mon Sep 17 00:00:00 2001 From: Anton Gulin Date: Mon, 20 Apr 2026 16:48:23 -0700 Subject: [PATCH 5/5] feat(skills): add agenticflow-built-in-credits and agenticflow-llm-models skills --- skills/agenticflow-built-in-credits/SKILL.md | 395 +++++++++++++++++++ skills/agenticflow-llm-models/SKILL.md | 138 +++++++ 2 files changed, 533 insertions(+) create mode 100644 skills/agenticflow-built-in-credits/SKILL.md create mode 100644 skills/agenticflow-llm-models/SKILL.md diff --git a/skills/agenticflow-built-in-credits/SKILL.md b/skills/agenticflow-built-in-credits/SKILL.md new file mode 100644 index 0000000..4129873 --- /dev/null +++ b/skills/agenticflow-built-in-credits/SKILL.md @@ -0,0 +1,395 @@ +--- +name: agenticflow-built-in-credits +description: "Use AgenticFlow's built-in features and account credits first — before adding external API keys (BYOK). Use this skill whenever the user asks about image generation without API keys, wants to use their existing credits, asks about built-in vs BYOK, or mentions agenticflow_generate_image, web_search, web_retrieval, or credit-efficient workflows. BYOK is only for extension when unsatisfied or explicitly requested." +compatibility: Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI +metadata: + author: Anton Gulin (https://github.com/antongulin) + version: "1.0.0" + license: MIT +--- + +# 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 + +```bash +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. + +--- + +## 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 ` (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` + +> 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) + +```bash +# 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 +``` + +### 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. + +```bash +# 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:** +```bash +af agent init --blueprint content-creator --dry-run --json +af agent init --blueprint content-creator --json +``` + +### Rung 6: Workforce Blueprints (Credits-First) + +```bash +# DEFAULT: Multi-agent using YOUR credits only +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 # web_search +``` + +--- + +## Extension Path: When to Consider BYOK + +### Scenario 1: User Explicitly Requests + +**User says:** *"I want this specific image from DALL-E 3"* + +**Action:** +```bash +# 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:** +```bash +# 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:** +```bash +# 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** +```bash +# 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** +```bash +# Use agenticflow_generate_image for actual output +af agent run --agent-id --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)** +```bash +# 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 + +```bash +# Check workflow nodes (should be agenticflow_* or built-ins) +af workflow get --workflow-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 + +```bash +# ALWAYS inspect before deploying +af schema agent --field mcp_clients --json +af agent init --blueprint --dry-run --json +``` + +--- + +## Smoke Test After Deploy + +```bash +# Verify built-in features work with your credits +af agent run --agent-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: + +```bash +af agent delete --agent-id --json +af workforce delete --workforce-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:** 1.0.0 +**Philosophy:** Credits-First, Extend Only When Needed +**Author:** Anton Gulin (https://github.com/antongulin) +**License:** MIT + +--- + +**Remember:** The built-in features are powerful. Many users never need BYOK. Start with what you have, extend only when you must. diff --git a/skills/agenticflow-llm-models/SKILL.md b/skills/agenticflow-llm-models/SKILL.md new file mode 100644 index 0000000..cfa8d3d --- /dev/null +++ b/skills/agenticflow-llm-models/SKILL.md @@ -0,0 +1,138 @@ +--- +name: agenticflow-llm-models +description: "Select and configure LLM models for AgenticFlow agents and workforces. Use this skill whenever the user asks which model to use, needs reasoning capabilities, wants fast/cheaper options, gets finish_reason=length errors, or asks about model speed/quality/intelligence trade-offs. Covers the top 5 recommended models, models to avoid, reasoning configuration, and max_tokens settings." +compatibility: Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI +metadata: + author: Anton Gulin (https://github.com/antongulin) + version: "1.0.0" + license: MIT +--- + +# AgenticFlow LLM Models + +Choose the right model for your agent based on capability needs, speed requirements, and reasoning depth. Use built-in credits for all models listed here. + +## When NOT to use this skill + +Use `agenticflow-built-in-credits` skill instead for pricing, credits, or billing questions. Use `agenticflow-mcp` skill if they need external API keys (BYOK). This skill covers model selection and capabilities, not account management or credit usage. + +## Orient first + +```bash +af bootstrap --json +``` + +Extract `models[]` — this is the source of truth for available models. Never hardcode model lists; they change between CLI releases. + +## Top 5 recommended models + +Based on speed, reasoning quality, and reliability: + +| Model | Speed | Reasoning | Best for | +|-------|-------|-----------|----------| +| `agenticflow/glm-4.7-flash` | 18s | 931 tokens | Default choice — reasoning, tools, best all-rounder | +| `agenticflow/gemini-2.5-flash-lite` | 13s | Hidden by default | Fastest, media support, good fallback | +| `agenticflow/gpt-5-nano` | 19s | 1,792 tokens | Reasoning + vision, needs max_tokens ≥ 4000 | +| `agenticflow/qwen-3.5-flash` | 33s | 5,016 tokens | Deep verification, deepest thinker | +| `agenticflow/deepseek-v3.2-speciale` | 51s | 1,308 tokens | Heavyweight reasoning, high intelligence | + +## Fast non-reasoning models + +For simple tasks where speed matters most: + +| Model | Speed | Best for | +|-------|-------|----------| +| `agenticflow/gpt-4o-mini` | 6s | Simple agents, high-volume | +| `agenticflow/gemma-4-31b-it` | 7s | General purpose, correct | +| `agenticflow/gemma-4-26b-a4b-it` | 8s | General purpose, correct | + +## Model selection guide + +**Need a default?** +```bash +# Start with GLM-4.7 Flash — best all-rounder with reasoning +af agent create --body '{"name":"My Agent","model":"agenticflow/glm-4.7-flash","project_id":""}' --json + +# If you need maximum speed and don't need reasoning, use Gemini 2.5 Flash Lite +af agent create --body '{"name":"My Agent","model":"agenticflow/gemini-2.5-flash-lite","project_id":""}' --json +``` + +**Need reasoning?** +- Default reasoning: `glm-4.7-flash` (18s, 931 tokens) — already the default above +- Vision + reasoning: `gpt-5-nano` (19s) +- Deep verification: `qwen-3.5-flash` (33s, 5K reasoning tokens) +- Maximum reasoning: `deepseek-v3.2-speciale` (51s) + +**Need speed only?** +- Fastest correct: `gpt-4o-mini` (6s) +- Fast + large context: `gemma-4-31b-it` (7s) + +## Workforce model selection + +All agents in a workforce inherit the model: +```bash +af workforce init --blueprint dev-shop --model agenticflow/glm-4.7-flash --name "My Team" --json +``` + +## Reasoning configuration + +Expose reasoning tokens (where supported): +```bash +af schema agent --field model_user_config --json +``` + +Check the full agent schema (for all fields): +```bash +af schema agent --json +``` + +For Gemini 2.5 Flash Lite, reasoning is hidden by default. Configure via `thinking_config` to expose. + +## Verify model availability + +```bash +# Always dry-run first +af agent create --body @agent.json --dry-run --json +``` + +The CLI validates the model string at create time. Typos fail fast with an actionable hint listing known models. + +## Avoid these models + +Based on benchmark testing (April 2026): + +| Model | Issue | +|-------|-------| +| `agenticflow/claude-3-5-haiku` | Fast (4s) but wrong on reasoning tasks. Use for writing only, never logic. | +| `agenticflow/gemini-2.0-flash` | Deprecated, replaced by 2.5 Flash Lite | +| `agenticflow/gemini-2.0-flash-lite` | Deprecated, replaced by 2.5 Flash Lite | +| `agenticflow/google-gemini-1.5-flash` | Legacy, may be deprecated | +| `agenticflow/gpt-oss-120b` | Intermittent failures (Groq backend issues) | +| `agenticflow/gpt-oss-20b` | Intermittent failures | + +## Fallback reasoning models + +If top 5 unavailable: + +| Model | Speed | Notes | +|-------|-------|-------| +| `agenticflow/qwen-3.5-9b` | 41s | Flaky (finish_reason=error despite correct reasoning) | +| `agenticflow/glm-4.5-air` | 48s | Needs max_tokens ≥ 4000 or truncates | +| `agenticflow/deepseek-v3.2` | 55s | Works but slower than Speciale | +| `agenticflow/deepseek-v3.2-exp` | 29s | Correct without exposing reasoning tokens | + +## Cleanup + +Test agents consume credits. Delete when done: +```bash +af agent delete --agent-id --json +``` + +## On errors + +- **400 / Invalid model** → Check `models[]` from bootstrap; model may have been renamed +- **402 / Payment Required** → Model requires credits; see `agenticflow-built-in-credits` skill +- **422 / Model not available** → Model temporarily unavailable; the `hint` suggests alternatives +- **finish_reason=length** → Increase `max_tokens` (especially for GPT-5 Nano and GLM-4.5 Air) + +When `hint` is non-empty, follow it before retrying.