agenticflow-agent

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

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

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)

af agent create --body @agent.json --dry-run --json
af agent create --body @agent.json --json

Minimum valid payload:

{
  "name": "My Support Assistant",
  "tools": [],
  "project_id": "<from bootstrap auth.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)

af agent run --agent-id <id> --message "Test prompt" --json
# Returns {response, thread_id, status}.

af agent run --agent-id <id> --thread-id <tid> --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:

# WRONG — full-body replace loses attached MCPs / tools / code_exec config if omitted
af agent update --agent-id <id> --body @updated.json

# RIGHT — partial update, everything else preserved
af agent update --agent-id <id> --patch --body '{"system_prompt":"new prompt"}' --json
af agent update --agent-id <id> --patch --body '{"model":"agenticflow/gpt-4o-mini"}' --json
af agent update --agent-id <id> --patch --body '{"mcp_clients":[{"mcp_client_id":"<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:

af mcp-clients list --name-contains "google sheets" --fields id,name --json
af mcp-clients inspect --id <mcp_id> --json
# Only proceed if pattern != "pipedream" with write_capable_tools
af agent update --agent-id <agent_id> --patch --body '{"mcp_clients":[{...}]}' --json

Cleanup

af agent delete --agent-id <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.

Reference

• cli-setup.md — install + auth
• troubleshooting.md
• glossary.md