# Documentation Hub

Welcome to the AgenticFlow documentation! This guide will help you master the most powerful no-code AI automation platform.

## Start here

**New to AgenticFlow?** Start with [**Your First 5 Minutes**](/get-started/your-first-5-minutes) for a short product walkthrough, then use [**Choose Your Path**](/get-started/choose-your-path) to find the right guide for your role.

<figure><img src="/files/iNRHCh1PnxC8LnUejyU3" alt=""><figcaption></figcaption></figure>

## Quick Navigation

### Getting Started (5-15 Minutes)

* [Your First 5 Minutes](/get-started/your-first-5-minutes) - Quick wins to get started
* [Choose Your Path](/get-started/choose-your-path) - Role-based guidance
* [Agents Quickstart](/get-started/agents-quickstart)
* [Workflows Quickstart](/get-started/workflows-quickstart)
* [Workforce Quickstart](/workforce/quickstart-15-min)

### Core Features

* [AI Agents](/ai-agents/03-agents) - Interactive AI assistants with visual configuration
* [Workflows](/workflows/04-workflows) - Drag-and-drop automation builder
* [Workforce](/workforce/05-workforce) - Multi-agent team orchestration (FLAGSHIP)

### Learn & Grow

* [Learning Hub](/learn/02-learn) - Quickstarts, tutorials, and learning paths

### Integrations & Development

* [300+ Integrations](/integrations/07-integrations) - No-code tool connections (MCPs)
* [API & Developer Docs](/developers/api) - Technical documentation

### Enterprise & Support

* [Security Overview](/policies/security-overview) - Security and data-handling overview
* [Support & Troubleshooting](/support/12-support) - Help when you need it

## Documentation Structure

This documentation is organized into 12 product sections plus Policies:

1. **Quickstart** - Fast wins and getting started guides (5-15 minutes)
2. **Learn** - Progressive learning paths, courses, and video tutorials
3. **Agents** - AI agent system documentation
4. **Workflows** - Traditional sequential automation workflows
5. **Workforce** - Multi-agent team orchestration (flagship feature)
6. **Data & Knowledge** - Knowledge bases and data management
7. **Integrations** - 300+ MCP integrations and custom connections
8. **Security** - Security and data-handling overview
9. **Developers** - API reference, SDKs, and technical documentation
10. **Use Cases** - Industry examples and ready-to-use templates
11. **Reference** - Complete node reference and technical specifications
12. **Support** - Troubleshooting, FAQs, and community resources
13. **Policies** - Terms, privacy, cookies, and security policies

## How to Use These Docs

### For Beginners

Start here: [Your First 5 Minutes](/get-started/your-first-5-minutes) → [Choose Your Path](/get-started/choose-your-path) → Complete relevant quickstart

### For Business Users

1. [Choose Your Path](/get-started/choose-your-path)
2. Pick your focus: [Agents](/ai-agents/03-agents), [Workflows](/workflows/04-workflows), or [Workforce](/workforce/05-workforce)
3. Explore [Use Cases](/use-cases/10-use-cases) for your industry

### For Developers

1. [API Reference](/developers/api)
2. [Node Reference](/reference/nodes)
3. [Developer Documentation](/developers/api)

### For Enterprise Teams

1. [Security Overview](/policies/security-overview)
2. [Contact Support](/support/contact-support)

## Need Help?

* **Troubleshooting**: Visit [Troubleshooting Guide](/support/troubleshooting)
* **Community**: Join our [Community](/support/community)
* **Support**: [Contact Support](/support/contact-support)

## What's AgenticFlow?

AgenticFlow is a no-code AI automation platform that enables you to:

* **Build AI Agents**: Create interactive AI assistants with an 11-tab visual configuration system
* **Automate Workflows**: Design drag-and-drop automation with 193+ nodes
* **Orchestrate Teams**: Deploy multi-agent teams with the visual Workforce builder
* **Connect Everything**: Access 300+ no-code integrations (MCPs)
* **Scale Securely**: Enterprise features with multi-tenant workspaces and RBAC

### Platform Highlights

* Visual no-code builders for all features
* Multi-modal AI capabilities (text, image, audio, video)
* Credit-based billing system
* Security controls and policy documentation
* Comprehensive API and SDK support

***

**Ready to get started?** [Begin with Your First 5 Minutes →](/get-started/your-first-5-minutes)


# Platform Overview

No-code AI automation platform for building agents and workflows

**Build intelligent AI agents and workflows for business operations - no programming required.**

[AgenticFlow](https://agenticflow.ai/) is a no-code platform for AI automation. Whether you're a business professional, entrepreneur, or enterprise team, you can create AI agents and workflows using a visual interface.

## 🧭 **Navigation Help**

📍 **New to AgenticFlow?** See our [Navigation Guide](/welcome-to-agenticflow/navigation-guide) to find exactly what you need based on your goals and role.

**Quick Paths:**

* 🚀 **Just starting?** → [Your First 5 Minutes](/get-started/your-first-5-minutes)
* 🎓 **Want structured learning?** → [Learning Hub](/learn/02-learn)
* 💼 **Business user?** → [Choose Your Path](/get-started/choose-your-path)
* 🏢 **Enterprise?** → [Enterprise Features](https://github.com/PixelML/agenticflow-docs/blob/main/docs/08-enterprise/README.md)

## 🎬 **Platform Overview**

{% embed url="<https://www.youtube.com/watch?v=z2KetjMOAXY>" %}
What is AgenticFlow AI? (2:52) - Complete platform overview: no-code AI automation that empowers your business with a fully customizable platform for building dedicated AI agent teams to automate marketing and creative tasks around the clock.
{% endembed %}

## 🗺️ **Choose Your Journey**

{% embed url="<https://www.loom.com/share/562686e3d82a4fdab6c8ea623c2f2010>" %}
AgenticFlow - Build AI agents to launch, market, and scale your business.
{% endembed %}

## 🌟 **Two Powerful Ways to Automate with AI**

### 🤖 **AI Agents: Interactive Intelligence**

Build specialized AI assistants that think, learn, and act independently:

* **11-Tab Configuration System**: Visual interface for complete agent customization
* **Multi-Modal Capabilities**: Handle text, images, documents, audio, and video
* **300+ Tool Integrations**: Connect to your existing business systems
* **Intelligent Conversations**: Context-aware responses that get smarter over time

### ⚡ **Visual Workflows: Drag-and-Drop Automation**

Create powerful automations using our visual workflow builder:

* **193+ Pre-Built Nodes**: AI models, integrations, logic controls, and data processors
* **No-Code Interface**: Drag, drop, and connect components visually
* **Real-Time Execution**: Watch your automations work with live data flow
* **Enterprise Scaling**: Handle thousands of operations simultaneously

<figure><img src="/files/T0AYtqkGMfMHcgYt0JBi" alt=""><figcaption><p>Visual workflow builder with drag-and-drop automation nodes</p></figcaption></figure>

## 🏢 **Workforce: The Future of AI Automation**

{% embed url="<https://www.youtube.com/watch?v=1kaojsg8f2s>" %}
Understanding Multi Agent Systems (2:01) - Core concepts: Learn how AI agents collaborate and coordinate to handle complex business processes as specialized teams.
{% endembed %}

### **Multi-Agent Orchestration**

Our flagship **Workforce** feature creates teams of AI agents that collaborate:

* **Specialized AI Teams**: Each agent excels in specific roles and responsibilities
* **Intelligent Coordination**: Agents automatically determine who handles each task
* **Real-Time Collaboration**: Watch your AI team work together to solve complex problems
* **Visual Team Builder**: Design your AI workforce using our intuitive interface

### **Real-World Applications**

**Customer Service Workforce**

* Intake Agent → Routes to Technical Support → Escalates to Account Management
* Self-service support experiences with configurable escalation paths

**Sales & Marketing Team**

* Lead Qualification → Research Specialist → Sales Development → Demo Specialist
* Automated pipeline that converts prospects to customers

**Content Creation Squad**

* Content Strategist → Writers → Designers → Quality Assurance → Publishers
* End-to-end content production with consistent brand voice

## 🎯 **Why Choose No-Code AI Automation?**

### **Speed to Value**

* **Launch in Minutes**: Deploy AI solutions without months of development
* **No Technical Barriers**: Business users can build sophisticated automations
* **Immediate ROI**: Start seeing results from day one

### **Platform Capabilities**

* **Scalable Architecture**: Handle millions of operations across your organization
* **Security & Compliance**: Enterprise security features and compliance tools
* **Integration Ready**: Connect to 300+ business tools and custom systems

### **Visual Simplicity**

* **Drag-and-Drop Interface**: Build complex workflows visually
* **Real-Time Debugging**: See exactly how your automations work
* **Template Library**: 200+ pre-built solutions for common business needs

<figure><img src="/files/FwehknSPi0LC1eHFeAE0" alt=""><figcaption><p>No-code interface makes AI automation accessible to everyone</p></figcaption></figure>

## 🚀 **Key Platform Features**

### **🤖 Intelligent Agent Builder**

* **11-Tab Configuration**: Complete control over agent behavior and capabilities
* **Multi-Agent Teams**: Create specialized agents that work together
* **Advanced AI Models**: Access to GPT-4, Claude, Gemini, and 50+ other models
* **Custom Knowledge**: Upload documents, connect databases, crawl websites

### **⚡ Visual Workflow Engine**

* **80+ Node Types**: From AI models to business integrations
* **Logic & Control**: Conditions, loops, parallel processing, error handling
* **Data Processing**: Transform, filter, and enrich data automatically
* **Real-Time Monitoring**: Watch workflows execute with live data flow

### **🔗 Universal Integrations**

{% embed url="<https://www.youtube.com/watch?v=GEBRHLCCf3s>" %}
Mia Copilot Gets 10,000+ Tools! (17:11) - Most Popular Video: Watch how AgenticFlow's massive tool expansion transforms agents into automation powerhouses with unprecedented access to apps, APIs, databases, and services.
{% endembed %}

* **MCP Protocol**: 300+ pre-built tool integrations
* **Business Systems**: CRMs, databases, cloud storage, communication tools
* **AI Services**: Multiple AI providers for optimal performance and cost
* **Custom APIs**: Connect to any system with REST APIs or webhooks

### **🌍 Community & Marketplace**

* **Template Marketplace**: Discover and share automation solutions
* **Active Community**: Learn from thousands of automation experts
* **Regular Events**: Webinars, workshops, and training sessions
* **Expert Support**: Professional services for complex implementations

## 🚀 **Getting Started with AgenticFlow**

```mermaid
journey
    title User Onboarding Journey
    section Discovery
        Visit Platform: 5: User
        Watch Overview Video: 4: User
        Choose Path: 3: User
    section Setup
        Create Account: 5: User
        First Agent/Workflow: 4: User
        Connect Tools: 3: User
    section Deploy
        Test & Refine: 4: User
        Go Live: 5: User
        Scale Up: 5: User
```

### **Choose Your Path**

#### **🤖 Start with AI Agents**

Perfect for customer service, sales support, and interactive assistance:

1. **Sign Up**: Create your free account at [agenticflow.ai](https://agenticflow.ai)
2. **Follow the Guide**: [**Agents Quickstart**](/get-started/agents-quickstart) - Build your first agent
3. **Quick Start**: [Your First 5 Minutes](/get-started/your-first-5-minutes) - Get up and running immediately
4. **Add Knowledge**: Upload documents or connect to your data sources
5. **Deploy & Test**: Launch your agent and start conversations

#### **⚡ Start with Workflows**

Ideal for automation, data processing, and systematic tasks:

1. **Visual Guide**: [**Workflows Quickstart**](/get-started/workflows-quickstart) - Build your first workflow
2. **Browse Templates**: Explore 200+ pre-built automation solutions
3. **Connect Tools**: Link to your existing business systems with 300+ integrations
4. **Test & Refine**: Run test executions and optimize performance
5. **Deploy & Scale**: Launch automations across your organization

<figure><img src="/files/jelNUgVf892bhrVuMhBC" alt=""><figcaption><p>Visual workflow builder interface</p></figcaption></figure>

### **🏢 Enterprise Workforce**

Ready to build multi-agent teams?

1. **Master Guide**: [🎨 **Visual Workforce Builder Guide**](/workforce/multi-agent-systems-guide) - Complete multi-agent orchestration
2. **Team Planning**: Define roles and responsibilities for your AI workforce
3. **Visual Builder**: Use our drag-and-drop interface to connect agents
4. **Integration Setup**: Connect to your business systems and processes
5. **Deployment**: Launch your AI workforce and monitor performance

### **📈 Success Framework**

**Phase 1: Foundation (Week 1)**

* Set up your first agent or workflow
* Connect essential business tools
* Run initial tests and gather feedback

**Phase 2: Expansion (Month 1)**

* Add more sophisticated automations
* Create specialized agents for different roles
* Integrate with additional business systems

**Phase 3: Scale (Month 2+)**

* Deploy across departments and teams
* Build multi-agent workforces
* Optimize based on performance data

### Support and Resources

For any questions or assistance, our support team is here to help. Access our comprehensive documentation, tutorials, and FAQs on our support portal. Additionally, join our regular training sessions and webinars to stay up-to-date with new features and best practices.

### Conclusion

AgenticFlow AI is your ultimate solution for AI-powered task automation, designed to help you scale your business operations efficiently. With a robust library of customizable workflows, easy-to-use tools, and a supportive community, you have everything you need to drive your company's growth and success.

***

Start your journey with AgenticFlow AI today and experience the power of AI-driven automation in transforming your business.

### Learn More

Explore our detailed guides and tutorials to unlock the full potential of AgenticFlow AI. Join our community on [Discord](https://qra.ai/discord) to connect with other users, share your projects, and get support from our team. We’re excited to see what you build with AgenticFlow AI!

<figure><img src="/files/H7sF60Ur19Kls33pUrwH" alt=""><figcaption></figcaption></figure>

If you have any questions or need assistance, reach out to our [support team](mailto:support@agenticflow.ai) or [join our community forums](https://community.agenticflow.ai/) or [our Discord](https://qra.ai/discord) for further guidance.


# Ecosystem: Platform · CLI · Ishi · AI Toolkit

How the AgenticFlow platform, CLI, Ishi, AI toolkit, and documentation fit together.

AgenticFlow is **one platform** surfaced through **multiple layers**. Each layer has a single responsibility. Together they let a human (or their AI agent) go from intent to a deployed, running agent in a single conversation.

<figure><img src="/files/iNRHCh1PnxC8LnUejyU3" alt=""><figcaption></figcaption></figure>

{% embed url="<https://youtu.be/VfTkY9EQTGA?si=quH8SIFKEBxrK5yS>" %}

## Why we built it this way

AgenticFlow's engine is powerful — multi-agent systems, MCP servers, code execution, native web search, agent task management, Anthropic-compatible skills, webhooks. But power without accessibility is a paradox: community feedback consistently pointed at configuration barriers, learning curves, and "2,000 pages of docs + 250 videos" failing to close the gap for non-technical users.

The fix is not more documentation. It is a different interface.

So we split the ecosystem into **two aligned parts**:

1. **The engine** — [app.agenticflow.ai](https://app.agenticflow.ai) keeps evolving as the production backend where agents, workforces, workflows, MCP clients, knowledge bases, and runs actually live. Product work prioritizes stability, traceability, versioning, and UX.
2. **The accessible interface layer** — a CLI (`af`) that exposes platform capabilities in a shape AI agents can drive, plus Ishi and AI-toolkit guidance for compatible developer tools.

This mirrors an industry-wide shift. [Shopify AI Toolkit](https://x.com/shopify/status/2042335627862032754) takes the same approach — expose the platform as an AI-readable contract, let the assistant do the configuration, let the human focus on intent. AgenticFlow's bet is the same: **you brief your AI, your AI talks to our CLI, the CLI configures AgenticFlow, and AgenticFlow serves your customers.**

## CLI-assisted operation

The CLI gives humans and AI coding tools the same operational contract:

* discover available platform capabilities
* validate payloads before creating resources
* create and update agents, workflows, and workforces
* inspect run state and hand back links to the Web UI

AgenticFlow remains the source of truth. The CLI and AI Toolkit are interfaces for configuring and operating the same platform resources.

## Ishi — first-party desktop AI agent

Ishi is AgenticFlow's first-party desktop AI agent. It uses the AgenticFlow CLI and API as its configuration backbone, so resources created through Ishi land in the same AgenticFlow workspace as resources created through the Web UI, API, or CLI.

Ishi is part of the AgenticFlow ecosystem, not a replacement for AgenticFlow. The product architecture remains: AgenticFlow owns the platform resources and runtime, while Ishi provides a conversational desktop interface for driving those resources.

## The six layers

| Layer                | Lives at                                                                                    | Audience             | Owns                                                |
| -------------------- | ------------------------------------------------------------------------------------------- | -------------------- | --------------------------------------------------- |
| **Core platform**    | [app.agenticflow.ai](https://app.agenticflow.ai)                                            | Both (UI or API)     | Resources, state, billing, auth, runtime            |
| **Visual UI**        | Same host, browser                                                                          | Human                | Drag-and-drop building, dashboards, trace viewer    |
| **CLI** (`af`)       | [`@pixelml/agenticflow-cli`](https://www.npmjs.com/package/@pixelml/agenticflow-cli) on npm | Developer + AI agent | Programmatic access, payload shapes, error envelope |
| **AI Toolkit**       | Compatible AI coding tools                                                                  | AI agent in IDE      | Routing — tells your AI which CLI command to run    |
| **Ishi + AI hosts**  | User's chosen desktop or developer environment                                              | Human + AI operator  | Local context and command execution                 |
| **Docs** (this site) | Browser                                                                                     | Human                | Concepts, integrations, node reference              |

No layer duplicates another's data. Skills in the AI Toolkit point at `af bootstrap` for the live model list. Docs link to CLI help for command reference. CLI links back here for concepts. Ishi and other AI-assisted hosts use the CLI and the platform — they don't hold their own copy of your resources. **The core platform is the single source of truth.**

## Layer diagram

```
                  ┌─────────────────────────────────────────────────┐
                  │           Core Platform                         │
                  │           app.agenticflow.ai                    │   Source of truth:
                  │           (UI + REST API + runtime)             │   agents, workforces,
                  └─────────────────────┬───────────────────────────┘   MCP clients, runs,
                                        │                               trace log.
               ┌────────────────────────┼─────────────────────────┐
               ▼                        ▼                         ▼
     ┌─────────────────┐       ┌──────────────┐         ┌─────────────────┐
     │  af CLI (npm)   │       │  Visual UI   │         │   Docs (this)   │
     │  payload shapes │       │  (browser)   │         │   concepts,     │
     │  error envelope │       │  human-first │         │   node library  │
     └────────┬────────┘       └──────────────┘         └─────────────────┘
              │
              │  consumed by:
              ▼
  ┌───────────────────────────────────────────────────────────────────┐
  │                    Ishi + AI-assisted hosts                       │
  │                                                                   │
  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────────────────┐ │
  │  │ Ishi     │  │ Claude   │  │ OpenAI   │  │ Cursor / Gemini    │ │
  │  │          │  │ Code     │  │ Codex    │  │ CLI                │ │
  │  └──────────┘  └──────────┘  └──────────┘  └────────────────────┘ │
  │       ▲             ▲             ▲                 ▲             │
  │       └─────────────┴─────────────┴─────────────────┘             │
  │          each loads the AI Toolkit skill pack, which routes       │
  │          user intent to the right `af` CLI command                │
  └───────────────────────────────────────────────────────────────────┘
                              ▲
                              │
                          Human user
                          (briefs intent in natural language)
```

The **CLI is the contract**. Whether the human is using Ishi, Claude Code, Cursor, Codex, Gemini CLI, or the AI Toolkit skill pack in another compatible host, the path to AgenticFlow is the same set of `af` commands with the same error envelope, the same `--dry-run` safety, and the same `af bootstrap` discovery.

## What each surface does

### Core Platform

The authoritative home for every resource. When you create an agent via the UI, the CLI, or the API, it lands in the same place. The `_links` block in `af bootstrap --json` returns URLs back into the UI so AI agents can hand off to their human at any point.

### Visual UI

The human path. Drag-and-drop workflow builder, agent 11-tab configuration, workforce graph canvas, connections management, knowledge library, dashboards. Best for design-first workflows, understanding the mental model, and reviewing what an AI agent built.

### `af` CLI

The **API contract for AI operators**. Every platform capability is exposed here with four amplifications that make it safe for autonomous use:

* **Local validation** — `--dry-run` on create/deploy commands catches shape errors before the network round-trip
* **Structured errors** — every failure returns `{schema: "agenticflow.error.v1", code, message, hint, details.payload}` with an actionable `hint` pointing at the next command
* **Partial updates** — `af agent update --patch` fetches → merges → PUTs, preserving attached MCP clients and tools
* **Self-description** — `af bootstrap/schema/context/playbook/changelog` returns everything an AI needs in one call

Developers use it directly for scripting. AI agents use it under the direction of the AI Toolkit.

### AI Toolkit

The **routing layer for AI agents** operating inside compatible developer tools and first-party desktop flows. Installed once via each host's plugin or skill mechanism when available. Three narrow flagship skills:

* **`agenticflow-workforce`** — multi-agent DAGs (coordinator → worker agents)
* **`agenticflow-agent`** — single-agent create/run/update
* **`agenticflow-mcp`** — attach external tool providers safely

Each skill has a tight `description` and `triggers[]` that routes user prompts. A `⚠️ When NOT to use` block on every skill points at its sibling to prevent over-engineering (e.g. don't spin up a workforce for a single-bot task).

The toolkit doesn't duplicate CLI knowledge — it tells the AI which CLI command to run and passes live output through.

### Ishi and AI-assisted hosts

The **human-facing operational layer**. Ishi or another compatible AI host can read the local context you allow it to access, take your natural-language intent, and drive the AgenticFlow CLI on your behalf — then report back with what it built.

Ishi is the first-party desktop AI agent in this layer. Claude Code, OpenAI Codex, Cursor, Gemini CLI, and similar hosts can load the AI Toolkit guidance and get the same CLI-driven integration. The CLI is the contract, so any compatible host can drive it.

Human, Ishi, and other AI-assisted paths converge at the same `af` commands with the same `bootstrap`/`schema`/`playbook` discovery surface.

### Docs (you are here)

The human-facing long-form library. Concepts, UI walkthroughs, integration tutorials, the 193+ node library in [Reference](/reference/nodes), industry use cases, enterprise guidance.

## Design principles

1. **CLI is the API contract for AI.** Anything an AI needs — auth, resources, schemas, shapes, changelog, playbooks, blueprints, marketplace — is in one of `af bootstrap/schema/context/playbook/changelog/blueprints/marketplace`. Ishi and compatible AI hosts consume the same surface.
2. **Toolkit routes, CLI answers.** Skills stay small (\~150 LOC) and point at CLI for live truth.
3. **Docs for humans, skills for AIs.** Overlap is a smell. If content drifts between them, delete one.
4. **Fail loud, hint clearly.** Every 4xx/5xx carries a recovery command in `hint`.
5. **One SoT per concern.** Concepts → docs. Commands → CLI. Routing → AI toolkit. Resources → platform. Local context → desktop agent.
6. **Local context stays explicit.** Anything running on the user's machine should use the local files and credentials the user intentionally provides.
7. **Stability first on the engine.** AgenticFlow platform stability, traceability, versioning, and UX remain the priority. Desktop-agent flows should use the same CLI and API surfaces as the rest of the platform.

## First-touch: human journey

A new user visits the platform:

1. **Sign up** at [app.agenticflow.ai](https://app.agenticflow.ai) → workspace + project auto-created.
2. **Generate an API key** at **Settings → API Keys**.
3. Decide on a path:

   **Path A — Click to build.** Open the UI, follow [Quickstart](/get-started/01-quickstart). Best for understanding the product.

   **Path B — Script with the CLI.** `npm install -g @pixelml/agenticflow-cli`, then:

   ```bash
   af login                # or set AGENTICFLOW_API_KEY / _WORKSPACE_ID / _PROJECT_ID
   af doctor --json --strict
   af bootstrap --json     # always start here
   ```

   See [CLI Reference](/developers/cli) for the full surface.

   **Path C — Let your AI do it.** Use Ishi or load the AgenticFlow AI Toolkit into Claude Code / OpenAI Codex / Cursor / Gemini CLI or another compatible host. Describe what you want in natural language — the agent handles the CLI calls. No JSON, no payload shapes, no command memorization.

   Then prompt your AI in plain language: *"Build me a customer support bot for my SaaS"*. The AI handles the CLI workflow below.
4. Each path converges on the same workspace — switch freely between UI, CLI, and AI-driven work.

**Target time-to-value:** under five minutes from signup to a deployed, runnable agent.

## First-touch: AI-agent journey (under the hood)

When a user in an IDE prompts their AI to build something on AgenticFlow, the AI Toolkit plugin activates. The journey the CLI is designed to support:

```
1. Orient:    af bootstrap --json
              ↳ returns auth, agents, workforces, blueprints, playbooks, whats_new, _links
              ↳ check data_fresh — false means backend unreachable, don't mutate

2. Learn:     af playbook <topic> --json
              ↳ e.g. `first-touch`, `migrate-from-paperclip`, `mcp-client-quirks`

3. Shape:     af schema <resource> [--field <name>] --json
              ↳ payload shape for what you're about to create
              ↳ --field drills into nested shapes (mcp_clients, response_format, etc.)

4. Preview:   af <resource> create --body @file --dry-run --json
              ↳ local validation catches shape errors before network

5. Build:     af <resource> create --body @file --json
              ↳ single agent
          OR: af workforce init --blueprint <id> --name "<name>" --json
              ↳ multi-agent team (auto-creates agents + wires the DAG)

6. Test:      af agent run --agent-id <id> --message "..." --json
          OR: af workforce run --workforce-id <id> --trigger-data '{...}'

7. Iterate:   af agent update --agent-id <id> --patch --body '{"field":"new"}' --json
              ↳ preserves MCP clients, tools, code-execution config

8. Ship:      af workforce publish --workforce-id <id> --json
              ↳ mints a public_key + public_url for the user's teammates

9. Cleanup:   af <resource> delete --<resource>-id <id> --json
              ↳ returns {schema:"agenticflow.delete.v1", deleted:true, id, resource}
```

At every step, a 4xx or 5xx response includes a `hint` that names the recovery command — no guessing.

### The composition ladder

AgenticFlow's three deploy verbs (`workflow`, `agent`, `workforce`) are rungs on a complexity ladder. **Start at the lowest rung that solves the user's problem.** Every rung composes from the rungs below.

```
  Rung 6: WORKFORCE (DAG)        Explicit multi-agent coordination
          ─ trigger → coord → [A || B] → synthesizer → output
          ─ References: nodes · workflows · agents · sub-DAGs

  Rung 5: AGENT + SUB-AGENTS     Lite multi-agent, agent-driven
          ─ triage.sub_agents = [specialist_a, specialist_b]

  Rung 4: AGENT + WORKFLOW TOOL  Flexible control + deterministic body
          ─ agent.tools = [{workflow_template_id: "deep_research"}]

  Rung 3: AGENT + NODE PLUGINS   Single flexible agent picks tools dynamically
          ─ agent.plugins = [web_search, web_retrieval, api_call]

  Rung 2: WORKFLOW ENRICHED      Deterministic + real-world data
          ─ trigger → web_retrieval → llm_summarize → output

  Rung 1: WORKFLOW CHAINED       Deterministic sequential reasoning
          ─ trigger → llm_plan → llm_execute → llm_format → output

  Rung 0: WORKFLOW MINIMAL       "Hello world"
          ─ trigger → llm → output
```

**Deploy verb maps 1:1 to kind:**

| Kind        | CLI                                  | Rungs covered         |
| ----------- | ------------------------------------ | --------------------- |
| `workflow`  | `af workflow init --blueprint <id>`  | 0, 1, 2               |
| `agent`     | `af agent init --blueprint <id>`     | 3 (+ 4, 5 on roadmap) |
| `workforce` | `af workforce init --blueprint <id>` | 6                     |

`af blueprints list [--kind <k>] [--complexity <n>] --json` surfaces every shipped blueprint with its rung so AI operators can filter.

### Choosing: agent vs. workforce vs. workflow

The AI Toolkit skills resolve this automatically from the user's prompt, but the underlying rule is simple:

| User intent                                                                            | Choose                                           | Why                                                                      |
| -------------------------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------ |
| Deterministic multi-step pipeline (summarize URL, fetch API, chain LLMs)               | **`af workflow`**                                | Rungs 0-2. Reproducible; no agent needed                                 |
| A single chat endpoint, a customer-facing bot, one assistant                           | **`af agent`**                                   | Rung 3. One prompt handles routing. Iterate with `--patch`               |
| Multiple agents that hand off (research → write, triage → specialist, pre-built teams) | **`af workforce`**                               | Rung 6. One command creates the workforce, all agents, and the wired DAG |
| Attach Google Docs/Sheets/Slack/Notion/etc. to an existing agent                       | **`af mcp-clients` + `af agent update --patch`** | Inspect before attach to avoid tool-schema quirks                        |

Don't reach for a workforce when one agent suffices. Don't reach for an agent when a workflow suffices.

### Starter catalogs: blueprints (offline) and marketplace (live)

Two complementary ways to start from a template:

|           | **Blueprint** (ships with CLI)                                                             | **Marketplace** (live backend)                          |
| --------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------- |
| Discovery | `af blueprints list --json`                                                                | `af marketplace list --type <kind> --json`              |
| Storage   | Version-locked to the CLI release                                                          | Hosted, curated, user-contributable                     |
| Network   | None needed to list                                                                        | Backend call per list/get/clone                         |
| Types     | `workflow` · `agent` · `workforce` kinds (rungs 0-6 of the ladder)                         | `agent_template` · `workflow_template` · `mas_template` |
| Deploy    | `af <kind> init --blueprint <id>` — the CLI picks the right verb from the blueprint's kind | `af marketplace try --id <id>` (auto-detects type)      |

**Workflow blueprints (rungs 0-2, 362 total in CLI v1.10.7)** — deterministic multi-node flows. Need one LLM-provider connection in the workspace (auto-discovered). The table below shows core examples; run `af blueprints list --kind workflow --json` for the full catalog.

| ID              | Rung | Nodes                    | Best for                          |
| --------------- | ---- | ------------------------ | --------------------------------- |
| `llm-hello`     | 0    | llm                      | Learning the model; one-off Q\&A  |
| `llm-chain`     | 1    | llm\_plan → llm\_execute | Plan-then-execute reasoning       |
| `summarize-url` | 2    | web\_retrieval → llm     | Digesting an article URL          |
| `n8n-converter` | 2    | LLM conversion chain     | Converting n8n workflow JSON      |
| `api-summary`   | 2    | api\_call → llm          | Explaining an unfamiliar JSON API |

**Agent blueprints (rung 3, 3 total)** — single agent with built-in plugins. No connection setup needed:

| ID                   | Plugins                                                   | Best for                               |
| -------------------- | --------------------------------------------------------- | -------------------------------------- |
| `research-assistant` | web\_search, web\_retrieval, api\_call, string\_to\_json  | Current-events research with citations |
| `content-creator`    | web\_search, web\_retrieval, agenticflow\_generate\_image | Blog drafts + hero images              |
| `api-helper`         | api\_call, string\_to\_json, web\_search                  | HTTP API wrappers with analysis        |

**Workforce blueprints (rung 6, 14 total)** — multi-agent DAGs (trigger → coordinator → workers → output, optionally → synthesizer). Require the Workforce feature:

| ID                                                                                   | Agents | Shape                                                      |
| ------------------------------------------------------------------------------------ | ------ | ---------------------------------------------------------- |
| `research-pair`                                                                      | 2      | planner → researcher (web\_search + web\_retrieval)        |
| `content-duo`                                                                        | 2      | writer (web) → illustrator (generate\_image)               |
| `api-pipeline`                                                                       | 2      | fetcher (api\_call) → analyst                              |
| `fact-check-loop`                                                                    | 2      | writer → fact\_checker (verify claims via web\_search)     |
| `parallel-research`                                                                  | 4      | coordinator → 2 researchers (parallel) → synthesizer       |
| `autonomous-desk`                                                                    | 4      | planner → route gate → research/workflow → critic → editor |
| `dev-shop` · `marketing-agency` · `sales-team` · `content-studio` · `support-center` | 2-4    | Vertical teams (generic agents, attach your own tools)     |
| `amazon-seller` · `tutor` · `freelancer`                                             | 5      | Domain-specific vertical teams                             |

The first 6 workforce blueprints (`research-pair` through `autonomous-desk`) have AgenticFlow-native plugins or verified graph wiring pre-attached, so they work end-to-end with zero follow-up setup. `autonomous-desk` is the high-autonomy option for missions that need plan, execute, critique, revise, and edit loops.

**Roadmap:** Rungs 4 (agent + workflow tool) and 5 (agent + sub-agents) are supported by the backend but not yet exposed as CLI blueprints — planned in a follow-up release.

### Copy-paste prompts

Short, minimal-context prompts a user can paste to any AI assistant with `af` access, which then discovers + deploys via the CLI:

```
Set up a research agent that cites sources from the web. Use `af`, test with a real
current-events question, clean up after.
```

```
Deploy a parallel-research workforce via `af`, test with a "compare X vs Y" question.
Confirm both researchers ran in parallel and the synthesizer produced a unified answer.
Clean up after.
```

Full catalog: `af playbook ready-prompts`.

## How the surfaces stay in sync

Avoiding drift between four moving parts requires discipline:

* **CLI `playbooks.ts` is the source of truth** for playbook content. AI Toolkit skills regenerate from it (via a forthcoming `sync-from-cli.mjs` mechanism).
* **CLI `changelog.ts` is the source of truth** for version history. Surfaced via `af changelog --json` and consumed by docs + marketing.
* **`af bootstrap`-backed live data** (models, blueprints, workforces, agents) is queried at runtime — never hardcoded in docs or skills.
* **Platform is the SoT for resources.** Docs describe what a workforce IS; CLI is how you create one; platform is where it LIVES.

## Version alignment

* **Platform**: continuous — [app.agenticflow.ai](https://app.agenticflow.ai)
* **CLI**: [`@pixelml/agenticflow-cli@1.10.7`](https://www.npmjs.com/package/@pixelml/agenticflow-cli) (npm, tag-triggered auto-publish)
* **SDK**: [`@pixelml/agenticflow-sdk@1.6.0`](https://www.npmjs.com/package/@pixelml/agenticflow-sdk) (shipped alongside CLI)
* **AI Toolkit**: `v4.3.0` — distributed to Claude, Codex, Cursor, Gemini plugin marketplaces
* **Ishi**: desktop AI agent (first-party)
* **Docs**: this GitBook — continuously updated

When a new CLI version ships, `af changelog --json` surfaces the changes. The AI Toolkit's `scripts/sync-from-cli.mjs` will pull them into the skill content automatically (planned — manual sync in the interim).

## Next steps

* [Quickstart](/get-started/01-quickstart) — five-minute human onboarding
* [AgenticFlow CLI](/developers/cli) — developer-facing CLI overview
* [CLI Command Reference](/developers/agenticflow-cli-capabilities) — every command, every flag
* [API Overview](/developers/api) — REST contract below the CLI
* [Agents](/ai-agents/03-agents) — single-agent concepts
* [Workforce](/workforce/05-workforce) — multi-agent orchestration concepts
* [Integrations](/integrations/07-integrations) — MCP providers and 300+ tools

### Install the AI Toolkit

* **Claude Code**: install the AgenticFlow AI Toolkit from the host's plugin flow when available.
* **Gemini CLI**: install the AgenticFlow AI Toolkit from the host's extension flow when available.
* **Cursor**: Install from Cursor Marketplace
* **OpenAI Codex CLI**: `/plugins` → search AgenticFlow → Add to Codex
* **Other / VS Code**: use the host's plugin or project-instruction mechanism with the current AgenticFlow CLI guidance.


# CLI Walkthrough — Build a Demo Stack

A hands-on runbook — follow along and you'll build a live AgenticFlow demo stack (workflows, agents, a workforce) driven by your favorite AI coding agent. Takes \~20 minutes. No prior AgenticFlow exper

You're about to build a live AgenticFlow stack — **2 workflows, 2 agents, and a multi-agent workforce** — driven by Ishi or another AI coding agent using the AgenticFlow CLI.

You don't touch the AgenticFlow UI for any of the building. You paste prompts, your AI does the work, and at the end every resource it built is **live in your AgenticFlow workspace** — ready to show anyone, including customers.

This is what the whole AgenticFlow ecosystem feels like when it works. Follow along.

***

## What you'll need (2 minutes)

1. **An AgenticFlow account.** Sign up at [app.agenticflow.ai](https://app.agenticflow.ai) — workspace and project auto-create.
2. **An API key.** Go to **Settings → API Keys** in the web UI, create one, copy it.
3. **A desktop AI coding agent.** Any compatible host, such as:
   * Ishi
   * Claude Code (recommended for this walkthrough)
   * Cursor
   * OpenAI Codex CLI
   * Gemini CLI
4. **Node.js 18+** on your laptop.

## Step 1 — Install the CLI (1 minute)

Open a terminal and run:

```bash
npm install -g @pixelml/agenticflow-cli
agenticflow login        # paste your API key when prompted
agenticflow bootstrap --json | jq '.auth'
```

If the last command prints `{"authenticated": true, ...}`, you're good.

> **No global install?** Every prompt below works without it — your AI will fall back to `npx --yes @pixelml/agenticflow-cli`. `af bootstrap --json` returns an `invocation` block that tells AI operators exactly how to call the CLI; the AI Toolkit skill (Step 2) carries the same guidance. You shouldn't need to think about invocation — just paste the prompts and let your AI figure it out.

## Step 2 — Install the AI Toolkit in your AI host (1 minute, optional but recommended)

The AI Toolkit teaches your AI agent how to drive AgenticFlow correctly. Without it, your AI will still figure things out — but it'll over-engineer or pick the wrong primitive more often. **With it, your AI picks the right thing first try.**

Use your AI host's plugin, skill, or instruction mechanism to load the AgenticFlow AI Toolkit when available. In OpenAI Codex CLI, open `/plugins`, search AgenticFlow, and add it to Codex. In other hosts, search for AgenticFlow in the host's marketplace or attach the current AgenticFlow CLI guidance as project instructions.

When the install finishes, restart the AI host so the new skill loads.

***

{% hint style="info" %}
**If your AI stumbles** ("not found", `ModuleNotFoundError`, or tries `npx af` and gets a wrong package), paste this one-liner:

> Use `agenticflow <subcommand>` if installed, else `npx --yes @pixelml/agenticflow-cli <subcommand>`. Don't use `af` (2-letter name, often collides) and never `npx af` (wrong package). Continue.
> {% endhint %}

## Step 3 — Build your first workflow (\~2 minutes)

**Open your AI host (Claude Code / Cursor / etc.) and paste this message:**

> Using the AgenticFlow CLI, build the simplest thing that fetches a URL and summarizes it. Pick an interesting Wikipedia article as the demo URL, deploy, run once, show me the summary.
>
> Leave the workflow deployed. At the end, print the Web UI link for it. One-line note: why this rung of the composition ladder?

### What you'll see the AI do

The AI will run these commands in order (roughly):

1. `af bootstrap --json` — orient itself
2. `af blueprints list --kind workflow --json` — find the workflow blueprints
3. `af workflow init --blueprint summarize-url --name "Demo · URL Summarizer" --json` — deploy
4. `af workflow run --workflow-id <id> --input '{"url":"https://en.wikipedia.org/wiki/..."}' --json` — run
5. `af workflow run-status --run-id <id> --json` — poll until done
6. Print the 3-bullet summary
7. Print the Web UI link

**Expected wall time:** 30-60 seconds.

### What to do next

**Click the Web UI link your AI printed.** You'll see the workflow canvas: a trigger node → a web\_retrieval node → an llm node → output. This is rung 2 of the composition ladder — the simplest useful workflow shape.

You can click **Run** in the UI with a different URL to prove it's a real, persistent resource.

***

## Step 4 — Build a second workflow with an HTTP API call (\~2 minutes)

**Paste this into your AI:**

> Using the AgenticFlow CLI, deploy a workflow that calls a public JSON API and explains the response in plain English. Pick an interesting endpoint yourself (GitHub, a weather API, jsonplaceholder, etc.). Run it once. Show me the explanation.
>
> Leave the workflow deployed. Print the Web UI link at the end.
>
> Get the workspace\_id from `af bootstrap --json`.

### What you'll see

Same pattern as Step 3, but with `api-summary` blueprint. The AI picks a real public API (likely GitHub or jsonplaceholder), calls it, parses the JSON response, and an LLM explains what each field means in plain English.

### What to do next

Click the Web UI link. Compare this workflow's canvas to Step 3's. Notice the shape is almost identical — just different nodes. **That's the point**: workflows are composable at the node level. Swap `web_retrieval` for `api_call` and you have a different deterministic tool.

***

## Step 5 — Build a flexible agent (\~2 minutes)

Now climb the ladder. Workflows are deterministic. **Agents are flexible** — same plugins are available, but an LLM decides which to call per turn.

**Paste this into your AI:**

> Using the AgenticFlow CLI, deploy a research agent that answers current-events questions with cited web sources. Test it with a real question about a technology release from the last 60 days — confirm the response cites real URLs (not training-data paraphrase).
>
> Leave the agent deployed. At the end, print the Web UI links for the agent AND the specific conversation thread.
>
> Get workspace\_id from `af bootstrap --json`.

### What you'll see

The AI deploys the `research-assistant` blueprint, runs it with a recent-news question, and reports back with real URLs in the answer. If you paste the URLs into your browser, they'll lead to real pages (OpenAI docs, Anthropic blog posts, news articles — whatever the agent found).

**Wall time:** 1-2 minutes (web\_search + web\_retrieval take longer than a deterministic workflow).

### What to do next

Click the **thread URL**. You'll see the full conversation — your message, the agent's tool calls (you can expand each `web_search` call to see the exact query it ran and the URLs it retrieved), and the final answer with citations.

**This is the "glass box" philosophy**: every tool call the agent made is visible and auditable. Compare that to a chat bot that gives you an answer and hopes you trust it.

***

## Step 6 — Build an agent that writes AND generates images (\~3 minutes)

Same rung as Step 5, different plugin loadout — this agent has `agenticflow_generate_image` instead of `api_call`.

**Paste this into your AI:**

> Using the AgenticFlow CLI, deploy an agent that drafts written content AND generates a matching image. Pick a topic yourself (e.g. "LinkedIn post on AI agents in 2026"). Run it once — show me both the written draft AND evidence the image plugin fired.
>
> Leave the agent deployed. Print the Web UI links for the agent AND the specific thread.
>
> Get workspace\_id from `af bootstrap --json`.

### What you'll see

A written draft (150-300 words, whatever topic you gave it) plus either an image URL or an image descriptor in the response. The agent autonomously decided to use `web_search` first (for current context), then `agenticflow_generate_image` (for the visual).

### What to do next

Open the thread URL. You'll see the agent's tool-call sequence: search → compose → generate image. **The order isn't hardcoded** — the agent decided. If you re-run with a different prompt, the order might change. That's the difference between a workflow (deterministic) and an agent (flexible).

***

## Step 7 — Build a multi-agent workforce (\~3 minutes)

Top of the ladder. Rung 6. **When genuine multi-agent coordination helps**, you use a workforce.

**Paste this into your AI:**

> Using the AgenticFlow CLI, deploy a multi-agent team that investigates a "compare X vs Y" question. Two researchers work in parallel, a synthesizer merges their findings. Pick a realistic X vs Y (something a developer or business audience would find interesting).
>
> Deploy, publish it so it has a public URL, kick off a run, wait for completion, show me the synthesizer's final unified answer.
>
> Leave the workforce and all its agents deployed. Print the Web UI canvas link and the public run URL at the end.

### What you'll see

The AI deploys the `parallel-research` blueprint. Behind the scenes, that creates **four real agents** (Coordinator, Researcher A, Researcher B, Synthesizer) and wires them into a graph: trigger → coordinator → \[A || B in parallel] → synthesizer → output.

The AI publishes it, kicks off a run, waits for all four agents to finish, then shows you the synthesizer's unified answer with attribution like *"(Researcher A)"* and *"(Researcher B)"* tags.

**Wall time:** 2-3 minutes (four LLM agents plus synthesis).

### What to do next

1. **Click the workforce canvas link.** You'll see the full DAG visually — four agent nodes, edges showing the fan-out + fan-in, a trigger, an output.
2. **Click the public run URL.** Send this to anyone — no AgenticFlow account needed. They can invoke your workforce right from the browser.

**This is the moment the ladder pays off.** Your first workflow (Step 3) and this workforce (Step 7) use the same underlying platform — but the workforce solves a problem a single workflow or agent can't: independent parallel investigation by multiple agents followed by structured synthesis.

***

## Step 8 — Ask your AI to pick the rung for a custom task (\~2 minutes)

This is the most important step. Up to now you've been telling the AI which rung to build on. Now you hand it an open-ended task and let it decide.

**Paste this into your AI — replace the bracketed line with whatever you want:**

> Using the AgenticFlow CLI, do this task for me:
>
> ```
> <REPLACE THIS LINE WITH YOUR OWN TASK — ANYTHING>
> ```
>
> Pick the lowest rung of the composition ladder that solves it (workflow < agent < workforce). Deploy, run once with realistic input, show me the output.
>
> Leave what you deployed. Print the Web UI link at the end. One-line note: why that rung?

### Example tasks to try

| Task you paste                                    | Expected rung | Why                          |
| ------------------------------------------------- | ------------- | ---------------------------- |
| "Summarize this Reuters article URL: https\://…"  | 2 (workflow)  | Deterministic transform      |
| "Explain what this API endpoint returns"          | 2 (workflow)  | Same — deterministic         |
| "Answer questions about the latest OpenAI models" | 3 (agent)     | Open-ended tool use          |
| "Write a blog post with a hero image"             | 3 (agent)     | Agent routes between plugins |
| "Compare AWS vs GCP for AI startups"              | 6 (workforce) | Parallel investigation helps |
| "Set up an Amazon Singapore seller team"          | 6 (workforce) | Vertical-team blueprint fits |

If your AI picks wrong, the AI Toolkit skill (Step 2) isn't installed properly. The skill has the rung-picking rule baked in — without it, your AI is guessing from `af --help`.

***

## Your workspace, right now

Run this in your terminal to see everything you built:

```bash
af bootstrap --json | jq '{
  agents: [.agents[] | select(.name | startswith("Demo")) | .name],
  workforces: [.workforces[] | select(.name | startswith("Demo")) | .name]
}'
af workflow list --name-contains "Demo" --fields id,name --json
```

You should see (at minimum):

* **Workflows**: Demo · URL Summarizer, Demo · API Explainer
* **Agents**: Demo · Research Agent, Demo · Content Creator, plus 4 agents inside the workforce
* **Workforces**: Demo · Parallel Research Team

Every one of these is live. Click any Web UI link you collected and it's there — the canvas, the history, the trace log.

## Showing this to someone

The two most dramatic things to show a visitor:

1. **The workforce's public URL** from Step 7. No auth required. Send it over email, put it on a slide, they can run your workforce themselves.
2. **An agent thread** from Step 5 or 6. Expand the tool calls so they can see the agent chose `web_search`, saw the results, chose `web_retrieval` on the most promising URL, then composed the answer. The decision-making is visible, not hidden.

## When you want to reset

The stack persists until you tear it down. When you're ready:

```bash
# Delete everything named "Demo · …" — scoped to this walkthrough only
af workforce list --name-contains "Demo" --fields id --json \
  | jq -r '.[].id' | xargs -I{} af workforce delete --workforce-id {} --json

af agent list --name-contains "Demo" --fields id --json \
  | jq -r '.[].id' | xargs -I{} af agent delete --agent-id {} --json

af workflow list --name-contains "Demo" --fields id --json \
  | jq -r '.[].id' | xargs -I{} af workflow delete --workflow-id {} --json
```

Or leave them. The whole point of a demo stack is it stays runnable.

***

## Troubleshooting

**"My AI host reports `af: command not found` or `af not found`."**

You skipped the global install in Step 1 (or it failed silently). Easiest fix: paste this follow-up:

> Use `agenticflow <subcommand>` if installed, or `npx --yes @pixelml/agenticflow-cli <subcommand>` otherwise. Continue the task.

Or install globally: `npm install -g @pixelml/agenticflow-cli`, then re-paste the original prompt.

**"My AI reports `ModuleNotFoundError`, a Python traceback, or some unrelated tool when calling `af`."**

**Name collision.** `af` is a generic 2-letter command that other tools claim — Python packages with broken venvs, homebrew formulas, shell aliases. The one on your system isn't ours.

Diagnose:

```bash
command -v af && type af
# Then try the canonical name:
command -v agenticflow && agenticflow --version
```

**Fix:** use `agenticflow` (the full canonical binary name — the CLI installs BOTH `agenticflow` and `af`) instead of `af`. `agenticflow` is 11 characters long and unlikely to collide with anything. Paste:

> Skip `af` entirely — name collision with another tool on my system. Use `agenticflow <subcommand>` instead. If `agenticflow` isn't on PATH either, fall back to `npx --yes @pixelml/agenticflow-cli <subcommand>`. Continue the task.

**"My AI tried `npx af` and got a different tool / weird errors."**

`npx af` treats `af` as a package name and fetches whatever package is named `af` on npm — **not our CLI**. The only reliable npx invocation is `npx --yes @pixelml/agenticflow-cli <subcommand>` (full package name, with `--yes` to auto-accept the install prompt). Paste the one-liner from the previous bullet to correct the AI.

**"I don't have the AI Toolkit installed but my AI keeps making wrong picks."**

Go back to Step 2 and install it. Then restart your AI host. The Toolkit is \~150 lines of routing rules that make a meaningful difference.

**"Step 5 or 6 returned `status: "completed_empty"`."**

The agent exhausted its recursion limit in a tool loop. This was common on older CLI versions; v1.10.1+ ships with `recursion_limit: 100` by default and it's rare now. If you hit it, bump the limit:

```bash
af agent update --agent-id <id> --patch --body '{"recursion_limit":100}' --json
```

Then re-run the `af agent run` call.

**"Step 7's public URL 404s when I open it in a browser."**

You're opening the *run* endpoint, which is POST-only. Construct the correct public URL — it's `https://agenticflow.ai/workforce/public/<public_key>` (no `/run`).

**"`af workforce run` returns 400 — `Failed to retrieve user info`."**

This is a known backend limitation on API-key auth for that specific command. The walkthrough uses `af workforce publish` + a direct `curl` to the public endpoint to work around it. If your AI used `af workforce run` instead, point it at the public-URL path.

**"My workspace shows different agent/workflow counts than expected."**

Some steps create resources inside other resources (the workforce in Step 7 creates 4 agents). Run the `af bootstrap --json | jq` command in the "Your workspace, right now" section for the real inventory filtered to `Demo · …` prefixed resources.

***

## Where to go from here

* [Ecosystem overview](/welcome-to-agenticflow/ecosystem) — the composition ladder explained, plus why we built it this way
* [CLI Reference](/developers/cli) — every command, every flag
* AI Toolkit — the routing layer that makes your AI pick the right rung on the first try
* [Agents concepts](/ai-agents/03-agents) — the 11-tab agent configuration model in the Web UI
* [Workforce concepts](/workforce/05-workforce) — how the multi-agent DAG engine works


# Navigation Guide

## 🎯 Quick Navigation Based on Your Goal

### "I want to..."

#### 🚀 **Start using AgenticFlow immediately**

```
📍 Path: Get Started → Your First 5 Minutes
```

* Build your first agent in 5 minutes
* No prerequisites needed
* Hands-on immediate value

#### 📚 **Learn the core concepts**

```
📍 Path: Learning → Key Concepts
```

* Core platform concepts
* Feature quickstarts
* Videos and office-hours recaps

#### 🤖 **Build an AI agent**

```
📍 Path: AI Agents → Agent Quickstart
   OR
📍 Path: Get Started → Your First 5 Minutes
```

* Visual 11-tab configuration system
* Templates available
* Multi-modal capabilities

#### ⚡ **Create an automation workflow**

```
📍 Path: Visual Workflows → Workflow Quickstart
```

* Drag-and-drop builder
* 193+ pre-built nodes
* No coding required

#### 👥 **Build a team of AI agents**

```
📍 Path: Workforce → Building Your First AI Team
```

* Multi-agent orchestration
* Team templates (Customer Service, Sales, Content)
* Visual team builder

#### 🔗 **Connect external tools (Slack, Google, etc.)**

```
📍 Path: 300+ Integrations → Popular Business Tools
   OR
📍 Path: Get Started → API Keys (for LLM setup)
```

* MCP protocol for 10,000+ tools
* No-code authentication
* Pre-built connectors

#### 📹 **Watch video tutorials**

```
📍 Path: Learning & Community → Video Learning → Complete Video Library
```

* 96+ tutorial videos
* Organized by topic
* From basics to advanced

#### 🎓 **Train my team**

```
📍 Path: Learning → Quickstarts and Video Tutorials
```

* Quickstarts by feature
* Video learning resources
* Team enablement material

***

## 👤 Navigation by User Type

### 🆕 **Complete Beginner**

**Your Learning Path:**

1. `Get Started` → Introduction to No-Code AI
2. `Get Started` → Your First 5 Minutes
3. `Get Started` → Choose Your Path
4. `Learning` → Video Tutorials (if you want guided learning)

### 💼 **Business User (Non-Technical)**

**Your Learning Path:**

1. `Get Started` → Choose Your Path
2. `Use Cases` → Your Industry/Department
3. `AI Agents` → Agent Templates
4. `Workforce` → Team Templates

### 👨‍💻 **Developer/Technical User**

**Your Learning Path:**

1. `Get Started` → API Keys
2. `API & Extensions` → REST API Overview
3. `300+ Integrations` → MCP Protocol
4. `Visual Workflows` → Custom Logic Nodes

### 🏢 **Enterprise Decision Maker**

**Your Learning Path:**

1. `Enterprise Features` → Security & Compliance
2. `Enterprise Features` → Multi-Tenant Workspaces
3. `Credits & Billing` → Plans and Credits
4. `Learning & Community` → Success Stories

### 👩‍🏫 **Trainer/Educator**

**Your Learning Path:**

1. `Learning` → Video Tutorials
2. `Get Started` → Quickstart Guides
3. `Support` → Office Hours recaps
4. `Learning & Community` → Video-to-Lesson Mapping

***

## 📊 Documentation Structure Overview

```
🏠 AgenticFlow Docs
│
├── 🚀 Get Started (START HERE)
│   ├── Your First 5 Minutes ⭐
│   ├── Choose Your Path
│   └── Platform Overview
│
├── 🤖 Core Features
│   ├── AI Agents (Build intelligent assistants)
│   ├── Visual Workflows (Automate processes)
│   └── Workforce (Multi-agent teams)
│
├── 📚 Learning
│   ├── Key Concepts
│   ├── Video Learning
│   └── Office Hours recaps
│
├── 🔗 Integrations
│   ├── 300+ No-Code Tools
│   └── MCP Protocol (10,000+ tools)
│
└── 🏢 Advanced
    ├── Enterprise Features
    ├── API Reference
    └── Troubleshooting
```

***

## 🔥 Most Popular Pages

1. [**Your First 5 Minutes**](/get-started/your-first-5-minutes) - Quick win
2. [**Agent Quickstart**](/get-started/agents-quickstart) - Build first agent
3. [**Workflow Quickstart**](/get-started/workflows-quickstart) - First automation
4. [**Choose Your Path**](/get-started/choose-your-path) - Role-based guide
5. [**Learning Hub**](/learn/02-learn) - Learning resources

***

## 💡 Pro Tips for Navigation

### 🎯 **Quick Wins First**

* Start with "Your First 5 Minutes" for immediate value
* Use templates instead of building from scratch
* Watch the 2-minute platform overview video

### 📈 **Progressive Learning**

* Follow the numbered steps in each quickstart
* Complete hands-on exercises before moving to advanced topics
* Join office hours for live Q\&A

### 🔍 **Finding What You Need**

* Use the search function for specific features
* Check the Support section for common questions
* Browse templates for your use case

### 🚀 **Accelerated Learning**

* If you have 1 hour: Complete all Quickstarts
* If you have 1 day: Complete the feature quickstarts
* If you have 1 week: Build an agent, workflow, and workforce from the quickstarts

***

## 🆘 Still Can't Find What You Need?

* **Search**: Use the search bar with keywords
* **Support**: Check [Support](/support/12-support)
* **Community**: Join [Discord](https://qra.ai/discord)
* **Support**: Email <support@agenticflow.ai>

***

## 📍 Navigation Breadcrumbs Example

**Building a Customer Service Agent:**

```
Home → Get Started → Choose Your Path → Customer Service Role
     → AI Agents → Agent Templates → Customer Service Template
     → Workforce → Team Templates → Customer Service Team
     → Deploy & Test
```

**Learning Workflow Automation:**

```
Home → Get Started → Your First 5 Minutes
     → Visual Workflows → Workflow Quickstart
     → Learning & Community → Video Learning → Workflow Tutorials
     → Build Your First Automation
```


# ChangeLog

This changelog tracks AgenticFlow product releases, Office Hours recaps, customer-facing fixes, model updates, workflow improvements, CLI updates, and platform reliability work.

Each release note is organized around:

* ✨ **Improvements** - feature, usability, integration, model, and workflow updates.
* 🐞 **Fixes** - bug fixes, reliability work, and stability improvements.
* 🎥 **Office Hours** - product walkthroughs, demos, and teaching material for builders.

The changelog is updated when an Office Hours release or shipped update is ready to document. Older Office Hours videos and release recaps are linked from the archive sections below and on the [AgenticFlow YouTube channel](https://www.youtube.com/@AgenticFlow/videos).

***

## Release Coverage

This public changelog covers AgenticFlow releases from **March 2024 through Office Hours #54**, including work across:

* Workflow run history, run detail accuracy, and retest routing.
* Agent chat stability, streaming failure recovery, file attachments, model selection, and Vision-capable model handling.
* Protected workflow and agent file uploads using temporary signed links.
* Trigger editing, scheduled agents, task visibility, and workspace memory retrieval.
* Workforce and MAS execution fixes, public workforce URLs, and multi-agent traceability.
* Marketplace, template download, template search, publication management, and mobile usability.
* MCP connections, custom headers, provider visibility, OAuth categories, and OpenAI-compatible provider management.
* AgenticFlow CLI, workflow/agent/workforce blueprints, marketplace catalog access, and desktop-agent integration.
* Ishi, AgenticFlow's first-party desktop AI agent, and the related AI Toolkit / skills ecosystem.
* Model/provider updates and deprecations across OpenAI-compatible providers, Claude, DeepSeek, Gemma, GLM, Qwen, Gemini, and other supported model surfaces.
* Early platform foundations, workflow nodes, chatflow publishing, model/version management, templates, data handling, scheduling, webhooks, MCP, and Copilot updates from the legacy release archive.

***

## Latest Release

### [18 Aug 2026 - Office Hour #54: New AI Models, Safer Actions & Easier Agent Building](/changelog/office-hour-54-new-models-safer-actions-and-easier-agent-building)

This release expands the model catalog with six new choices and improves deletion safety, MCP guidance, navigation, accessibility, and builder clarity.

**Highlights**

* Gemini 3.7 Flash, Grok 4.6, Muse Spark 1.2, Qwen 3.8 Max, DeepSeek V4 Pro 0813, and Qwen3.8-27B are now available.
* Destructive actions across workflows, AI Drive, MCP, Workforces, and connections now use explicit confirmation.
* MCP status, navigation, form labels, sharing controls, and keyboard access are clearer.
* The release includes six copy-ready AgenticFlow CLI workflow blueprint prompts.

[Read the full Office Hour #54 notes](/changelog/office-hour-54-new-models-safer-actions-and-easier-agent-building)

***

### [04 Aug 2026 - Office Hour #53: DeepSeek V4 Flash 0731 & Agent Reliability Fixes](/changelog/office-hour-53-deepseek-v4-flash-and-agent-reliability-fixes)

This release adds DeepSeek V4 Flash 0731 and resolves reliability issues affecting project deletion, API-created agent visibility, and agent avatar delivery.

**Highlights**

* DeepSeek V4 Flash 0731 is available through PixelML and AgenticFlow.
* The Projects page prevents deletion of the only remaining project in normal workspace UI flows.
* Agent API writes and AI Studio now share the same four-message limit for suggested starter messages.
* New avatar uploads use durable delivery URLs instead of expiring presigned URLs.
* Broken avatar references fall back to the default agent icon across editor, chat, and embedded surfaces.

[Read the full Office Hour #53 notes](/changelog/office-hour-53-deepseek-v4-flash-and-agent-reliability-fixes)

***

## Recent Release Themes

### Reliability, Debugging & Supportability

Recent releases improved agent chat stability, streaming failure recovery, workflow run detail accuracy, trigger provenance, workspace history routing, memory retrieval, trace visibility, task status, file attachment handling, and long-running agent defaults.

Key releases:

* [Office Hours #54](/changelog/office-hour-54-new-models-safer-actions-and-easier-agent-building)
* [Office Hours #53](/changelog/office-hour-53-deepseek-v4-flash-and-agent-reliability-fixes)
* [Office Hours #52](/changelog/office-hour-52-ai-drive-mcp-and-model-lifecycle-updates)
* [Office Hours #50](/changelog/office-hour-50-public-routes-and-model-updates)
* [Office Hours #49](/changelog/office-hour-49-safer-agent-chat-protected-uploads-and-model-cleanup)
* [Office Hours #48](/changelog/office-hour-48-trigger-reliability-memory-and-ui-stability)
* [Office Hours #45](/changelog/office-hour-45-core-stability-traceability-and-bug-fixes)
* [Office Hours #37](/changelog/office-hour-37-workflow-ask-ai-member-page-and-chatv2-fixes)
* [Office Hours #36](/changelog/office-hour-36-tasks-page-and-workflow-fixes)

### Agent, Workflow & Workforce Builder Experience

AgenticFlow continued improving the surfaces builders use every day: workflow inputs, shared workflows, templates, agent publishing, sub-agents, MAS templates, marketplace clone flows, workforce endpoints, and versioning workflows.

Key releases:

* [Office Hours #54](/changelog/office-hour-54-new-models-safer-actions-and-easier-agent-building)
* [Office Hours #53](/changelog/office-hour-53-deepseek-v4-flash-and-agent-reliability-fixes)
* [Office Hours #52](/changelog/office-hour-52-ai-drive-mcp-and-model-lifecycle-updates)
* [Office Hours #51](/changelog/office-hour-51-claude-model-updates)
* [Office Hours #46](/changelog/office-hour-46-recap-and-workflow-blueprint-prompts)
* [Office Hours #45](/changelog/office-hour-45-core-stability-traceability-and-bug-fixes)
* [Office Hours #42](/changelog/office-hour-42-nano-banana-2-and-agent-knowledge-ui)
* [Office Hours #40](/changelog/office-hour-40-published-agent-status-fix)

### Model Selection, Providers & Attachments

Model and provider work included deprecated model handling in chat, Gemini 3.5 Flash on the PixelML Provider, the redesigned Model Selector, inline token limits, Vision/Reasoning capability badges, JSON attachments, OpenAI-compatible provider management, OAuth connection visibility, and multiple model/provider additions.

Key releases:

* [Office Hours #54](/changelog/office-hour-54-new-models-safer-actions-and-easier-agent-building)
* [Office Hours #53](/changelog/office-hour-53-deepseek-v4-flash-and-agent-reliability-fixes)
* [Office Hours #52](/changelog/office-hour-52-ai-drive-mcp-and-model-lifecycle-updates)
* [Office Hours #51](/changelog/office-hour-51-claude-model-updates)
* [Office Hours #50](/changelog/office-hour-50-public-routes-and-model-updates)
* [Office Hours #49](/changelog/office-hour-49-safer-agent-chat-protected-uploads-and-model-cleanup)
* [Office Hours #48](/changelog/office-hour-48-trigger-reliability-memory-and-ui-stability)
* [Office Hours #47](/changelog/office-hour-47-model-selector-and-chat-upgrades)
* [Office Hours #46](/changelog/office-hour-46-recap-and-workflow-blueprint-prompts)
* [Office Hours #44](/changelog/office-hour-44-workflow-output-model-updates-and-ui-fixes)
* [Office Hours #41](/changelog/office-hour-41-gemini-3-1-pro-and-sub-agent-settings)

### CLI, Ishi & Desktop-Agent Workflows

The AgenticFlow CLI, Ishi, desktop-agent workflows, MCP tool access, skills, and AI Toolkit routing are part of the same builder ecosystem. These releases document the CLI composition ladder, deployable blueprints, marketplace catalog access, and first-party desktop-agent workflows.

Key releases:

* [Office Hours #51](/changelog/office-hour-51-claude-model-updates)
* [Office Hours #46](/changelog/office-hour-46-recap-and-workflow-blueprint-prompts)
* [Office Hours #45](/changelog/office-hour-45-core-stability-traceability-and-bug-fixes)
* [Office Hours #43](/changelog/office-hour-43-ishi-sub-agent-and-skills-navigation)
* [Office Hours #35](/changelog/office-hour-35-debug-tray-and-ishi-launch)
* [Office Hours #34](/changelog/office-hour-34-desktop-ai-assistant-layer)

***

## Release Index

| Date               | Office Hours   | Focus                                                                                                                                       | Full notes                                                                                                        |
| ------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| 18 Aug 2026        | #54            | New models, safer delete actions, clearer MCP guidance, more predictable navigation, accessibility, and builder controls                    | [Read notes](/changelog/office-hour-54-new-models-safer-actions-and-easier-agent-building)                        |
| 04 Aug 2026        | #53            | DeepSeek V4 Flash 0731, last-project UI protection, suggested-message API consistency, and durable agent avatars                            | [Read notes](/changelog/office-hour-53-deepseek-v4-flash-and-agent-reliability-fixes)                             |
| 21 Jul 2026        | #52            | AI Drive folder ZIP downloads, MCP header/OAuth reliability, GPT-5.6 Sol and Kimi K3, OpenAI deprecations, and Straico shutdown             | [Read notes](/changelog/office-hour-52-ai-drive-mcp-and-model-lifecycle-updates)                                  |
| 07 Jul 2026        | #51            | Claude model additions plus AgenticFlow CLI v1.10.7, `autonomous-desk`, MAS graph playbook, and expanded blueprint catalog                  | [Read notes](/changelog/office-hour-51-claude-model-updates)                                                      |
| 23 Jun 2026        | #50            | MCP reliability, route stability, accessibility improvements, and model additions                                                           | [Read notes](/changelog/office-hour-50-public-routes-and-model-updates)                                           |
| 09 Jun 2026        | #49            | Agent chat stability, streaming failure recovery, protected uploads, deprecated model handling, URL to Markdown and Web Scraping node fixes | [Read notes](/changelog/office-hour-49-safer-agent-chat-protected-uploads-and-model-cleanup)                      |
| 26 May 2026        | #48            | Gemini 3.5 Flash, workflow debugging accuracy, trigger reliability, memory retrieval, mobile Marketplace usability                          | [Read notes](/changelog/office-hour-48-trigger-reliability-memory-and-ui-stability)                               |
| 12 May 2026        | #47            | Model Selector redesign, chat attachments, JSON files, Telegram publishing fix, teaching prompts                                            | [Read notes](/changelog/office-hour-47-model-selector-and-chat-upgrades)                                          |
| 28 Apr 2026        | #46            | Frontier model updates, timezone consistency, MCP auth, Composio deprecation, workflow blueprint prompts                                    | [Read notes](/changelog/office-hour-46-recap-and-workflow-blueprint-prompts)                                      |
| 14 Apr 2026        | #45            | Core stability, traceability, MAS/workforce fixes, API-key paths, CLI improvements                                                          | [Read notes](/changelog/office-hour-45-core-stability-traceability-and-bug-fixes)                                 |
| 31 Mar 2026        | #44            | Workflow output downloads, GLM/Qwen models, profile/iPad/template UI fixes                                                                  | [Read notes](/changelog/office-hour-44-workflow-output-model-updates-and-ui-fixes)                                |
| 17 Mar 2026        | #43            | Ishi sub-agent updates, skills library, sidebar navigation                                                                                  | [Read notes](/changelog/office-hour-43-ishi-sub-agent-and-skills-navigation)                                      |
| 10 Mar 2026        | #42            | Nano Banana 2, Agent Knowledge UI, publish/trigger/Web Retrieval fixes                                                                      | [Read notes](/changelog/office-hour-42-nano-banana-2-and-agent-knowledge-ui)                                      |
| 03 Mar 2026        | #41            | Gemini 3.1 Pro, sub-agent settings, chatbot logo customization, shared workflow upload fix                                                  | [Read notes](/changelog/office-hour-41-gemini-3-1-pro-and-sub-agent-settings)                                     |
| 24 Feb 2026        | #40            | Published agent status regression fix                                                                                                       | [Read notes](/changelog/office-hour-40-published-agent-status-fix)                                                |
| 10 Feb 2026        | #39            | Office Hours recording                                                                                                                      | [Read notes](/changelog/office-hour-39)                                                                           |
| 02 Feb 2026        | #38            | System Prompt editor toolbar and preview formatting fixes                                                                                   | [Read notes](/changelog/office-hour-38-system-prompt-editor-fixes)                                                |
| 27 Jan 2026        | #37            | Workflow audio transcription, Ask AI node, Member page, ChatV2 image upload fixes                                                           | [Read notes](/changelog/office-hour-37-workflow-ask-ai-member-page-and-chatv2-fixes)                              |
| 20 Jan 2026        | #36            | Tasks page, chatbot setup, text extraction, templates, PDF export, web search fixes                                                         | [Read notes](/changelog/office-hour-36-tasks-page-and-workflow-fixes)                                             |
| 13 Jan 2026        | #35            | Debug Tray, Ishi launch, credits, MCP integration, task/versioning roadmap                                                                  | [Read notes](/changelog/office-hour-35-debug-tray-and-ishi-launch)                                                |
| 06 Jan 2026        | #34            | Desktop AI assistant layer, Agent Skills, MCP server integration, Skill Creator                                                             | [Read notes](/changelog/office-hour-34-desktop-ai-assistant-layer)                                                |
| 30 Dec 2025        | #33            | Desktop AI architect preview, voice-to-infrastructure, robotics concepts                                                                    | [Read notes](/changelog/office-hour-33-desktop-ai-architect-preview)                                              |
| 23 Dec 2025        | #32            | Model comparison, concept video workflows, UGC image feedback templates                                                                     | [Read notes](/changelog/office-hour-32-model-comparison-and-creative-workflow-updates)                            |
| 16 Dec 2025        | #31            | DeepSeek, video understanding, image generation using credits, Copilot Ask Mode, Chat V2 beta                                               | [Read notes](/changelog/office-hour-31-deepseek-video-understanding-and-image-generation)                         |
| 09 Dec 2025        | #30            | Marketplace 2.0, publication management, Claude Opus update, Robomotion MCP, build sessions                                                 | [Read notes](/changelog/office-hour-30-marketplace-2-0-and-model-updates)                                         |
| 02 Dec 2025        | #29            | Nano Banana Pro, RoboMotion MCP, Tasks UI preview, GLM 4.5 Air, AWS Qualified Badge                                                         | [Read notes](/changelog/office-hour-29-black-friday-recap-and-nano-banana-pro)                                    |
| November 22, 2025  | #28            | GPT-5.1 Series + Gemini 3 Pro Preview + Skills Deep Dive                                                                                    | [Read notes](/changelog/office-hour-28-gpt-5-1-series-gemini-3-pro-preview-skills-deep-dive)                      |
| November 11, 2025  | #27            | Kimi K2 Thinking Model + Code Execution + Agent API Launch                                                                                  | [Read notes](/changelog/office-hour-27-kimi-k2-thinking-model-code-execution-agent-api-launch)                    |
| November 4, 2025   | #26            | Designer Agent + Video Agent + Let AI Work While You Sleep (MCP)                                                                            | [Read notes](/changelog/office-hour-26-designer-agent-video-agent-let-ai-work-while-you-sleep-mcp)                |
| October 28, 2025   | #25            | Veo 3.1 + New Plugin System + New Skill System                                                                                              | [Read notes](/changelog/office-hour-25-veo-3-1-new-plugin-system-new-skill-system)                                |
| October 21, 2025   | #24            | AWS Select Partner + Claude Haiku 4.5 + Skills Launch                                                                                       | [Read notes](/changelog/office-hour-24-aws-select-partner-claude-haiku-4-5-skills-launch)                         |
| October 14, 2025   | #23            | MCP OAuth Upgrade + Project-Level Isolation + Memory System                                                                                 | [Read notes](/changelog/office-hour-23-mcp-oauth-upgrade-project-level-isolation-memory-system)                   |
| October 7, 2025    | #22            | OpenAI Dev Day Special: Apps in ChatGPT + Sora 2 & SeeDance 1.0                                                                             | [Read notes](/changelog/office-hour-22-openai-dev-day-special-apps-in-chatgpt-sora-2-seedance-1-0)                |
| September 30, 2025 | #21            | Claude Sonnet 4.5 Deep Dive + DeepSeek 3.2 & GLM 4.5                                                                                        | [Read notes](/changelog/office-hour-21-claude-sonnet-4-5-deep-dive-deepseek-3-2-glm-4-5)                          |
| September 23, 2025 | #20            | AgenticFlow MCP in ChatGPT + Google URL Context (Gemini 2.5)                                                                                | [Read notes](/changelog/office-hour-20-agenticflow-mcp-in-chatgpt-google-url-context-gemini-2-5)                  |
| September 16, 2025 | #19            | ChatGPT MCP Copilot + MAS Templates & UGC Art Generator                                                                                     | [Read notes](/changelog/office-hour-19-chatgpt-mcp-copilot-mas-templates-ugc-art-generator)                       |
| September 9, 2025  | #18            | Veo 3 + Multi-Agent Video Generator + MAS Embeds & Express Designer                                                                         | [Read notes](/changelog/office-hour-18-veo-3-multi-agent-video-generator-mas-embeds-express-designer)             |
| September 2, 2025  | #17            | Nano Banana (Gemini 2.5 Flash Image) + Virtual Try-On + 16:9 Trick                                                                          | [Read notes](/changelog/office-hour-17-nano-banana-gemini-2-5-flash-image-virtual-try-on-16-9-trick)              |
| August 26, 2025    | #16            | Discord Bot Integration + Visual AI Agents + Qualcomm Win                                                                                   | [Read notes](/changelog/office-hour-16-discord-bot-integration-visual-ai-agents-qualcomm-win)                     |
| August 19, 2025    | #15            | Discord Bot Agent NOW LIVE + Multi-Agent System V2 + Chrome Extension Preview                                                               | [Read notes](/changelog/office-hour-15-discord-bot-agent-now-live-multi-agent-system-v2-chrome-extension-preview) |
| August 12, 2025    | #14            | GPT-5 Nano NOW LIVE + Multi-Agent System Demo                                                                                               | [Read notes](/changelog/office-hour-14-gpt-5-nano-now-live-multi-agent-system-demo)                               |
| August 5, 2025     | #13            | SOTA OCR with Mistral + MAS V2 UI Preview & Deep Research Templates                                                                         | [Read notes](/changelog/office-hour-13-sota-ocr-with-mistral-mas-v2-ui-preview-deep-research-templates)           |
| July 29, 2025      | #12            | AgenticFlow MCP Integration + Multi-Agent Teams + 10,000+ Tools                                                                             | [Read notes](/changelog/office-hour-12-agenticflow-mcp-integration-multi-agent-teams-10-000-tools)                |
| July 22, 2025      | #11            | AgenticFlow MCP Server + Autonomous Workflow Creation                                                                                       | [Read notes](/changelog/office-hour-11-agenticflow-mcp-server-autonomous-workflow-creation)                       |
| July 15, 2025      | #10            | Kimi K2 1 TRILLION Parameter Open Model + n8n Agent & Multi-Agent Progress                                                                  | [Read notes](/changelog/office-hour-10-kimi-k2-1-trillion-parameter-open-model-n8n-agent-multi-agent-progress)    |
| May-Jun 2025       | #1-#7          | Early Office Hours video archive covering MCP, embeds, webhooks, scheduling, Copilot, and multi-agent previews                              | [Read notes](/changelog/office-hours-01-07-early-video-archive)                                                   |
| Mar 2024-Jun 2025  | Legacy updates | Core foundations, workflow nodes, templates, media/data integrations, chatflow, publishing, models, credits, and reliability updates        | [Read notes](/changelog/legacy-product-updates-2024-2025)                                                         |

***

## Historical Archive

The older archive keeps the public operating record visible without relying on collapsed release blocks:

* [Office Hours #28](/changelog/office-hour-28-gpt-5-1-series-gemini-3-pro-preview-skills-deep-dive) through [Office Hours #10](/changelog/office-hour-10-kimi-k2-1-trillion-parameter-open-model-n8n-agent-multi-agent-progress) preserve the 2025 model, MCP, workflow, MAS, template, Discord bot, video, and skills updates.
* [Office Hours #1-#7](/changelog/office-hours-01-07-early-video-archive) links to the early video tutorial archive for MCP, embeds, webhooks, scheduling, Copilot, and multi-agent previews.
* [Legacy Product Updates: March 2024 - June 2025](/changelog/legacy-product-updates-2024-2025) summarizes the platform foundation work before the current Office Hours release-note format.

***

## Teaching & Prompt Packs

Several Office Hours include copy-ready prompt packs and walkthroughs for builders:

* [Office Hours #54](/changelog/office-hour-54-new-models-safer-actions-and-easier-agent-building) includes six AgenticFlow CLI workflow blueprint prompts selected from current use-case issues.
* [Office Hours #47](/changelog/office-hour-47-model-selector-and-chat-upgrades) includes Model Selector usage guidance and workflow blueprint prompts.
* [Office Hours #46](/changelog/office-hour-46-recap-and-workflow-blueprint-prompts) includes six AgenticFlow CLI workflow blueprint prompts for practical business automation demos.
* [Office Hours #28](/changelog/office-hour-28-gpt-5-1-series-gemini-3-pro-preview-skills-deep-dive) includes a skills deep dive and comparison of skills, system prompts, and MCP.

***

## Support

For reproducible product issues, email <support@agenticflow.ai> with workspace context, affected agent/workflow/template details, screenshots or screen recording, and steps to reproduce.


# Office Hour #54: New AI Models, Safer Actions & Easier Agent Building

### Quick Recap

Office Hour #54 expands the model catalog and makes everyday work across AgenticFlow safer, clearer, and easier to complete.

This release includes:

* Six new model choices: Gemini 3.7 Flash, Grok 4.6, Muse Spark 1.2, Qwen 3.8 Max, DeepSeek V4 Pro 0813, and Qwen3.8-27B
* Confirmation before deleting workflows, AI Drive items, MCP servers, Workforces, and connections
* Clearer MCP connection and tool-availability guidance
* More reliable navigation across Library, Datasets, Marketplace, and onboarding
* Easier keyboard and assistive-technology use across agent, workflow, workforce, project, connection, and sharing screens
* Clearer labels and action names when creating, configuring, sharing, and publishing work

***

### What Changed & Why

#### 1. Six New Models Added to the Catalog

The Model Selector now includes six additional choices:

* **Gemini 3.7 Flash**
* **Grok 4.6**
* **Muse Spark 1.2**
* **Qwen 3.8 Max**
* **DeepSeek V4 Pro 0813**
* **Qwen3.8-27B**

These additions give builders more flexibility when choosing a model for agents, workflows, content creation, research, and other day-to-day tasks. You can compare them with your existing models to find the response style, speed, and task fit that works best for each use case.

As with any model change, test important live workflows before switching. Responses can vary by model even when the prompt and tools stay the same.

<figure><img src="/files/qTS8T8cZB67UDgrbgThh" alt="AgenticFlow model selector showing Grok 4.6"><figcaption><p>Grok 4.6 appears in the live model selector with its provider grouping and input/output limits.</p></figcaption></figure>

<figure><img src="/files/6famR1D6esCVGa1zgs7z" alt="AgenticFlow model selector showing Qwen 3.8 Max and Qwen 3.8 27B"><figcaption><p>Qwen 3.8 Max and Qwen 3.8 27B are listed with their model limits.</p></figcaption></figure>

<figure><img src="/files/5DamA3yfg807OEiMTHxx" alt="AgenticFlow model selector showing Gemini 3.7 Flash and DeepSeek V4 Pro 0813"><figcaption><p>Gemini 3.7 Flash and DeepSeek V4 Pro 0813 appear in the live catalog.</p></figcaption></figure>

<figure><img src="/files/mTLU2GICh2E1c7qzbMY9" alt="AgenticFlow model selector showing DeepSeek V4 Pro 0813 and Muse Spark 1.2"><figcaption><p>DeepSeek V4 Pro 0813 and Muse Spark 1.2 show their published input/output limits.</p></figcaption></figure>

### Model research: choose by job, not by leaderboard

The six additions span three different deployment choices: hosted frontier models, hosted models co-trained with an agent harness, and an open-weight model that can run on a local workstation. The useful question is not “which model is #1?” but “which model gives this workflow the required quality, latency, cost, data boundary, and tool behavior?”

The table below is a practical starting point. It combines the model catalog in AgenticFlow with independent benchmark snapshots and publisher documentation. Re-test any production workflow after changing models because a benchmark score does not guarantee the same result on your prompt, tools, or data.

| Model                    | Best first job                                                                           | Why it is interesting                                                                                                                                                                                                                                                                                | Watch-out                                                                                                                                                        |
| ------------------------ | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Gemini 3.7 Flash**     | High-volume multimodal extraction, classification, and fast workflow steps               | Artificial Analysis reports a high-effort Intelligence Index of 56, about 340 output tokens/second, a 1M-token context, and lower measured cost per task than Gemini 3.6 Flash. See the [AA analysis](https://artificialanalysis.ai/articles/gemini-3-7-time-frontier).                              | Speed and price depend on effort level, cache, and provider route. Measure quality on your own documents before making it the default.                           |
| **Grok 4.6**             | Research, long-running coding, and tasks where strong tool use matters                   | Artificial Analysis reports an Intelligence Index of 61, Terminal-Bench 2.1 at 88.4%, and a 500K context window. It is also #5 in the Arena Code/WebDev snapshot below. See the [AA analysis](https://artificialanalysis.ai/articles/grok-4-6-benchmarks-and-analysis).                              | It is hosted rather than local. Treat live-information behavior, data handling, and cost as part of the design, not as afterthoughts.                            |
| **Muse Spark 1.2**       | Repository work, visual-to-code tasks, and long-horizon coding with persistent subagents | The Muse product is paired with a coding harness designed for long tool sequences. It reaches #2 in Arena’s overall lab snapshot and #22 in the Code/WebDev snapshot below.                                                                                                                          | Model and harness behavior are coupled. A good result in Muse Code may not reproduce with a plain chat completion.                                               |
| **Qwen 3.8 Max**         | Hosted coding, analysis, and multimodal workflows that need a long context               | QwenCloud lists 1M context, tool use, structured output, and a 2T-class mixture-of-experts model; Arena Code ranks it #3 in the dated snapshot below.                                                                                                                                                | Vendor-reported model size and benchmark results are not the same as guaranteed application quality. Check current pricing and limits in the provider console.   |
| **DeepSeek V4 Pro 0813** | Text/code/tool workflows where open weights, long context, or a lower-cost route matters | The DeepSeek API exposes OpenAI-compatible and Anthropic-compatible interfaces, and the family is documented as open-weight/MIT with a 1M context route. Arena Code ranks the 0813 high-effort variant #10 in the snapshot below. See the [DeepSeek updates](https://api-docs.deepseek.com/updates). | Provider routes can expose different revisions, effort levels, and prices. Confirm the exact model ID and evaluate tool-call reliability, not just text quality. |
| **Qwen3.8-27B**          | Private/local coding, knowledge work, and repeatable experiments on a workstation        | A 27B open-weight model is unusually capable for its size. Unsloth reports that a 4-bit build can fit in roughly 17–19GB of memory, putting a useful local experiment within reach of a 24GB-class GPU or Apple-silicon machine. See the [Unsloth guide](https://unsloth.ai/docs/models/qwen3.8).    | A quantized weight-file fit is not the same as a usable 1M context. Leave headroom for KV cache, the operating system, tools, and your runtime.                  |

### Reading the Artificial Analysis view

Artificial Analysis’ Intelligence Index is a composite, not a single test. Version 4.1 weights agentic and knowledge-work evaluations such as GDPval-AA v2, Terminal-Bench 2.1, τ³-Bench Banking, Humanity’s Last Exam, GPQA, and coding/science tasks. The [AA methodology update](https://artificialanalysis.ai/articles/artificial-analysis-intelligence-index-v4-1) explains the current mix and why scores can move when the index changes.

The supplied screenshot is useful as a “capability per parameter” conversation starter. It is a dated view of the Artificial Analysis chart, not a live guarantee. In that view, Qwen3.8-27B sits around the low-50s while the much larger Qwen3.8 Max sits near the frontier. That is the important customer insight: a small open model can be unusually attractive when privacy, local control, or predictable cost matters, even when a larger hosted model remains stronger on some tasks.

<figure><img src="/files/PPCNrGJRdZ7t24k2ZTgn" alt="Artificial Analysis Intelligence Index versus total parameters chart supplied for Office Hour 54"><figcaption><p>Artificial Analysis Intelligence Index versus total parameters, supplied snapshot. Use it to discuss efficiency and the Pareto frontier; verify current values in the <a href="https://artificialanalysis.ai/models">live model explorer</a> before making a procurement decision.</p></figcaption></figure>

#### The Qwen3.8-27B versus Opus 4.6 headline, correctly framed

“Qwen3.8-27B beats Opus 4.6” can be true for a selected coding row and still be false as a general statement. In the Arena Code/WebDev snapshot dated 15 August 2026, Qwen3.8 Max and Grok 4.6 rank above Opus 4.6 high; Qwen3.8-27B is not listed in that snapshot. The Artificial Analysis/community view places Qwen3.8-27B around 52, which is remarkable for a 27B model, but it is not evidence that it wins every benchmark, every tool loop, or every customer workload.

Use the claim this way in a customer conversation: **“Qwen3.8-27B is a frontier-like local option for its size; validate it against your own holdout before replacing a hosted frontier model.”**

### Arena snapshots: preference, code, and agent behavior are different signals

Arena scores come from human or task-level comparisons and are best read as a snapshot of preference or practical performance. They are not interchangeable with Artificial Analysis’ composite index. The rows below are deliberately dated so the page does not imply that a leaderboard is static.

<figure><img src="/files/3JRlBoV4UPAorIZriRVB" alt="Arena Code WebDev snapshot comparing six Office Hour 54 models with Opus 4.6"><figcaption><p>Arena Code/WebDev overall snapshot from 15 August 2026. Scores are preliminary and change as votes accumulate; <a href="https://arena.ai/leaderboard/code">open the live Arena leaderboard</a> before quoting a rank.</p></figcaption></figure>

Selected Arena Code/WebDev rows from that snapshot:

| Rank | Model                       | Arena score | Price shown by Arena                     |
| ---: | --------------------------- | ----------: | ---------------------------------------- |
|    3 | Qwen3.8 Max                 |   1667 ± 13 | $2 / $6 per 1M input/output tokens       |
|    5 | Grok 4.6 high               |   1631 ± 17 | $2 / $6 per 1M input/output tokens       |
|    8 | Gemini 3.7 Flash high       |   1587 ± 13 | $0.75 / $3.57 per 1M input/output tokens |
|   10 | DeepSeek V4 Pro high (0813) |   1584 ± 14 | $1.32 / $3.96 per 1M input/output tokens |
|   16 | Opus 4.6 high               |    1545 ± 6 | Provider price varies                    |
|   22 | Muse Spark 1.2 xHigh        |   1535 ± 14 | $1.25 / $4.25 per 1M input/output tokens |

The separate [Agent Arena leaderboard](https://arena.ai/leaderboard/agent) is a better lens for tool loops and steerability, but it does not contain every model in this release. In the 13 August 2026 snapshot, Qwen3.8 Max is #11 with 12.54% confirmed success and 0.11% tool hallucination, Gemini 3.7 Flash high is #21 with 9.85% confirmed success and 1.18% tool hallucination, and DeepSeek V4 Pro is #28 with 2.16% confirmed success and 0.35% tool hallucination. The absence of Grok 4.6, Muse Spark 1.2, or Qwen3.8-27B from that table means “not covered in this snapshot,” not “failed.”

### Qwen3.8-27B: a local frontier experiment on a practical budget

The most actionable customer story in this release is not a leaderboard screenshot. It is the ability to run a strong open model close to the data:

1. **Start with a quantized build.** Unsloth’s current guidance puts a 4-bit Qwen3.8-27B build in the roughly 17–19GB range. A 24GB GPU or a modern Apple-silicon system with sufficient unified memory gives safer headroom than a machine that only meets the weight-file minimum.
2. **Budget for the whole loop.** KV cache, context length, tool schemas, retrieval results, the runtime, and the operating system all compete for memory. “Fits in 17GB” does not mean “runs a 1M-token agent at full speed.”
3. **Use a bounded first demo.** Point the model at a private repository or document set, let it propose a patch or answer with citations, and require human approval before any external write. This demonstrates privacy and cost without pretending that local inference is automatically autonomous.
4. **Measure the customer’s outcome.** Record task success, review edits, latency, tokens, memory pressure, and failure recovery. Compare those numbers with the hosted model that the customer would otherwise buy.

<figure><img src="/files/HByEfsIzjKXR7V2Lcv4M" alt="Diagram showing a private data workflow using Qwen3.8-27B locally with a quantized runtime and approval gate"><figcaption><p>Reference architecture for a local Qwen3.8-27B pilot. The memory figure is a quantized-weight estimate; measure context, throughput, and tool reliability on the target machine.</p></figcaption></figure>

An illustrative $2,000 workstation can therefore be a compelling pilot budget, but it is not a promise of a particular build, GPU, throughput, or total cost of ownership. Hardware prices, quantization formats, and context requirements change quickly; quote a current configuration only after measuring the customer’s workload.

### DeepSeek Harness: the new layer underneath the model

[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) is a developer-preview harness, not a seventh model in the catalog. Its design treats the model, tools, context, sessions, and sandbox as replaceable plugins. The official [DeepSeek Harness site](https://deepseek.com/harness/) describes modes for standard work, coding, minimal interaction, and creator-style flows; the repository documents an append-only session log that supports replay, resume, fork, and search.

That separation is valuable for customers because it makes the experiment reproducible:

* **Model test:** keep the prompt, tools, and task fixed while comparing Gemini, Grok, Qwen, Muse, and DeepSeek.
* **Harness test:** keep the model fixed while comparing session memory, tool permissions, retries, sandboxing, and approval gates.
* **Operations test:** keep both fixed while measuring cost per successful task, time to recovery, trace completeness, and data residency.

DeepSeek Harness is still a preview and may change incompatibly. It should be treated as an interoperability and reproducibility idea to learn from, not as a guarantee that every AgenticFlow workflow or provider route will behave the same way.

### What people are trying in the open model ecosystem

Social posts are useful for finding experiments, but they are anecdotes rather than controlled benchmarks. These searches are intentionally linked so readers can inspect the original thread and date:

* **Local coding:** community posts around [Qwen3.8-27B](https://x.com/search?q=%22Qwen3.8-27B%22\&src=typed_query) focus on 4-bit quantization, 24GB-class machines, and private repository work. Treat “runs on my machine” as a starting point, then reproduce it with the customer’s context and tools.
* **Long-horizon coding:** [Muse Spark 1.2 discussions](https://x.com/search?q=%22Muse%20Spark%201.2%22\&src=typed_query) highlight persistent subagents, visual-to-code work, and long tool sequences. The interesting idea is the harness plus the model, not just the model name.
* **Voice and parallel agents:** [Grok 4.6 agent threads](https://x.com/search?q=%22Grok%204.6%22%20agent\&src=typed_query) show people trying voice prompts, parallel research, and coding loops. Verify what was actually executed before presenting a demo as an automation claim.
* **Reproducible sessions:** [DeepSeek Harness threads](https://x.com/search?q=%22DeepSeek%20Harness%22\&src=typed_query) are exploring replayable logs, plugins, and local sandboxes. This is a useful design pattern for auditability even when the underlying model changes.

### Customer value: turn a big model release into a smaller buying decision

For a customer, the release is valuable when it reduces risk or cycle time—not when it adds six names to a selector. A practical pilot can be designed in one afternoon:

| Step                     | Customer question                                                                 | Evidence to keep                                                  |
| ------------------------ | --------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| 1. Choose the lane       | Is the priority speed, frontier quality, local privacy, or long-horizon tool use? | One sentence naming the workload and data boundary                |
| 2. Build a holdout       | What five to ten real tasks represent the work?                                   | Inputs, expected outputs, and a review rubric                     |
| 3. Run two routes        | What changes between hosted and local execution?                                  | Quality, latency, token use, memory, and cost per successful task |
| 4. Add the safety gate   | Which actions require confirmation or a draft-before-send step?                   | Tool permissions, approval screenshots, and failure traces        |
| 5. Ship the smallest win | Can one workflow save time without claiming an external action occurred?          | Before/after time, acceptance rate, rollback path, and owner      |

The release’s safer delete confirmations, clearer MCP status, and better form labels make this evaluation easier to operate. The model expansion then gives the customer a controlled choice: fast multimodal work with Gemini, frontier hosted work with Grok or Qwen Max, harness-led long-horizon work with Muse, open-weight text/code work with DeepSeek, or a private Qwen3.8-27B pilot close to the data.

#### 2. Safer Delete Actions Across the Workspace

Deleting important workspace items now includes a clear confirmation step in more places.

Before removal, AgenticFlow asks you to confirm when deleting:

* A workflow
* A file or folder in AI Drive
* A connected MCP server
* A Workforce
* A saved connection

The confirmation identifies what will be removed, helping prevent accidental clicks while keeping the final decision with the user.

<figure><img src="/files/E735MVJeSJ2QeAvbNVwk" alt="MCP connection list showing the Delete action in an item menu"><figcaption><p>A connection item exposes Delete as an explicit action before the confirmation step.</p></figcaption></figure>

Dataset actions have also been improved so choosing **Delete** opens the expected confirmation instead of taking you to the dataset details page.

#### 3. Clearer MCP and Connection Guidance

MCP pages now give a more accurate picture of whether a server is ready to use.

If a connection needs attention or its tools are not currently available, AgenticFlow now shows clearer guidance about the next step and tool availability.

<figure><img src="/files/1uN2RmtlgKBYQicwhYzu" alt="AgenticFlow MCP client connection list"><figcaption><p>The MCP client connection page groups saved servers in one place and keeps the available actions visible.</p></figcaption></figure>

Additional connection improvements include:

* Clearer connection-method and sign-in choices when adding a custom MCP server
* Better identification of connected servers and their available tools
* A clearer distinction between connection status and available actions
* More focused next-step actions on the OpenAI-compatible provider setup page

These changes make it easier to understand whether an integration is ready before attaching it to an agent or workflow.

#### 4. More Predictable Creation and Navigation

Several journeys now take users directly to the intended destination:

* **Library:** Selecting **Create resource** now opens the resource editor correctly, including when the create page is opened directly.
* **Marketplace:** Selecting **View all** for Multi-Agent templates keeps the Multi-Agent category active.
* **Welcome:** The signed-in **Deploy your agent** button now starts the Telegram setup when needed and continues into onboarding after setup.
* **Datasets:** Delete actions stay within the expected confirmation journey.
* **OpenAI-compatible providers:** The setup screen now presents only useful next actions.

These updates reduce dead ends and make common setup paths feel more consistent.

#### 5. Easier Agent and Workflow Building

Forms and controls across the builders now explain their purpose more clearly, including when used with a keyboard or screen reader.

Improvements cover:

* Workflow run inputs and required fields
* Workflow and agent schedule settings
* Workflow and agent variables
* Agent webhook settings
* Image generation options such as model, prompt, quality, aspect ratio, steps, and connection
* API key creation
* Workspace member invitations and project member roles
* AI Drive folder creation
* Bulk-run table creation
* Telegram bot setup

Visible labels now stay connected to the field they describe, and selection controls provide clearer context than the selected value alone. This makes complex forms easier to scan and reduces uncertainty when moving between fields.

<figure><img src="/files/o4zTturTf0U6dQzzDbov" alt="AgenticFlow agent editor showing named capability and builder controls"><figcaption><p>The agent editor presents named capability, knowledge, memory, and chat-experience controls as scannable rows.</p></figcaption></figure>

#### 6. Clearer Sharing, Publishing, and Chat Controls

AgenticFlow now gives similar actions distinct, descriptive names so users can tell them apart more easily.

Updates include:

* Workflow sharing options that clearly identify what each switch controls
* Agent settings switches with clearer names and selected states
* Agent publish visibility that is easier to identify
* Platform-specific names for each **Configure** action on the publish screen
* Template **Duplicate** actions that include the template name
* Agent version and chat-history actions that are easier to recognize
* Agent sharing actions that work with both keyboard and mouse input
* Clearly identified message and send controls in agent chat
* More usable Workforce publishing and template-cloning choices

The create-app flow also now communicates which app type is selected, making it easier to review a choice before continuing.

#### 7. Better Keyboard and Assistive-Technology Support

This release includes a broad usability pass across common AgenticFlow screens. Buttons that previously relied only on an icon now have meaningful names, choice cards can be reached and selected from a keyboard, and switches communicate what they control.

The improvements are available across:

* Agents and agent chat
* Workflows and schedulers
* Workforce publishing and cloning
* Marketplace templates
* MCP and connection setup
* Projects and member invitations
* AI Drive and Datasets
* Image generation
* Pricing information
* Sharing and publishing

These changes do not alter the underlying workflow. They make the same features easier to understand and operate for more users.

***

### Model Updates Included

* Added Gemini 3.7 Flash
* Added Grok 4.6
* Added Muse Spark 1.2
* Added Qwen 3.8 Max
* Added DeepSeek V4 Pro 0813
* Added Qwen3.8-27B

### Improvements Included

* Added confirmation before deleting workflows, AI Drive items, MCP servers, Workforces, and connections
* Improved Library resource creation and direct access to the create page
* Improved MCP connection-status and tool-availability guidance
* Corrected Multi-Agent Marketplace navigation
* Improved the signed-in welcome and deploy journey
* Kept dataset deletion separate from detail-page navigation
* Added clearer labels across agent, workflow, workforce, scheduler, project, connection, and image-generation forms
* Improved keyboard access for sharing, publishing, category selection, and template cloning
* Made repeated actions easier to distinguish by including the relevant platform, template, or item name
* Improved chat message, send, history, version, and close controls
* Clarified selected states for app types, switches, and choice controls

***

### 🚀 6 Workflow Blueprint Prompts

Copy any prompt below into **Claude Code**, **Codex**, **Ishi**, or another AI coding agent with the **AgenticFlow CLI** installed to deploy a working workflow in minutes. These prompts were selected from six different AgenticFlow use cases and are ready to run as one-shot blueprint demos.

#### 1. Translation Quality Check Pack (`translation-quality-check-pack`)

```
Using the AgenticFlow CLI, deploy the translation-quality-check-pack blueprint. Use this Japanese source text:

"本契約は、顧客データの処理、保存、削除に関する責任分担を定めるものです。サービス提供者は、監査ログを90日間保持し、顧客の要求に応じてエクスポート可能にします。"

English translation: "This agreement defines each party's responsibilities for processing, storing, and deleting customer data. The service provider keeps audit logs for 90 days and can export them when the customer requests it."

Deploy, run once, show me the overall quality, meaning drift findings, terminology issues, suggested revision, and reviewer notes.

Leave the workflow deployed. Print the Web UI link.
One-line note: why this rung of the composition ladder?
```

***

#### 2. Add Sales CSV Invoice Pack workflow blueprint (`sales-csv-invoice-pack`)

```
Using the AgenticFlow CLI, deploy the sales-csv-invoice-pack blueprint. Use this CSV: customer,product,quantity,unit_price / Acme Co,Workflow Setup,1,1200 / Acme Co,Support Hours,8,150 / Brightline Inc,Training Seat,5,200. Invoice policy: "Calculate draft invoice totals by customer. Do not claim invoices were emailed, stored, paid, or approved." Deploy, run once, show me draft invoice summaries, validation issues, and next steps. Leave the workflow deployed. Print the Web UI link. One-line note: why this rung of the composition ladder?
```

***

#### 3. Convert website knowledge base workflow blueprint (`website-knowledge-base-pack`)

```
Using the AgenticFlow CLI, deploy the website-knowledge-base-pack blueprint. Use https://pixelml.com/ as the source URL.

Knowledge base policy: Create a RAG-ready knowledge base outline with source summary, sections, candidate chunks, metadata suggestions, unanswered questions, and QA checklist. Do not claim crawling beyond the supplied URL, vector database write, Supabase update, or external action occurred.

Deploy, run once, and show me the source summary, section outline, candidate chunks with metadata suggestions, unanswered questions, and QA checklist.

Leave the workflow deployed. Print the Web UI link.
One-line note: why this rung of the composition ladder?
```

***

#### 4. Company Docs QA Packet Workflow Blueprint (`company-docs-qa-pack`)

```
Using the AgenticFlow CLI, deploy the company-docs-qa-pack blueprint. Use these document excerpts:

Section: Expense Policy
Employees may expense economy airfare, hotel rooms up to USD 250 per night, and client meals up to USD 75 per person. Manager approval is required for exceptions.
---
Section: Security Review
New vendors must complete security review before production access. Required evidence includes SOC 2, DPA, subprocessor list, and SSO support.
---
Section: Onboarding
New hires receive laptop provisioning, HR orientation, and finance setup during week one.

Question: What evidence do we need before giving a new vendor production access, and who approves expense exceptions?

Deploy, run once, show me the direct answer, citation table, confidence, missing information, and suggested follow-up question.

Leave the workflow deployed. Print the Web UI link.
One-line note: why this rung of the composition ladder?
```

***

#### 5. Attendance Analytics Alert (`attendance-analytics-alert`)

```
Using the AgenticFlow CLI, deploy the attendance-analytics-alert blueprint. Use these attendance records:

"2026-06-04 | Alex Chen | Engineering | Present | Check-in 09:04 | Check-out 17:45
2026-06-04 | Mia Torres | Design | Late | Check-in 10:22 | Check-out 18:10
2026-06-04 | Dan Patel | Sales | Absent | Reason: no notice
2026-06-04 | Sarah Kim | Support | Present | Check-in 08:55 | Check-out 17:05"

Attendance policy: "Late after 09:30. Absence with no notice is critical and should alert the manager. More than one late/absent record in a department should be flagged for HR review."

Deploy, run once, show me the manager alert message, HR summary, exception table, and follow-up checklist.

Leave the workflow deployed. Print the Web UI link.
One-line note: why this rung of the composition ladder?
```

***

#### 6. Convert phase blog production workflow blueprint (`phase-blog-production-pack`)

```
Using the AgenticFlow CLI, deploy the phase-blog-production-pack blueprint. Use this blog brief:

"Topic: How AI workflow automation reduces manual operations work | Audience: operations leaders at B2B SaaS companies | Goal: generate qualified demo interest | Primary keyword: AI workflow automation | Tone: practical and executive-friendly | Target length: 1,200 words"

Production rules: Create a phase-based production packet with strategy, outline, draft plan, review checklist, SEO notes, and publishing handoff. Do not claim CMS publishing, Google Docs updates, agent delegation, or external action occurred.

Deploy, run once, and show me the strategy summary, phase table, outline, QA checklist, SEO notes, and publishing handoff.

Leave the workflow deployed. Print the Web UI link.
One-line note: why this rung of the composition ladder?
```

### Get Started

* **Try AgenticFlow free:** <https://agenticflow.ai/>
* **Latest changelog:** <https://docs.agenticflow.ai/changelog>
* **Join our Discord:** <https://qra.ai/discord>
* **Need help?** Email <support@agenticflow.ai> with the page you were using and what you expected to happen.


# Office Hour #53: DeepSeek V4 Flash 0731 & Agent Reliability Fixes

### Quick Recap

Office Hour #53 adds a new long-context DeepSeek model and resolves reliability issues across project management, API-created agents, and agent avatar delivery.

This release includes:

* DeepSeek V4 Flash 0731 availability through PixelML and AgenticFlow
* Protection against deleting the only remaining project from the workspace Projects page
* A consistent four-message limit for agent suggested messages across API and AI Studio paths
* A fix for API-created agents that could be missing from AI Studio after being created with five suggested messages
* Durable agent avatar URLs for the editor, chat, and embedded agent surfaces
* Safe fallback behavior when a previously stored avatar URL is unavailable

***

### What Changed & Why

#### 1. DeepSeek V4 Flash 0731 Added to PixelML and AgenticFlow

DeepSeek V4 Flash 0731 is now available through both first-party model surfaces:

**PixelML Provider**

* `pixelml/deepseek-v4-flash-0731`

**AgenticFlow Provider**

* `agenticflow/deepseek-v4-flash-0731`

DeepSeek released the official V4 Flash version on July 31, 2026, positioning it as a fast and economical text model for agentic workloads, coding, repository work, terminal tasks, tool use, and automation.

The AgenticFlow model entries expose:

* A 1,048,576-token context window
* Up to 65,536 output tokens
* Streaming responses
* Tool calling
* Structured output

DeepSeek's publisher documentation also describes thinking and non-thinking modes, JSON-object output, and reasoning with tools. The hosted DeepSeek API uses the rolling model ID `deepseek-v4-flash`; the dated `0731` entries in AgenticFlow select the July 31 version through the configured provider route.

Use this model for long-context, text-based agents and workflows that need fast coding, analysis, automation, or repeated tool use. No first-party image, audio, or video input capability is documented for this release.

The capability notes above summarize publisher-provided information and should not be read as AgenticFlow-run benchmark results. DeepSeek publishes a higher maximum output limit for its own hosted surface; AgenticFlow currently exposes the 65,536-token output limit shown in the Model Selector.

Sources:

* [DeepSeek API updates](https://api-docs.deepseek.com/updates/)
* [DeepSeek model and feature matrix](https://api-docs.deepseek.com/quick_start/pricing/)
* [DeepSeek V4 Flash 0731 model card](https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash-0731)
* [DeepSeek thinking mode](https://api-docs.deepseek.com/guides/thinking_mode/)
* [DeepSeek tool calling](https://api-docs.deepseek.com/guides/tool_calls/)
* [DeepSeek V4 technical report](https://arxiv.org/abs/2606.19348)
* [DSpark speculative decoding paper](https://arxiv.org/abs/2607.05147)

<figure><img src="/files/6huO1CVaXyNV4G49mZIS" alt="Original AgenticFlow editorial visual for DeepSeek V4 Flash 0731 showing its model shape, one-million-token context, direct API list pricing, and agent-oriented capabilities"><figcaption><p>Original AgenticFlow visual for the 0731 release. The model shape, context, and direct API price are publisher-provided; AgenticFlow credits and effective costs may differ.</p></figcaption></figure>

#### Why 0731 Is a Breakthrough for Agent Builders

The important story is not “a bigger model arrived.” DeepSeek says V4 Flash 0731 keeps the same model structure and size as the preview release, then improves it through post-training and an attached DSpark speculative-decoding module. That makes 0731 a useful case study in how better data, reasoning policy, tool behavior, and serving can move an agent model forward without simply scaling the base checkpoint.

```mermaid
flowchart LR
    Base["V4 Flash base<br/>MoE · 284B total · 13B active"] --> P["0731 post-training<br/>same base structure and size"]
    P --> S["DSpark attached<br/>speculative decoding"]
    P --> E["Agent behavior<br/>coding · terminal · tools"]
    S --> I["More interactive serving<br/>less verification waste"]
    E --> A["AgenticFlow<br/>long-context agents and workflows"]
    I --> A
    N["Not a new V4-Pro checkpoint"] -.-> P
```

The publisher's 0731 model-card table reports a large jump over the V4 Flash preview on the same listed agent benchmarks:

| Benchmark           | 0731 | V4 Flash preview | V4 Pro preview | Change vs preview |
| ------------------- | ---: | ---------------: | -------------: | ----------------: |
| Terminal Bench 2.1  | 82.7 |             61.8 |           72.1 |             +20.9 |
| NL2Repo             | 54.2 |             39.4 |           38.5 |             +14.8 |
| Cybergym            | 76.7 |             38.7 |           52.7 |             +38.0 |
| DeepSWE             | 54.4 |              7.3 |           12.8 |             +47.1 |
| Toolathlon Verified | 70.3 |             49.7 |           55.9 |             +20.6 |

These are publisher-reported results, not AgenticFlow-run evaluations. The public code-agent benchmarks used DeepSeek Harness minimal mode with `max` reasoning effort, `temperature = 1.0`, and `top_p = 0.95`; `DSBench-FullStack` and `DSBench-Hard` are internal test sets. The numbers are evidence of a meaningful post-training jump, not a guarantee that every workflow will improve by the same amount.

<figure><img src="/files/EoPMnlYFMwSniOtmZdwh" alt="DeepSeek&#x27;s official V4 Flash 0731 launch benchmark chart comparing it with the V4 Flash preview, V4 Pro preview, GLM-5.2, and Opus 4.8"><figcaption><p>DeepSeek's official launch graphic for V4 Flash 0731. It reproduces the publisher's benchmark table and settings note. Source: <a href="https://x.com/deepseek_ai/status/2083084415157022911">DeepSeek announcement on X</a>.</p></figcaption></figure>

<figure><img src="/files/TFAxQCEhRjfwYn6lngwN" alt="Official DeepSeek V4 family benchmark and long-context efficiency chart comparing V4 Pro and V4 Flash with other frontier models"><figcaption><p>Publisher-provided V4 family performance and long-context efficiency snapshot. This image comes from the V4 preview model card, so use it as family context—not as a direct 0731 benchmark. Source: <a href="https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash">DeepSeek V4 Flash model card</a>.</p></figcaption></figure>

The efficiency angle matters in production. The V4 family is a mixture-of-experts design: the model card lists 284B total parameters and 13B activated for Flash, while both V4 variants support a one-million-token context. DeepSeek's technical report also describes compressed attention, mHC, and Muon optimization; for V4 Pro at 1M context it reports 27% of V3.2's single-token inference FLOPs and 10% of the KV cache. That is why the breakthrough is best understood as a systems result: more useful agent behavior, long-context reach, and a lower operating envelope working together.

#### The New DeepSeek Pareto Story

“Pareto frontier” means the set of options for which no alternative is simultaneously cheaper and better on the same objective. A model can sit on that frontier without being the absolute best model overall. For 0731, there are two related frontiers:

1. **Model selection: cost × capability.** DeepSeek's current direct API list price is $0.14 per 1M input tokens and $0.28 per 1M output tokens for `deepseek-v4-flash`; V4 Pro is listed at $0.435 and $0.87. That makes Flash roughly 3.1× cheaper on both listed token directions, before any peak pricing or AgenticFlow credit conversion. The trade-off is a lower ceiling on the hardest knowledge and agent tasks, so Flash is the better default when volume, context, and tool use matter more than the final few points of frontier quality.
2. **Serving: interactivity × throughput.** DeepSeek's DSpark paper describes confidence-scheduled speculative decoding and reports 60–85% faster per-user generation at matched throughput in the DeepSeek-V4 serving system. This is a serving-system result, not an AgenticFlow benchmark and not a claim that every hosted route will reproduce it. It explains why the 0731 model card exposes DSpark as part of the model structure: agent quality is only useful if users can iterate at interactive speed.

<figure><img src="/files/lerjpVWtHRRwHSWus0Fd" alt="Schematic Pareto frontier showing DeepSeek V4 Flash 0731 as an efficient model-selection point and DSpark as a serving interactivity improvement"><figcaption><p>Schematic explanation of the two Pareto frontiers. It is an editorial model-selection diagram, not a benchmark leaderboard.</p></figcaption></figure>

#### External Launch Evidence: Real-World Agents, Cost, and Local Inference

The launch also produced useful evidence outside DeepSeek's own benchmark harness. These signals should be read in their proper category: Arena reports results from real-world agent sessions, while the individual creator and tooling posts below are commentary or demonstrations rather than reproducible product benchmarks.

**Agent Arena: real-world sessions**

On August 4, 2026, Agent Arena reported **DeepSeek-V4-Flash-20260731 (High)** at **#21 overall** and **#3 among open-source models**, based on more than **12,500 real-world agentic sessions**. Arena also reported a **+1.98% net improvement**, with **+6.99% Confirmed Success** but **-2.31% Steerability**. That last trade-off matters: the release looks strong in completed-task outcomes, but builders should still test how well it follows corrections and changing instructions in their own agents.

<figure><img src="/files/LFtjjvHOlb4R4ylzTcXU" alt="Agent Arena chart ranking DeepSeek V4 Flash High at number 21 overall with positive net improvement"><figcaption><p>Agent Arena's real-world session snapshot for the July 31 release. Source: <a href="https://x.com/arena/status/2084657730758046101">Agent Arena on X</a>. Arena's ranking and signals are independent of DeepSeek's publisher benchmark table.</p></figcaption></figure>

**Agent Arena: the cost-performance Pareto point**

In a second post, Arena placed the current **DeepSeek-V4-Flash (High)** on its cost-performance frontier at a reported **$0.024 median cost per task**, calculated from real Agent Mode token usage including cache hits and misses. Arena described it as the lowest-price model on its chart with a positive net improvement. The number is a workload-specific Arena measurement—not the same thing as DeepSeek's per-token API list price or AgenticFlow credits—and it can move as model pricing, prompts, and traffic change.

<figure><img src="/files/29rBvn1tc1EhFq0Fe4rX" alt="Agent Arena cost-performance Pareto chart highlighting DeepSeek V4 Flash High at 0.024 dollars median cost per task"><figcaption><p>Agent Arena's cost-performance Pareto snapshot. Source: <a href="https://x.com/arena/status/2084807343926399463">Agent Arena Pareto post on X</a>.</p></figcaption></figure>

**A local inference signal: DGX Spark × 2**

The `@wmoto_ai` post is a useful glimpse of the local-inference story. Translated from Japanese, the author says that an earlier run had not enabled reasoning effort, then reports a rerun at **Reasoning Effort Max** decoding at approximately **46 tokens/second** on two DGX Spark systems. The post is an individual demonstration: it does not specify a full reproducible harness, prompt, quantization, or end-to-end latency, so it should not be read as a guaranteed local performance number.

<figure><img src="/files/Xmssko4uQMoG6gcFAUc7" alt="Thumbnail from the DGX Spark DeepSeek V4 Flash demo video"><figcaption><p>Community demonstration of a DeepSeek V4 Flash workload on two DGX Spark systems. <a href="https://x.com/wmoto_ai/status/2083438448279695452/video/1">Watch the demo on X</a>. Demonstration only; hardware and workload details are not independently verified here.</p></figcaption></figure>

{% embed url="<https://x.com/wmoto_ai/status/2083438448279695452>" %}

**Launch commentary and baseline hygiene**

Two widely shared reactions are useful context but should not be promoted to benchmark evidence:

* [Cline's launch note](https://x.com/cline/status/2083094354030362858) highlighted the 82.7 Terminal-Bench result and said the model was initially API-only. Cline compared against an earlier April-preview value of 56.9; that is a different baseline from DeepSeek's model-card preview column of 61.8, so the deltas should not be mixed.
* [Andrew Curran's pricing reaction](https://x.com/AndrewCurran_/status/2084509003384827970) captured the surprise around DeepSeek's low price point. It is commentary on a pricing chart, not a source for AgenticFlow credits or a substitute for the [official DeepSeek pricing table](https://api-docs.deepseek.com/quick_start/pricing/).

<figure><img src="/files/9A8FWs6ZFMuUEBrtmI6L" alt="Cline post discussing the DeepSeek V4 Flash Terminal-Bench score and API availability"><figcaption><p>Cline's launch commentary. The baseline in this post refers to an earlier April preview, not the V4 Flash preview column used in DeepSeek's later model-card table. Source: <a href="https://x.com/cline/status/2083094354030362858">Cline on X</a>.</p></figcaption></figure>

<figure><img src="/files/ZhhEEzXKR6skxcpPsNdm" alt="Andrew Curran post reacting to DeepSeek&#x27;s pricing visibility in a market comparison chart"><figcaption><p>Andrew Curran's commentary on the pricing shock around the release. Source: <a href="https://x.com/AndrewCurran_/status/2084509003384827970">Andrew Curran on X</a>.</p></figcaption></figure>

For AgenticFlow builders, the practical default is straightforward: start with `agenticflow/deepseek-v4-flash-0731` for long-context coding, repository analysis, terminal work, structured extraction, and repeated tool calls. Move to a higher-cost frontier model when the task's failure cost justifies it, and ground either choice with Knowledge, retrieval, or verification tools when factual accuracy is load-bearing.

#### 2. The Workspace UI Protects the Last Project

The Projects page now disables **Delete** when a workspace has only one project in the loaded project list. The control explains that a workspace must retain at least one project instead of opening a confirmation flow that would leave the regular workspace experience without a project context.

When a workspace has multiple projects, deletion behavior is unchanged.

This is a workspace UI safeguard for normal dashboard usage. Existing backend rules that prevent deletion of projects still referenced by agents or workflows continue to apply separately.

#### 3. Suggested Message Limits Are Consistent Across API and AI Studio

AI Studio supports up to four suggested starter messages per agent. Previously, agent create and update requests could accept five messages, producing a record that no longer matched the AI Studio list schema. As a result, an agent created through the API could be accepted successfully but then be missing from the AI Studio dashboard.

Agent create and update requests now enforce the same maximum of four suggested messages used by AI Studio and agent templates. Requests with more than four messages return a validation error before the incompatible record is persisted.

This prevents new API-created agents from entering the mismatched state. Existing agents that already contain five suggested messages should be reduced to four before being saved again; this release does not automatically rewrite those existing records.

#### 4. Agent Avatars Now Use Durable Delivery URLs

Agent avatar uploads previously stored an expiring presigned download URL. The image could appear correctly after upload and then break later in both the editor and the embedded agent after the signed URL expired.

<figure><img src="/files/dAoltq8w4SZBpEqWqYqe" alt="Agent editor showing a broken avatar image before the durable delivery URL fix"><figcaption><p><strong>Before:</strong> an expired avatar URL could leave a broken image in the agent editor.</p></figcaption></figure>

<figure><img src="/files/9IhKr3rc6BBkyOd2qDS7" alt="Embedded agent widget showing broken avatar images before the durable delivery URL fix"><figcaption><p><strong>Before:</strong> the same expired avatar could also appear broken in the embedded agent widget.</p></figcaption></figure>

New avatar uploads now use the public avatar delivery path and save a durable delivery URL in the agent configuration. The same URL is used across the agent editor, chat welcome and message views, and embedded chat surfaces.

The updated flow also improves failure handling:

* The upload waits briefly for the delivered image to become available before updating the form
* Upload failures show a clear error and keep the previous avatar value
* An unavailable stored avatar falls back to the bundled default agent icon instead of rendering a broken image

After uploading or cropping an avatar, builders must still select **Save** in the agent editor to persist the new URL. Existing expired avatar URLs are not migrated automatically; re-uploading the image once and saving the agent moves it to the durable delivery path.

***

### Model Updates Included

* Added `pixelml/deepseek-v4-flash-0731`
* Added `agenticflow/deepseek-v4-flash-0731`
* Added model-selection guidance for long-context coding, automation, and tool-use workloads

### Bug Fixes Included

* Disabled deletion of the only remaining project from the workspace Projects page
* Aligned agent create, update, template, and AI Studio validation around a maximum of four suggested messages
* Prevented new API-created agents from disappearing from AI Studio because of a five-message payload
* Replaced expiring agent avatar references with durable delivery URLs for new uploads
* Added default-avatar fallbacks across agent editor, chat, and embedded surfaces
* Improved avatar upload readiness and failure feedback while preserving the previous avatar on failure

***

### 🚀 6 Workflow Blueprint Prompts

Copy any prompt below into **Claude Code**, **Codex**, **Ishi**, or another AI coding agent with the **AgenticFlow CLI** installed to deploy a working workflow in minutes. These six use cases cover procurement, financial monitoring, email automation, content analysis, meeting operations, and lead generation.

#### 1. Marketplace Price Comparison (`marketplace-price-comparison`)

Compare marketplace offers for a product and produce a structured buying recommendation based on seller reputation, shipping, returns, total value, and verification risk.

> Using the AgenticFlow CLI, deploy the marketplace-price-comparison blueprint. Use these inputs:
>
> Product query: Logitech MX Master 3S mouse Buyer priorities: Prefer reputable sellers, fast shipping, clear return policy, and total value over absolute lowest price.
>
> Deploy, run once, show me the structured offers JSON and buying recommendation including best candidate source, risks, missing info, verification steps, and concise recommendation.
>
> Leave the workflow deployed. Print the Web UI link. One-line note: why this rung of the composition ladder?

***

#### 2. Financial Transaction Tracker (`financial-transaction-tracker-pack`)

Classify a transaction batch, flag material or unfamiliar outflows, and turn the findings into a concise review packet without claiming external accounting or messaging actions.

> Using the AgenticFlow CLI, deploy the financial-transaction-tracker-pack blueprint. Use these transaction rows:
>
> "2026-06-03 | debit | AWS | 2180.00 | cloud infrastructure | card ending 1842 2026-06-03 | credit | Stripe | 18400.00 | customer payments | payout batch 2026-06-04 | debit | Unknown Vendor | 1299.00 | software subscription | card ending 1842 2026-06-04 | debit | Payroll Provider | 14250.00 | payroll | ACH"
>
> Tracking policy: "Categorize income, payroll, software, cloud, or unknown. Flag unknown vendors over $500 and any single outflow above $10,000. Draft Notion/Telegram-style review notes. Do not claim Gmail, Notion, Telegram, bank, or accounting actions occurred."
>
> Deploy, run once, show me the summary, classified transaction table, risk flags, and review note draft.
>
> Leave the workflow deployed. Print the Web UI link. One-line note: why this rung of the composition ladder?

***

#### 3. Weather Forecast Email (`weather-forecast-email`)

Generate a commute-focused weather briefing for a selected location, email it to the chosen recipient, and report the send result.

> Using the AgenticFlow CLI, deploy the weather-forecast-email blueprint. Use these inputs:
>
> Location: London Forecast context: daily commute Recipient email: your own email
>
> Deploy, run once, show me the weather forecast email and send confirmation.
>
> Leave the workflow deployed. Print the Web UI link. One-line note: why this rung of the composition ladder?

***

#### 4. Content Page Insights (`content-page-insights-pack`)

Analyze a web page for message clarity, audience fit, proof gaps, conversion opportunities, and reusable content angles without changing the source page.

> Using the AgenticFlow CLI, deploy the content-page-insights-pack blueprint. Analyze this URL: <https://pixelml.com/>
>
> Analysis goal: "Analyze homepage clarity for operations teams evaluating AI workflow automation. Identify key messages, missing proof, conversion opportunities, and reusable content angles. Do not claim page edits, publishing, or external updates occurred."
>
> Deploy, run once, show me the page analyzed, key messages, audience fit, proof gaps, conversion opportunities, and reusable content angles.
>
> Leave the workflow deployed. Print the Web UI link. One-line note: why this rung of the composition ladder?

***

#### 5. Meeting Action Tracker (`meeting-action-tracker-pack`)

Transform meeting notes into an executive summary, decisions, owned action items, risks, open questions, and a follow-up draft.

> Using the AgenticFlow CLI, deploy the meeting-action-tracker-pack blueprint. Use this meeting data:
>
> "Title: Renewal Risk Review | Date: 2026-06-04 | Attendees: Sarah PM, Dan Eng, Mia CS, Omar Sales | Notes: Brightline renewal is at risk because SSO migration delayed admin rollout. Dan will ship SSO audit fix by June 10. Mia will prepare customer comms by June 6. Omar needs pricing exception approval before June 8. Open question: whether Finance accepts a phased renewal."
>
> Tracker rules: "Extract executive summary, decisions, action items with owners and due dates, risks, open questions, and follow-up note. Do not claim Notion, Slack, email, or calendar updates occurred."
>
> Deploy, run once, show me the executive summary, decisions, action item table, open questions, risks, and follow-up note draft.
>
> Leave the workflow deployed. Print the Web UI link. One-line note: why this rung of the composition ladder?

***

#### 6. Search Lead Generation (`search-lead-generation-pack`)

Score search results against a B2B ideal-customer profile, identify the strongest prospect, and draft review-ready next actions with data-quality notes.

> Using the AgenticFlow CLI, deploy the search-lead-generation-pack blueprint. Use these search rows:
>
> "Result: Northstar Health | URL: <https://example.com/northstar> | Snippet: regional healthcare network seeking patient experience analytics automation Result: Atlas Retail | URL: <https://example.com/atlas> | Snippet: ecommerce retailer scaling customer support and weekly operations reporting Result: Beacon Labs | URL: <https://example.com/beacon> | Snippet: AI research studio publishing technical demos"
>
> Lead policy: "ICP: B2B teams with customer feedback, support, or reporting automation pain. Score fit, summarize need, and draft next action for review only. Do not claim SerpAPI request, website fetch, Google Sheets write, dedupe update, or external action occurred."
>
> Deploy, run once, show me the lead scoring table, top lead, next actions, and quality notes.
>
> Leave the workflow deployed. Print the Web UI link. One-line note: why this rung of the composition ladder?

***

### Get Started

* **Try AgenticFlow free:** <https://agenticflow.ai/>
* **Latest changelog:** <https://docs.agenticflow.ai/changelog>
* **Join our Discord:** <https://qra.ai/discord>
* **Found a bug?** Email <support@agenticflow.ai> with a reproducible case.


# Office Hour #52: AI Drive ZIP Downloads, MCP Reliability & Model Lifecycle Updates

### Quick Recap

Office Hour #52 improves everyday file handling and integration reliability while expanding the model catalog and preparing teams for two imminent model and provider lifecycle deadlines.

This release includes:

* AI Drive folder downloads as ZIP archives with nested folder structure preserved
* More reliable custom MCP connections using authentication headers and Streamable HTTP
* MCP OAuth health checks before an integration is shown as connected
* New `gpt-5.6-sol` and `kimi-k3` model options
* OpenAI-compatible provider models displayed in the Agent Chat Model tab
* Deprecation handling and migration guidance for OpenAI models scheduled to shut down on July 23, 2026
* Removal of the Straico connection and nodes ahead of Straico's platform and API shutdown on July 22, 2026

🎥 Watch the full session:

{% embed url="<https://www.youtube.com/watch?v=qLxu_w-JKdA>" %}

***

### What Changed & Why

#### 1. Custom MCP Headers Now Work More Reliably

Custom MCP servers can require API keys, bearer tokens, tenant identifiers, or other values to be sent as HTTP headers. AgenticFlow now preserves those headers throughout the connection lifecycle and uses them when validating the server and discovering its tools.

This update also hardens the Streamable HTTP discovery path. Responses are fully consumed before AgenticFlow parses the MCP payload, preventing authenticated connections from appearing healthy while returning `0 tools` because the streaming response could not be read.

For builders, this means custom MCP servers using header authentication can move from setup to tool discovery without losing their authentication context. If discovery fails, the integration reports the failure instead of presenting an apparently usable connection.

#### 2. Download Complete AI Drive Folders as ZIP Archives

AI Drive folders now include a **Download as ZIP** action. One action packages the selected folder and its accessible contents instead of requiring every file to be downloaded separately.

<figure><img src="/files/htzTUTXH7HtXq9aCbmAl" alt="AI Drive folder row menu showing the Download as ZIP action"><figcaption><p>Open a folder's menu in AI Drive and choose <strong>Download as ZIP</strong> to package the entire folder and its nested contents in one action.</p></figcaption></figure>

The generated archive:

* Includes accessible files and subfolders recursively
* Preserves relative paths and the original nested directory structure
* Preserves empty subfolders
* Keeps identical filenames in different subfolders from colliding
* Uses a filesystem-safe archive name based on the selected folder
* Uses the existing permission-aware file download path for every file

Large folders show preparation, file-packaging, and compression progress. If individual files cannot be fetched, AgenticFlow identifies skipped files; if no files can be downloaded, it shows an actionable failure instead of producing an empty archive.

The existing single-file download flow is unchanged.

#### 3. GPT-5.6 Sol and Kimi K3 Added to the Model Catalog

Two new frontier model options are now available for agent and workflow workloads:

| Model         | Best suited for                                                                                | Published capabilities                                                                                                                                                                                                                                                                                 |
| ------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `gpt-5.6-sol` | Complex professional work, advanced reasoning, coding, research, and tool-intensive agents     | OpenAI's flagship GPT-5.6 model with a 1.05M-token context window, up to 128K output tokens, text and image input, configurable reasoning effort, function calling, Structured Outputs, and Responses API tools including web search, file search, code execution, computer use, MCP, and tool search. |
| `kimi-k3`     | Long-horizon coding, multimodal knowledge work, document-heavy automation, and agent workflows | Kimi's frontier model with up to a 1,048,576-token context window, multimodal understanding across images, video, PDFs, Word documents, and spreadsheets, plus tool calling, JSON mode, structured outputs, context caching, and configurable reasoning effort.                                        |

Use `gpt-5.6-sol` when the workload needs OpenAI's highest-capability model and broad hosted-tool support. Use `kimi-k3` for long-context, multimodal, document, and coding workloads that benefit from Kimi's agent-oriented execution profile.

The capability notes above summarize publisher-provided information and should not be read as AgenticFlow-run benchmark results.

**Visual Model Evidence**

The charts below are publisher-provided benchmark comparisons from Kimi's K3 announcement. They include GPT-5.6 Sol and other frontier models for context, but they are not AgenticFlow-run evaluations. Results can vary with the benchmark harness, reasoning effort, fallback behavior, and tool configuration.

<figure><img src="/files/j8iH9xUmhPllosxUDukq" alt="Kimi&#x27;s official coding benchmark comparison for Kimi K3, GPT-5.6 Sol, Claude Fable 5, Claude Opus 4.8, GPT-5.5, and GLM-5.2"><figcaption><p>Kimi K3 coding benchmark comparison. Source: <a href="https://www.kimi.com/en/blog/kimi-k3">Kimi K3 announcement</a>.</p></figcaption></figure>

<figure><img src="/files/W1ZdSDIqdxVBDVOyYAyh" alt="Kimi&#x27;s official general-agent and visual-agent benchmark comparison for Kimi K3 and other frontier models"><figcaption><p>Kimi K3 general-agent and visual-agent benchmark comparison. Source: <a href="https://www.kimi.com/en/blog/kimi-k3">Kimi K3 announcement</a>.</p></figcaption></figure>

Sources:

* [OpenAI GPT-5.6 Sol model documentation](https://developers.openai.com/api/docs/models/gpt-5.6-sol)
* [OpenAI GPT-5.6 model guidance](https://developers.openai.com/api/docs/guides/latest-model)
* [Kimi K3 announcement](https://www.kimi.com/fr-fr/blog/kimi-k3)
* [Kimi Code model configuration](https://www.kimi.com/code/docs/en/kimi-code/models.html)

#### 4. OpenAI Model Deprecations: Action Required Before July 23

OpenAI is shutting down 15 legacy-model deprecation entries on **July 23, 2026**. AgenticFlow now marks relevant legacy models as deprecated so teams can identify affected agents and workflows before runtime requests begin failing.

The July 23 shutdown includes:

| Retiring model entries                                                                                           | OpenAI's recommended substitute |
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `gpt-5-chat-latest`, `gpt-5-codex`, `gpt-5.1-chat-latest`, `gpt-5.1-codex`, `gpt-5.1-codex-max`, `gpt-5.2-codex` | `gpt-5.5`                       |
| `gpt-5.1-codex-mini`                                                                                             | `gpt-5.4-mini`                  |
| `computer-use-preview-2025-03-11`, `computer-use-preview`                                                        | `gpt-5.4-mini`                  |
| `gpt-4o-mini-search-preview-2025-03-11`, `gpt-4o-search-preview-2025-03-11`                                      | `gpt-5.4-mini`                  |
| `gpt-4o-mini-tts-2025-03-20`                                                                                     | `gpt-4o-mini-tts-2025-12-15`    |
| `gpt-audio-mini-2025-10-06`                                                                                      | `gpt-audio-1.5`                 |
| `gpt-realtime-mini-2025-10-06`                                                                                   | `gpt-realtime-mini`             |
| `o3-deep-research-2025-06-26`, `o3-deep-research`, `o4-mini-deep-research-2025-06-26`, `o4-mini-deep-research`   | `gpt-5.5-pro`                   |

AgenticFlow's broader model-catalog cleanup also marks legacy entries such as GPT-4o, GPT-4o Mini, and o1-mini as deprecated where they remain visible. These exact aliases are not all part of OpenAI's July 23 shutdown batch, so migration timing should be checked against OpenAI's official deprecation schedule.

Before July 23:

* Review agents and workflows that use a deprecated OpenAI model
* Replace the model and retest tool calls, structured outputs, and reasoning behavior
* Pay particular attention to Codex, computer-use, search-preview, audio, realtime, and deep-research workloads
* Avoid creating new production dependencies on entries already marked deprecated

Source: [OpenAI API deprecations](https://developers.openai.com/api/docs/deprecations)

#### 5. Straico Connection and Nodes Deprecated After Provider Shutdown Notice

Straico announced that its web app, desktop app, and API will shut down on **July 22, 2026**. Because AgenticFlow's Straico connection and workflow nodes depend directly on that API, they have been removed from new connection and workflow-building surfaces.

Teams with existing Straico-based workflows should migrate before the shutdown. Review any use of Straico prompt-completion or image-generation steps, move the workload to another supported provider, and preserve any Straico-hosted assets or outputs that still need to be retained.

This change affects only the Straico integration. Other AgenticFlow model providers and AI connections remain available.

Source: [Straico shutdown announcement](https://straico.com/straico-shutdown-announcement/)

#### 6. OpenAI-Compatible Models Now Appear in Agent Chat

Models from configured OpenAI-compatible providers now appear in the Agent Chat **Model** tab alongside built-in provider models. Provider labels and icons are retained so builders can identify where a model comes from instead of working from an unlabelled model slug.

<figure><img src="/files/eTD8YxerrxeKvNRLu0vU" alt="Agent Chat model selector showing the active provider and model"><figcaption><p>The Agent Chat model selector now includes models from configured OpenAI-compatible providers.</p></figcaption></figure>

This closes the gap between provider configuration and day-to-day agent use: once a compatible provider and its models are configured, those models can be selected directly while editing or chatting with an agent.

#### 7. MCP OAuth Connections Are Verified Before Showing Connected

MCP OAuth status now reflects actual connection health instead of only a completed callback or saved configuration.

After setup, AgenticFlow validates the provider authentication state and attempts tool discovery before treating the integration as durably connected. When validation cannot complete, the interface can surface states such as **Requires Auth**, **Verification Failed**, or **Tools unavailable** with clearer next steps.

This protects agent-building and tool-call flows from silently depending on an MCP integration that cannot authenticate or expose tools. Provider-specific failures are surfaced during setup or attachment, before they become harder-to-diagnose runtime failures.

***

### Enhancements, Fixes & Deprecations Included

* Added custom-header persistence and validation for MCP connections
* Fixed Streamable HTTP discovery failures caused by parsing unread streaming responses
* Improved error visibility when an authenticated MCP server cannot expose tools
* Added AI Drive folder downloads as ZIP archives with recursive structure preservation
* Added progress feedback, safe archive naming, empty-folder handling, and partial-download reporting
* Added `gpt-5.6-sol` and `kimi-k3` to the model catalog
* Added OpenAI-compatible provider models, labels, and icons to the Agent Chat Model tab
* Added verified MCP OAuth and tool-discovery states before showing integrations as connected
* Marked affected and legacy OpenAI models as deprecated ahead of provider shutdown dates
* Removed Straico connection and node options following Straico's platform shutdown announcement

***

### 🚀 7 Workflow Blueprint Prompts

Copy any prompt below into **Claude Code**, **Codex**, **Ishi**, or another AI coding agent with the **AgenticFlow CLI** installed to deploy a working workflow in minutes. These seven use cases span security triage, creative production, interior design, weather and tech-news email digests, product-review analysis, and price monitoring.

#### 1. Network Vulnerability Report Packet (`network-vulnerability-report-pack`)

Turn raw scan findings into a prioritized security triage report — executive summary, severity-ranked findings table, likely CVE lookup targets, a remediation plan, and a notification draft. Draft-only; it does not run scans or take external actions.

> Using the AgenticFlow CLI, deploy the network-vulnerability-report-pack blueprint. Use these scan findings:
>
> Host: api.internal.example | Open ports: 22/tcp OpenSSH 8.2, 80/tcp nginx 1.18, 443/tcp nginx 1.18 | TLS: supports TLS 1.2 and 1.3 | Finding: HTTP redirects to HTTPS but missing HSTS | Finding: SSH password authentication enabled | Scope: internal staging API
>
> Report policy: Create a security triage report with severity, likely CVE lookup targets, remediation steps, and notification draft. Draft only; do not claim Nmap execution, file write, Telegram send, email send, CVE API lookup, or external action occurred.
>
> Deploy, run once, show me the executive summary, findings table, CVE lookup targets, remediation plan, notification draft, and assumptions.
>
> Leave the workflow deployed. Print the Web UI link.

***

#### 2. Motivational Short Creative Packet (`motivational-short-creative-pack`)

Turn a short creative brief into a complete short-form video plan — a hook, a 30-second voiceover script, a shot list, a generated key visual, voice direction, and a production checklist. Draft assets only.

> Using the AgenticFlow CLI, deploy the motivational-short-creative-pack blueprint. Use these inputs:
>
> Creative brief: Theme: keep showing up when progress feels invisible | Audience: early-stage founders | Format: 30-second vertical motivational short | Tone: grounded, cinematic, not cheesy Production policy: Create a 30-second script, shot list, image prompt, voiceover direction, and production checklist. Draft only; do not claim Ollama generation, fal.ai render, ElevenLabs voice, Google Sheets save, video render, or external action occurred.
>
> Deploy, run once, show me the hook, 30-second voiceover script, shot list, generated key visual URL, voice direction, and production checklist.
>
> Leave the workflow deployed. Print the Web UI link.

***

#### 3. Interior Moodboard Creative Packet (`interior-moodboard-creative-pack`)

Turn a one-line room brief into a coherent moodboard packet — concept directions, a palette, materials, furniture notes, and a generated moodboard image. Draft assets only.

> Using the AgenticFlow CLI, deploy the interior-moodboard-creative-pack blueprint. Room brief:
>
> "Room: small home office | Style: warm Japandi | Colors: oak, cream, muted sage | Needs: ergonomic desk, soft lighting, storage for books, calm video-call background"
>
> Creative constraints: "Create concept directions, palette, furniture notes, and one moodboard image. Draft assets only; do not claim Nextcloud folder creation, file sharing, PDF export, or external action occurred."
>
> Deploy, run once, show me the concept name, palette, materials, furniture notes, generated image status, and shopping considerations.
>
> Leave the workflow deployed. Print the Web UI link.

***

#### 4. Weather Report Email (`weather-report-email`)

Fetch a forecast for any city and turn it into a readable weather report, then send it as an email — a full end-to-end daily briefing that completes a real send.

> Using the AgenticFlow CLI, deploy the weather-report-email blueprint. Use these inputs:
>
> City: New York Latitude: 40.7128 Longitude: -74.0060 Recipient email: your own email
>
> Deploy, run once, show me the generated weather report and confirm the email send result.
>
> Leave the workflow deployed. Print the Web UI link.

***

#### 5. Tech News Radar Email (`tech-news-radar-email`)

Point it at any feed and a focus topic and it curates the top items into a clean digest, then emails it — a self-running news radar you can put on a schedule.

> Using the AgenticFlow CLI, deploy the tech-news-radar-email blueprint. Use these inputs:
>
> Feed URL: <https://feeds.feedburner.com/TheHackersNews> Focus topic: cybersecurity Max items: 5 Recipient email: your own email
>
> Deploy, run once, show me the curated digest that was generated and confirm the email send result.
>
> Leave the workflow deployed. Print the Web UI link.

***

#### 6. Product Review Insight Packet (`product-review-insight-pack`)

Turn a batch of product reviews into a decision-ready packet — average rating, sentiment, top themes, defect signals, buyer language, product and marketing opportunities, and a Slack-style summary. Draft analysis only.

> Using the AgenticFlow CLI, deploy the product-review-insight-pack blueprint. Use these review rows:
>
> rating,review 5,Great battery life and easy setup. Works well for travel. 2,Plastic hinge feels weak and the app disconnected twice. 4,Good value but instructions were confusing. 1,Stopped charging after two weeks and support was slow.
>
> Analysis policy: Analyze sentiment, themes, defects, buyer language, and improvement opportunities. Draft only; do not claim Apify run, Google Sheets save, Slack send, batch split, or external action occurred.
>
> Deploy, run once, show me the average rating, sentiment, top themes, defect signals, buyer language, product and marketing opportunities, and Slack-style summary draft.
>
> Leave the workflow deployed. Print the Web UI link.

***

#### 7. Price Monitor Alert Packet (`price-monitor-alert-pack`)

Compare a list of products against their target and previous prices, flag the ones at or below target, and draft Telegram-style alert text. Draft-only; it does not scrape or send.

> Using the AgenticFlow CLI, deploy the price-monitor-alert-pack blueprint. Use these price rows:
>
> sku,product,current\_price,target\_price,previous\_price,url A100,Noise-canceling headphones,89.99,95.00,109.99,<https://www.amazon.com/> B200,Standing desk mat,42.50,40.00,39.99,<https://www.amazon.com/> C300,USB-C hub,24.99,30.00,34.99,<https://www.amazon.com/>
>
> Alert policy: Flag products where current price is at or below target, compare against previous price, and draft Telegram-style alert text. Draft only; do not claim Decodo scrape, Google Sheets save, Telegram send, calendar reminder, Gmail send, or external action occurred.
>
> Deploy, run once, show me the alert summary, product decision table, price-change notes, Telegram-style alert drafts, and operations notes.
>
> Leave the workflow deployed. Print the Web UI link.

***

### Get Started

* **Try AgenticFlow free:** <https://agenticflow.ai/>
* **Latest changelog:** <https://docs.agenticflow.ai/changelog>
* **Join our Discord:** <https://qra.ai/discord>
* **Found a bug?** Email <support@agenticflow.ai> with a reproducible case.


# Office Hour #51: Claude Fable 5, Sonnet 5 & Opus 4.8 Model Updates

### Quick Recap

Office Hour #51 expands model availability across PixelML and the Anthropic provider, giving builders more Claude-family options for high-capability reasoning, long-running agent work, and everyday cost-performance workflows.

This release includes:

* Claude Fable 5 availability through PixelML
* Claude Sonnet 5 availability through PixelML
* Claude Opus 4.8 availability through the Anthropic provider
* Claude Fable 5 availability through the Anthropic provider
* Claude Sonnet 5 availability through the Anthropic provider
* Clearer model-choice guidance for builders choosing between frontier capability, enterprise reliability, and everyday speed/cost balance
* AgenticFlow CLI v1.10.7 updates, including the new `autonomous-desk` workforce blueprint, a MAS graph-building playbook, workflow-in-workforce routing support, and a much larger CLI-shipped blueprint catalog

🎥 Watch the full session:

{% embed url="<https://www.youtube.com/watch?v=knqeRIYwE2M>" %}

***

### What Changed & Why

#### 1. New Claude Models Added Across PixelML and Anthropic

This release adds new Claude model options to the model catalog so agents and workflows can be configured against the right provider surface for each team.

**PixelML Provider**

* Claude Fable 5
* Claude Sonnet 5

**Anthropic Provider**

* Claude Opus 4.8
* Claude Fable 5
* Claude Sonnet 5

Teams now have a cleaner path for selecting Claude models directly from the Model Selector, whether they prefer PixelML-managed access or their own Anthropic connection.

```mermaid
flowchart LR
    W["Workload"] --> S["Claude Sonnet 5"]
    W --> O["Claude Opus 4.8"]
    W --> F["Claude Fable 5"]

    S --> S1["Everyday production agents"]
    S --> S2["High-volume coding, document, support, and content work"]

    O --> O1["Complex enterprise coding"]
    O --> O2["Longer agent sessions where reliability matters"]

    F --> F1["Highest-capability reasoning"]
    F --> F2["Deep research, long-horizon planning, and vision-heavy workflows"]

    F --> R{"Safety classifier refusal?"}
    R -->|"No"| Done["Return Fable result"]
    R -->|"Yes"| FB["Fallback to another Claude model"]
```

The selection path is simple: use Sonnet 5 for scalable everyday execution, Opus 4.8 for dependable high-end enterprise agent work, and Fable 5 when the workflow needs the highest available capability and can handle refusal/fallback behavior.

#### 2. Better Coverage Across Capability Tiers

These additions give builders a more complete Claude lineup for different workload profiles:

* **Claude Fable 5** is the highest-capability option for the most demanding reasoning, long-horizon agentic work, complex software tasks, research, vision-heavy workflows, and multi-step planning.
* **Claude Opus 4.8** is a strong default for complex agentic coding and enterprise work where reliability, instruction following, and sustained context handling matter.
* **Claude Sonnet 5** is the balanced option for everyday agent workflows, coding, document work, and general knowledge tasks where teams want strong capability with better speed and cost efficiency.

For practical agent design, use Fable 5 when maximum capability matters most, Opus 4.8 when a complex enterprise workflow needs a dependable high-end model, and Sonnet 5 when you want the best day-to-day balance.

**Model Evidence Notes**

The notes below summarize external model evidence from Anthropic's public model documentation and announcements. They are useful for model-selection context, but should be read as publisher-provided model evidence rather than AgenticFlow-run evaluation results.

| Model           | Surface            | Why it matters                                                                                                                                                                                                                                                                                                                        |
| --------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Claude Fable 5  | PixelML, Anthropic | Anthropic describes Fable 5 as its most capable widely released model, built for demanding reasoning and long-horizon agentic work. It supports a 1M-token context window, up to 128K output tokens, adaptive thinking, tool calling, code execution, memory, and vision.                                                             |
| Claude Opus 4.8 | Anthropic          | Anthropic positions Opus 4.8 for complex agentic coding and enterprise work. It supports a 1M-token context window, up to 128K output tokens, adaptive thinking, vision, and strong tool-use workflows.                                                                                                                               |
| Claude Sonnet 5 | PixelML, Anthropic | Anthropic positions Sonnet 5 as the best combination of speed and intelligence, with substantially improved cost-performance over Sonnet 4.6 and higher-effort performance that can match Opus 4.8 on some tasks. It supports a 1M-token context window, up to 128K output tokens, adaptive thinking, vision, and tool-use workflows. |

**Visual Model Evidence**

The figures below are publisher-provided charts from Anthropic. They add visual context for why these models are useful in agent and workflow builders, but they are not AgenticFlow-run benchmark results.

<figure><img src="https://www.anthropic.com/_next/image?q=75&#x26;url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2Fa9007019094f217e98cb8261a2765d7646c01708-2600x1392.png&#x26;w=3840" alt="Official Claude Opus 4.8 benchmark table comparing coding, agentic terminal coding, reasoning, computer use, knowledge work, and financial analysis results"><figcaption><p>Claude Opus 4.8 benchmark evidence from Anthropic's Opus 4.8 announcement. Source: <a href="https://www.anthropic.com/news/claude-opus-4-8">Introducing Claude Opus 4.8</a>.</p></figcaption></figure>

<figure><img src="https://www.anthropic.com/_next/image?q=75&#x26;url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2Fcd0df787f39b6408dcba539fba93f817f2f3c0b4-3840x2160.png&#x26;w=3840" alt="Official Claude Sonnet 5 agentic search cost-performance chart comparing Sonnet 5, Opus 4.8, and Sonnet 4.6 across effort levels"><figcaption><p>Sonnet 5 cost-performance evidence on agentic search from Anthropic. Source: <a href="https://www.anthropic.com/news/claude-sonnet-5">Introducing Claude Sonnet 5</a>.</p></figcaption></figure>

<figure><img src="https://www.anthropic.com/_next/image?q=75&#x26;url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2Fd5c761e88dc46d7f79990dc2c4ad7a7cbaebdf3b-3840x2160.png&#x26;w=3840" alt="Official Claude Sonnet 5 agentic computer use cost-performance chart comparing Sonnet 5, Opus 4.8, and Sonnet 4.6 across effort levels"><figcaption><p>Sonnet 5 cost-performance evidence on agentic computer use from Anthropic. Source: <a href="https://www.anthropic.com/news/claude-sonnet-5">Introducing Claude Sonnet 5</a>.</p></figcaption></figure>

**Builder Integration Notes**

Fable 5 is the one model in this group that needs extra integration handling. Anthropic documents that Fable 5 can return `stop_reason: "refusal"` as a successful HTTP 200 response when its safety classifiers decline a request. For production agents, that means builders should treat Fable refusals as a normal model outcome, not as infrastructure failure.

Practical defaults:

* Add a visible fallback path for Fable 5 workflows, usually to Opus 4.8 for complex work or Sonnet 5 for cost-sensitive everyday execution.
* Log refusals separately from provider errors so support teams can distinguish policy behavior from outages.
* Use the `effort` setting intentionally on Opus 4.8 and Sonnet 5 instead of relying on defaults when cost, latency, or quality targets matter.
* For high-volume Sonnet 5 workloads, account for the launch pricing window and the standard pricing that applies after August 31, 2026.

Sources:

* [Anthropic model overview](https://platform.claude.com/docs/en/about-claude/models/overview)
* [Introducing Claude Fable 5 and Claude Mythos 5](https://platform.claude.com/docs/en/about-claude/models/introducing-claude-fable-5-and-claude-mythos-5)
* [Introducing Claude Opus 4.8](https://www.anthropic.com/news/claude-opus-4-8)
* [Introducing Claude Sonnet 5](https://www.anthropic.com/news/claude-sonnet-5)

#### 3. How to Choose the New Models

Use the new model entries as workload-specific defaults:

* Choose **Claude Fable 5** for high-stakes planning, deep research, complex code generation, large migrations, multi-step agent loops, and workflows where quality matters more than cost or latency.
* Choose **Claude Opus 4.8** for enterprise-grade coding, analysis, document-heavy workflows, and longer agent sessions that need strong consistency and lower failure risk.
* Choose **Claude Sonnet 5** for production agents, support workflows, content operations, summarization, coding assistance, document analysis, and other high-volume workflows where capability and cost both matter.

#### 4. AgenticFlow CLI v1.10.7: More Blueprints and a Self-Correcting Desk

The AgenticFlow CLI has also moved from the v1.10.0 surface documented in earlier Office Hours to `@pixelml/agenticflow-cli@1.10.7`.

Key CLI updates since the last changelog pass:

* **New `autonomous-desk` workforce blueprint.** This is a desk-topology MAS pattern: Planner → route gate → deterministic workflow or web Researcher → Critic QA gate → automatic revision → Editor. Use it when a mission needs quality control, revision, and a final edited deliverable rather than a one-pass answer.
* **Workflow-in-workforce routing.** `af workforce init` now supports `--tool-workflow-id`, `--tool-workflow-purpose`, and `--tool-workflow-input` for the desk topology, so a deployed public-runnable workflow can serve as the deterministic route inside a higher-autonomy workforce.
* **New `mas-graph-building` playbook.** This documents the field-verified rules for hand-authored workforce graphs: the required `.output` hop in template references, condition branch indexes, state variable merging, structured-output schemas, and workflow invocation through `call_other_workflow`.
* **Larger CLI blueprint catalog.** The CLI now ships **379 blueprints**: 362 workflow blueprints, 3 agent blueprints, and 14 workforce blueprints. That includes n8n migration and many practical workflow packs such as `n8n-converter`, `email-to-structured`, `rss-digest-email`, `competitor-url-snapshot`, and `job-app-package`.
* **Smoother agent and workflow execution.** Recent v1.10.x fixes raised blueprint agent recursion defaults to 100, added `af workflow run --wait`, returned canonical workflow/workforce Web UI links in `_links`, added safe invocation guidance in `af bootstrap --json`, and added a Node.js 18+ launcher guard for npm installs.

Practical operator guidance:

* Start every AI-assisted CLI session with `af bootstrap --json`; the returned `invocation`, `blueprints`, `commands`, `changelog`, and `_links` fields are the current source of truth.
* Use `af blueprints list --kind workflow --json` before reaching for a workforce. Most new catalog growth is deterministic workflow packs, not multi-agent teams.
* Use `af workforce init --blueprint autonomous-desk --json` for self-correcting research, planning, or review missions; read `af playbook mas-graph-building` before hand-authoring a workforce graph.
* Use `af workflow run --workflow-id <id> --body '<flat_json>' --wait --json` when you want a single command to start the workflow and return the final output.

***

### Model Updates Included

* Added Claude Fable 5 to the PixelML provider
* Added Claude Sonnet 5 to the PixelML provider
* Added Claude Opus 4.8 to the Anthropic provider
* Added Claude Fable 5 to the Anthropic provider
* Added Claude Sonnet 5 to the Anthropic provider
* Added model-choice guidance for selecting between Fable 5, Opus 4.8, and Sonnet 5

### CLI Updates Included

* Updated the documented current CLI version to `@pixelml/agenticflow-cli@1.10.7`
* Added the `autonomous-desk` workforce blueprint to the Office Hours release record
* Documented workflow-in-workforce desk flags: `--tool-workflow-id`, `--tool-workflow-purpose`, and `--tool-workflow-input`
* Added the `mas-graph-building` playbook as the source of truth for hand-authored MAS graph rules
* Updated blueprint counts to 379 total CLI-shipped blueprints: 362 workflow, 3 agent, and 14 workforce
* Added `af workflow run --wait` and canonical `_links` behavior to the CLI release summary

***

### 🚀 5 Workflow Blueprint Prompts

Copy any prompt below into **Claude Code**, **Codex**, or another AI coding agent with the **AgenticFlow CLI** installed to deploy a working workflow in minutes. These five use cases cover security triage, market intelligence, stock research, sales-call coaching, and local lead enrichment.

#### 1. Web Security Quickscan Packet (`network-vulnerability-report-pack`)

Turn raw scan findings into a prioritized security triage report — executive summary, severity-ranked findings table, likely CVE lookup targets, remediation plan, and a notification draft. Draft-only; it does not run scans or take external actions.

> Using the AgenticFlow CLI, deploy the network-vulnerability-report-pack blueprint. Use these scan findings:
>
> Host: api.internal.example | Open ports: 22/tcp OpenSSH 8.2, 80/tcp nginx 1.18, 443/tcp nginx 1.18 | TLS: supports TLS 1.2 and 1.3 | Finding: HTTP redirects to HTTPS but missing HSTS | Finding: SSH password authentication enabled | Scope: internal staging API
>
> Report policy: Create a security triage report with severity, likely CVE lookup targets, remediation steps, and notification draft. Draft only; do not claim Nmap execution, file write, Telegram send, email send, CVE API lookup, or external action occurred.
>
> Deploy, run once, show me the executive summary, findings table, CVE lookup targets, remediation plan, notification draft, and assumptions.

***

#### 2. Market Intelligence Brief (`market-intelligence-brief-pack`)

Turn scattered regional market signals into a decision-ready brief with an executive summary, regional insights, an opportunity ranking, competitive risks, and recommended actions.

> Using the AgenticFlow CLI, deploy the market-intelligence-brief-pack blueprint. Research topic: "AI workflow automation demand in regulated industries"
>
> Market signals: "Southeast Asia: banks and media teams are piloting AI workflow tools but worry about compliance. US: operations teams ask for human-in-loop governance and audit trails. EU: buyers prioritize privacy-first deployments and model governance."
>
> Deploy, run once, show me the executive summary, regional insights, opportunity ranking, competitive risks, and recommended actions.
>
> Leave the workflow deployed. Print the Web UI link.

***

#### 3. Stock Price Target Brief (`stock-price-target-brief`)

Turn a single ticker and an investment style into a consistent research brief: quote snapshot, key news drivers, a watch rating, a risk checklist, and the next data to pull. Research and organization only — not financial advice.

> Using the AgenticFlow CLI, deploy the stock-price-target-brief blueprint. Use these inputs:
>
> Ticker: AAPL Company name: Apple Investment style: conservative long-term watchlist
>
> Deploy, run once, show me the quote snapshot, key news drivers, watch rating, risk checklist, and next data to pull.
>
> Leave the workflow deployed. Print the Web UI link.

***

#### 4. Sales Call Objection Coach (`sales-call-objection-coach-pack`)

Turn a raw sales-call transcript into coaching: an objection table, the discovery questions the rep missed, clear next steps, and a Slack-style coaching feedback draft. Draft analysis only; it does not retrieve, send, or write to external systems.

> Using the AgenticFlow CLI, deploy the sales-call-objection-coach-pack blueprint. Use this call transcript:
>
> "AE: Thanks for joining. What are you trying to improve? Prospect: Our support team spends too much time tagging tickets, but I am worried implementation will take months. AE: We can start with a small workflow. Prospect: Budget is tight this quarter and security will need to review any AI vendor. AE: I can send a case study. Prospect: Send it, but I need a clear rollout plan before involving my VP."
>
> Coaching policy: "Identify objections, buyer concerns, missed discovery questions, recommended next steps, and Slack-style coaching feedback. Draft analysis only; do not claim Fireflies retrieval, Google Drive file creation, Slack send, wait step, or external action occurred."
>
> Deploy, run once, show me the objection table, missed discovery questions, next steps, and Slack-style coaching feedback draft.
>
> Leave the workflow deployed. Print the Web UI link.

***

#### 5. Maps Lead Enrichment (`maps-lead-enrichment-pack`)

Turn a list of local businesses into a prioritized, enriched lead list — each business scored on the signals that matter, with a suggested outreach angle. Organizes the data you provide; no live scraping.

> Using the AgenticFlow CLI, deploy the maps-lead-enrichment-pack blueprint. Use these local business rows:
>
> Each row: name, category, rating, number of reviews, website, city.
>
> Deploy, run once, show me the enriched and prioritized lead list — each business scored with the signals that matter and a suggested outreach angle.
>
> Leave the workflow deployed. Print the Web UI link.

***

### Get Started

* **Try AgenticFlow free:** <https://agenticflow.ai/>
* **Latest changelog:** <https://docs.agenticflow.ai/changelog>
* **Join our Discord:** <https://qra.ai/discord>
* **Found a bug?** Email <support@agenticflow.ai> with a reproducible case.


# Office Hour #50: Public Route Stability, Accessibility Sweep & MCP Reliability + Model Updates

### Quick Recap

Office Hour #50 focuses on stability and usability improvements across MCP onboarding, public/workspace routes, and production-facing interaction flows, while adding new model options to the catalog.

This release includes:

* New model availability in PixelML and AgenticFlow
* 7 practical Workflow Blueprint Prompts across unique business categories
* Stability fixes for custom MCP authentication and tool discovery
* Automatic token refresh for MCP connections when refresh tokens are still valid
* Clearer prompts and workflow controls for MCP connection readiness before chat
* Safer behavior for public routes and workspace entry surfaces
* Keyboard/accessibility improvements for high-usage management and builder pages

🎥 Watch the full session:

{% embed url="<https://www.youtube.com/watch?v=7-7KwCH-3o8>" %}

***

### What Changed & Why

#### 1. New Models Added Across PixelML and AgenticFlow

This release adds new model entries to expand execution options for workflows and agents:

* `xiaomi/mimo-v2.5-pro` (PixelML)
* `xiaomi/mimo-v2.5` (AgenticFlow)
* `GLM5.2` (PixelML)
* `mistralai/mistral-nemo` (AgenticFlow)

<figure><img src="/files/8mXY15Y5ekghhfxkWgDf" alt="Model selector showing new AgenticFlow models including MiMo V2.5 and Mistral Nemo"><figcaption><p>New model options appear in the agent model selector.</p></figcaption></figure>

Teams gain additional choices for balancing cost, speed, and quality in everyday builds.

**Model Evidence Notes**

The visuals below come from the model publishers or provider pages. They are useful for understanding why these models were added, but they should be read as external model evidence rather than AgenticFlow-run evaluation results.

| Model                    | Surface     | Why it matters                                                                                                                                                                    |
| ------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `xiaomi/mimo-v2.5-pro`   | PixelML     | Agentic coding and long-horizon tool-use model with 1M-token context. Xiaomi's model card lists a 1.02T-parameter MoE architecture with 42B active parameters.                    |
| `GLM5.2`                 | PixelML     | Long-horizon coding and agent model with 1M-token context and 128K max output, positioned by Z.ai around software engineering, MCP/tool-use, and multi-step automation workloads. |
| `xiaomi/mimo-v2.5`       | AgenticFlow | Native multimodal model with 1M-token context for image, video, audio, text, agent, and coding workflows.                                                                         |
| `mistralai/mistral-nemo` | AgenticFlow | Cost-efficient 12B open model option with 128K context and strong multilingual coverage for practical multilingual and lightweight agent workloads.                               |

<figure><img src="https://huggingface.co/XiaomiMiMo/MiMo-V2.5-Pro/resolve/main/assets/benchmark.jpg" alt="Official MiMo V2.5 Pro benchmark chart showing agentic coding, software engineering, and long-horizon benchmark results"><figcaption><p>MiMo V2.5 Pro benchmark evidence from the official XiaomiMiMo model card. Source: <a href="https://huggingface.co/XiaomiMiMo/MiMo-V2.5-Pro">XiaomiMiMo/MiMo-V2.5-Pro</a>.</p></figcaption></figure>

<figure><img src="https://cdn.bigmodel.cn/markdown/1781632244480plan2.png?attname=plan2.png" alt="Official GLM 5.2 coding benchmark chart from Z.ai"><figcaption><p>GLM-5.2 coding and long-horizon benchmark evidence from Z.ai. Source: <a href="https://docs.z.ai/guides/llm/glm-5.2">Z.ai GLM-5.2 guide</a>.</p></figcaption></figure>

<figure><img src="https://huggingface.co/XiaomiMiMo/MiMo-V2.5/resolve/main/assets/mimo-v2.5-multimodal-bench.png" alt="Official MiMo V2.5 multimodal benchmark chart"><figcaption><p>MiMo V2.5 multimodal benchmark evidence from the official XiaomiMiMo model card. Source: <a href="https://huggingface.co/XiaomiMiMo/MiMo-V2.5">XiaomiMiMo/MiMo-V2.5</a>.</p></figcaption></figure>

<figure><img src="https://huggingface.co/XiaomiMiMo/MiMo-V2.5/resolve/main/assets/mimo-v2.5-coding-bench.png" alt="Official MiMo V2.5 coding benchmark chart"><figcaption><p>MiMo V2.5 coding benchmark evidence from the official XiaomiMiMo model card. Source: <a href="https://huggingface.co/XiaomiMiMo/MiMo-V2.5">XiaomiMiMo/MiMo-V2.5</a>.</p></figcaption></figure>

<figure><img src="https://mistral.ai/_astro/20165ae8-c76a-4093-a5e9-4ece72e25ca7_JptKb.webp?dpl=6a3992cb2ff6f100081a30c6" alt="Official Mistral NeMo multilingual benchmark chart"><figcaption><p>Mistral NeMo multilingual benchmark evidence from Mistral AI. Source: <a href="https://mistral.ai/news/mistral-nemo/">Mistral NeMo announcement</a>.</p></figcaption></figure>

#### 2. Custom MCP Connections Are More Reliable After Auth

Several custom MCP setups could remain in an unstable state after OAuth, showing “Requires Auth” while tool discovery still failed.

This release improves the connection handling and verification path for custom MCP clients so authentication and tool visibility align more consistently after setup. MCP clients now proactively refresh tokens when a valid refresh token is available, reducing manual refresh steps and lowering connection downtime.

<figure><img src="/files/1M4Adw6JU6iSM3klDcY2" alt="Custom MCP server connected and active with its tools discovered"><figcaption><p>Custom MCP connections stay active with tools reliably discovered after auth.</p></figcaption></figure>

For teams building with external MCP endpoints, this reduces setup confusion and makes onboarding more predictable in day-to-day operations.

#### 3. Improved Chat and MCP UX for Agent Workflows

To make onboarding and chat startup faster, two UX updates were added:

* Agent workflows now surface clearer in-app guidance when a workflow requires an active MCP connection before chat can run.

<figure><img src="/files/gvfQNkTWniGlbogKqbBa" alt="Agent builder showing a missing-connection notice before chat can run"><figcaption><p>Agents now clearly flag when a required MCP connection is missing before chat.</p></figcaption></figure>

* MCP toggles now include an explicit visible-value on/off state in the header controls when adding connections, so users can immediately see whether they are exposing values or running in masked mode.

<figure><img src="/files/euR9s9hmy7hGPmQokQq6" alt="Add New MCP form with a visible-value on/off toggle on header values"><figcaption><p>A visible-value toggle now shows whether header values are exposed or masked.</p></figcaption></figure>

In addition, agent chat flow handling was updated so a new thread can be created automatically in context, rather than requiring users to manually create a fresh thread before continuing.

Finally, the chat interface now consistently uses the correct chat version marker, addressing the prior mixed display of v1/v2 labels in some situations.

#### 4. Public Route and Workspace Entry States Are More Deterministic

Some public pages and entry surfaces could show incomplete states when permissions or content context were not resolved correctly.

The platform now handles those edge cases more clearly so users are less likely to see broken shells or confusing behavior when entering:

* Public text editor route
* Admin area for non-admin access scenarios
* Public tools listing and tool detail pages

This brings the UI closer to a stable baseline for first-time checks and regular usage.

#### 5. Interaction and Accessibility Polishing Across Core Pages

This release also continues earlier accessibility work by improving the semantics and keyboard accessibility of frequently used interface controls across:

* Workflows and workflow step controls
* Datasets (create/list/detail)
* Tasks and agent rows
* Projects, API keys, audit logs, and marketplace actions
* Drive list actions and shared dialog/import controls
* Agent chat composer flow and connection-state messaging around required MCP links

The behavior remains the same, but control paths are more consistent and easier to navigate with keyboard interaction.

***

### Bug Fixes Included

* Fixed custom MCP setups that could still appear unauthenticated after successful OAuth flow completion
* Fixed MCP tool visibility mismatches in edge auth/discovery states
* Fixed frequent manual-token-refresh workflows by proactively refreshing MCP tokens when available and not expired
* Fixed unclear chat startup behavior when users attempted to run a workflow without a required MCP connection
* Fixed confusing on/off state visibility in MCP header controls when adding a new MCP connection
* Fixed missing/incorrect chat version labeling in agent chat UI (v1/v2 visibility)
* Fixed manual new-thread friction in agent chat by auto-creating a new thread when continuing an incomplete or stale thread state
* Fixed public `/text-editor` behavior to avoid exposing unfinished scaffold content
* Fixed non-deterministic admin and public route outcomes when access context is missing
* Fixed `/tools` and `/tools/[toolId]` handling for missing data contexts
* Fixed dataset detail handling when payload shape was incomplete or malformed
* Improved keyboard accessibility and discoverability for icon actions across high-traffic workspace surfaces
* Fixed a set of row and action controls to remove mouse-only interaction patterns in workflows, tasks, and dataset views

#### Before/After Evidence

Two of the bug-fix groups had clean before/after visual evidence available from the verification pass.

**Custom MCP Auth & Tool Discovery**

Before the fix, some OAuth-based custom MCP connections could return from provider authorization but still show `Authentication Required`, `Requires Auth`, and `0` tools.

<figure><img src="/files/0hP2fVBwOgJ6IlIshiO7" alt="Before fix: custom MCP connection shows Authentication Required, Requires Auth, and zero tools"><figcaption><p>Before: OAuth completed, but the MCP connection still required auth and exposed no tools.</p></figcaption></figure>

After the fix, the same class of custom MCP connection can stay active and expose discovered tools.

<figure><img src="/files/1M4Adw6JU6iSM3klDcY2" alt="After fix: custom MCP connection is active and tools are discovered"><figcaption><p>After: the MCP connection is active and discovered tools are available.</p></figcaption></figure>

**Dataset Detail Route Stability**

Before the fix, opening an existing dataset detail route could land on the generic error boundary.

<figure><img src="/files/cImQ3B4O9nxAIlzoYdRB" alt="Before fix: dataset detail route shows a Something went wrong error boundary"><figcaption><p>Before: dataset detail route crashed into the generic error boundary.</p></figcaption></figure>

After the fix, the dataset detail route renders the dataset surface instead of crashing when payloads are incomplete or inconsistent.

<figure><img src="/files/VaMFcR42yD014ymKBlHR" alt="After fix: dataset detail route loads without crashing"><figcaption><p>After: the dataset detail route loads without the generic crash state.</p></figcaption></figure>

### 🚀 7 Workflow Blueprint Prompts

Copy any prompt below into **Claude Code**, **Codex**, Cursor, or another AI coding agent with the **AgenticFlow CLI** installed to deploy a working workflow quickly. These examples cover seven distinct workflow categories: document processing, market risk, appointment recovery, sales operations, UX research, AI news digestion, and onboarding profile generation.

#### 1. Invoice Archive Extraction Packet (`invoice-archive-extraction-pack`)

Extract invoice metadata from an email, propose an archive filename and folder path, flag items that need review, and create finance handoff notes. This is a draft-only workflow; it does not upload files, send email, or write to external systems.

> Using the AgenticFlow CLI, deploy the invoice-archive-extraction-pack blueprint. Use this invoice email:
>
> Subject: Invoice INV-2026-118 from Northstar Events Hi team, please find attached invoice INV-2026-118 for the June customer summit venue deposit. Vendor: Northstar Events Ltd. Amount: USD 4,850. Due date: 2026-06-20. PO: PO-8842. Thanks, <billing@northstar-events.example>
>
> Archive policy: Extract invoice metadata, classify the document, propose an archive filename and folder path, and list review flags. Draft only; do not claim Gmail search, Drive upload, FTP transfer, Google Sheets save, or external action occurred.
>
> Deploy, run once, show me the extracted metadata table, proposed archive filename, proposed archive folder, review flags, and finance handoff notes.
>
> Leave the workflow deployed. Print the Web UI link. One-line note: why this rung of the composition ladder?

***

#### 2. Commodity Risk Brief Packet (`commodity-risk-brief-pack`)

Analyze commodity market signals, assess simple price-movement context, and create an operational risk brief with drivers, impacts, non-trading actions, and clear limitations.

> Using the AgenticFlow CLI, deploy the commodity-risk-brief-pack blueprint. Use these market signals:
>
> "Signal: Brent crude moved from 82.10 to 86.40 over 24h. Shipping: Red Sea delays reported. OPEC: no formal production change. News: refinery outage in one region. Internal exposure: logistics budget sensitive above 85."
>
> Risk policy: "Create operational risk brief with anomaly assessment, drivers, alert level, and non-trading actions. Do not provide investment advice or price predictions. Do not claim API fetch, OPEC report fetch, news feed fetch, Slack/email alert, dashboard write, or external action occurred."
>
> Deploy, run once, show me the executive summary, alert level, drivers, operational impacts, non-trading actions, and limitations.
>
> Leave the workflow deployed. Print the Web UI link. One-line note: why this rung of the composition ladder?

***

#### 3. No-Show Appointment Recovery (`no-show-appointment-recovery`)

Determine whether an appointment is a no-show, assess lead intent, package the recovery decision with timestamp context, and draft rescheduling outreach.

> Using the AgenticFlow CLI, deploy the no-show-appointment-recovery blueprint. Use this appointment record:
>
> "Lead: Marcus Reed. Meeting: pricing demo. Scheduled: 2026-06-04 09:00 America/New\_York. Current time: 2026-06-04 09:45 America/New\_York. Lead score: 87. Last activity: downloaded enterprise pricing guide. Owner: Jenna. Reschedule link: <https://cal.com/jenna/demo>"
>
> Recovery policy: "No-show if 30+ minutes past scheduled time. High intent if lead score above 75 or enterprise pricing activity. Send friendly reschedule message and alert owner for same-day follow-up."
>
> Deploy, run once, show me the no-show JSON, lead status, reschedule message, sales rep alert, same-day follow-up checklist, and escalation note.
>
> Leave the workflow deployed. Print the Web UI link. One-line note: why this rung of the composition ladder?

***

#### 4. Service Package Recommendation Packet (`service-package-recommendation-pack`)

Read a prospect inquiry, route it by budget band, and create a service-package recommendation packet with fit rationale, scoped deliverables, implementation plan, risks, next step, and email draft.

> Using the AgenticFlow CLI, deploy the service-package-recommendation-pack blueprint. Use this inquiry:
>
> "Company: Northstar Clinics | Contact: Elena Ramos | Need: automate patient feedback reporting and executive dashboards | Timeline: launch pilot in 45 days | Budget: 18000 USD | Notes: wants compliance review and staff training"
>
> Package rules: "Basic: under 8000 USD, discovery and lightweight prototype. Standard: 8000-20000 USD, workflow design, dashboard, and training. Premium: over 20000 USD, integrations, governance, rollout support, and executive reporting. Draft recommendations only; do not claim email send, Sheets update, Calendar event, or external action occurred."
>
> Deploy, run once, show me the selected package, fit reason, scoped deliverables, implementation plan, email draft, next step, and risks.
>
> Leave the workflow deployed. Print the Web UI link. One-line note: why this rung of the composition ladder?

***

#### 5. UX Research Plan Builder (`ux-research-plan-builder`)

Turn a research brief and constraints into a leadership-ready UX research plan, including research questions, methods, participant profile, interview guide, survey questions, and approval checklist.

> Using the AgenticFlow CLI, deploy the ux-research-plan-builder blueprint. Use this research brief:
>
> "Product: onboarding analytics dashboard. Audience: product managers at B2B SaaS companies. Hypothesis: users fail to act because activation metrics are scattered across too many tools. Decision: whether to build a guided onboarding insights module."
>
> Research constraints: "Timeline: 2 weeks. Sample: 8 customer interviews and 20 survey responses. Channels: existing customer advisory group and in-app intercept. Need a concise plan that can be approved by product leadership."
>
> Deploy, run once, show me the research questions, methods JSON, participant profile, interview guide, survey questions, approval checklist, and expected decision output.
>
> Leave the workflow deployed. Print the Web UI link. One-line note: why this rung of the composition ladder?

***

#### 6. AI News Digest Packet (`ai-news-digest-pack`)

Use a public news URL, filter for AI- or technology-relevant items, categorize and summarize them, and create a draft daily digest.

> Using the AgenticFlow CLI, deploy the ai-news-digest-pack blueprint. Use this news URL: <https://www.bbc.com/news/technology>
>
> Digest policy: Extract AI or technology-relevant items, categorize them, and write a concise daily digest. Draft only; do not claim ScrapeGraphAI scrape, Google Sheets save, Gmail send, batch split completion, or external action occurred.
>
> Deploy, run once, show me the digest title, categorized item table, concise summaries, why-it-matters notes, and editor notes.
>
> Leave the workflow deployed. Print the Web UI link. One-line note: why this rung of the composition ladder?

***

#### 7. Verified User Profile Card (`verified-user-profile-card`)

Take a user profile and visual style, validate the email, create an HTML profile card, render it as an image, and return delivery copy plus CRM/profile log fields.

> Using the AgenticFlow CLI, deploy the verified-user-profile-card blueprint. Use this user profile:
>
> "Name: Alex Rivera. Email: <alex@northstar.io>. Role: RevOps Manager. Company: Northstar Analytics. Bio: Builds automated reporting systems for go-to-market teams."
>
> Profile style: "Professional member profile card, clean white background, navy accent, readable name and role, no external assets."
>
> Deploy, run once, show me the validated profile fields, profile card URL, delivery email copy, verification status, and CRM/profile log fields.
>
> Leave the workflow deployed. Print the Web UI link. One-line note: why this rung of the composition ladder?

***

***

### Get Started

* **Try AgenticFlow free:** <https://agenticflow.ai/>
* **Latest changelog:** <https://docs.agenticflow.ai/changelog>
* **Join our Discord:** <https://qra.ai/discord>
* **Found a bug?** Email <support@agenticflow.ai> with a reproducible case.


# Office Hour #49: Safer Agent Chat, Protected Uploads & Model Cleanup

### 📺 Quick Recap

Office Hour #49 focuses on reliability and clarity in the places users feel most directly: chatting with agents, recovering from failed messages, moving uploads to time-limited signed links, and surfacing deprecated-model states clearly.

This release includes fixes for:

* Agent chat sessions that could become unresponsive
* Message streaming failures in the chat interface
* Continuing a conversation in the same thread after a failed message
* Deprecated model handling in agent chat
* Agent recursion-limit and runtime-error visibility
* Time-limited signed links for workflow and agent uploads
* `URL to Markdown` and `Web Scraping` node reliability issues

🎥 Watch the full session:

{% embed url="<https://www.youtube.com/watch?v=IxysLYdJsbY>" %}

***

### 🔍 What Changed & Why

#### 1. Agent Chat Is More Stable During Long-Running Conversations

Some users could hit a state where chatting with an agent made the browser difficult to recover from.

<figure><img src="/files/lZYpx58o4HhvK6s5I7oE" alt=""><figcaption></figcaption></figure>

This was one of the highest-impact fixes in this release because it affected the core agent conversation experience, not just a secondary settings page or edge workflow.

Agent chat is now more stable during long-running responses, tool-heavy conversations, and failure recovery. The interface is smoother, less likely to get stuck, and better at recovering when an agent run does not complete cleanly.

#### 2. Chat Streaming Failures Now Show Clear Notifications

When a message stream failed, the chat interface could leave users uncertain about whether the agent was still working, stuck, or already failed.

The chat interface now surfaces clear notifications for message streaming failures. If the previous message fails, the thread remains usable and users can continue chatting with the same agent in the same conversation instead of starting over.

This makes failures easier to understand and keeps the conversation context intact.

<figure><img src="/files/KIGbS5AFsXO4Kxfk2rTr" alt="Agent chat showing a clear failure message"><figcaption><p>After: failed chat states show a clear message instead of leaving the thread looking stuck.</p></figcaption></figure>

#### 3. Agent Runtime Errors Are Now Visible in Chat

Agent chat now gives clearer feedback when an agent cannot continue because of a runtime issue.

This includes cases where:

* The agent is configured with a deprecated model
* The agent reaches its recursion limit
* The agent encounters an error while processing the chat

Instead of failing silently or appearing stuck, the chat surface now displays the issue directly or shows a toast notification. Users can understand what happened and take the next step without guessing.

#### 4. Workflow and Agent Uploads Use Time-Limited Signed Links

Workflow and agent uploads now use temporary presigned URLs rather than long-lived direct file links.

Uploaded files now use expiring URLs:

* **Workflow uploads:** signed links expire after **6 hours**
* **Agent uploads:** signed links expire after **24 hours**

This narrows the access window for uploaded files and keeps link behavior aligned with the context in which each file is used.

#### 5. Deprecated Models Marked Across Providers

Several older model entries are now deprecated across providers. This cleanup reduces confusion in the model selector and helps prevent agents and workflows from being configured with models that are no longer reliable choices.

<figure><img src="/files/d5vSoOV1MRe2FQhPpa47" alt="Deprecated model badges in the model selector"><figcaption><p>Deprecated models are visibly marked in the model selector.</p></figcaption></figure>

**PixelML Provider**

* `pixelml/gemini-2.0-flash`
* `pixelml/deepseek-chat`
* `pixelml/deepseek-reasoner` (R1-0528)
* `pixelml/deepseek-v3.2-exp`

**AgenticFlow Provider**

* `agenticflow/gemini-2.0-flash`
* `agenticflow/gemini-2.0-flash-lite`
* `agenticflow/google-gemini-1.5-flash`
* `agenticflow/deepseek-v3`
* `agenticflow/deepseek-v3.2-exp`

**Google Gen AI Provider**

* `google_gen_ai/gemini-2.0-flash`
* `google_gen_ai/gemini-2.0-flash-lite`

**DeepSeek Provider**

* `deepseek/deepseek-chat`
* `deepseek/deepseek-reasoner`

If an agent is still using a deprecated model, AgenticFlow now surfaces that state in the chat experience so users can update the model instead of interpreting the failure as a generic agent issue.

#### 6. `URL to Markdown` and `Web Scraping` Nodes Are More Reliable

This release also includes fixes for workflow node behavior in `URL to Markdown` and `Web Scraping`.

<figure><img src="/files/5XnqJdWkGfBiUioTHrOo" alt=""><figcaption></figcaption></figure>

The affected nodes now handle scraping and conversion flows more reliably, reducing failed runs and improving stability for workflows that depend on web content extraction.

<figure><img src="/files/362NJjzCNd48oJG3OZyV" alt="Workflow run logs showing successful web content retrieval and content brief generation"><figcaption><p>After: a workflow using web retrieval successfully fetches the Office Hour #49 changelog URL and completes the downstream generation step.</p></figcaption></figure>

***

### Bug Fixes Included

* Improved recovery behavior for unresponsive agent chat sessions
* Added notifications for message streaming failures in chat
* Preserved thread usability after a failed chat message
* Improved agent chat stability and recovery behavior
* Added visible feedback when an agent uses a deprecated model
* Added visible feedback for agent recursion-limit failures
* Added toast notifications for agent chat runtime errors
* Protected workflow uploads with signed URLs expiring after 6 hours
* Protected agent uploads with signed URLs expiring after 24 hours
* Deprecated older Gemini and DeepSeek model entries across PixelML, AgenticFlow, Google Gen AI, and DeepSeek providers
* Fixed reliability issues in the `URL to Markdown` workflow node
* Fixed reliability issues in the `Web Scraping` workflow node

***

#### 🚀 7 Workflow Blueprint Prompts <a href="#id-6-workflow-blueprint-prompts" id="id-6-workflow-blueprint-prompts"></a>

**1. Learning Content Curator Workflow**

> Using the AgenticFlow CLI, deploy the learning-content-curator blueprint. Learning topic: "agentic workflows for operations teams".
>
> Audience: "Operations managers who understand no-code automation but are new to agentic workflow design."
>
> Deploy, run once, show me the curated resources JSON, recommended first 3 resources, 7-day learning path, key concepts, practical exercise, and gaps to fill later.
>
> Leave the workflow deployed. Print the Web UI link.\
> One-line note: why this rung of the composition ladder?

***

**2. Convert ticket summary escalation workflow blueprint**

> Using the AgenticFlow CLI, deploy the ticket-summary-escalation-pack blueprint. Use this ticket thread:
>
> "Ticket #8942 | Customer: Brightline Health | Plan: Enterprise | Thread: Customer reports dashboard exports failing for finance users since Monday. Agent suggested clearing cache; issue persists. Customer says quarter-end report is blocked and asks for escalation. Last error: export job failed after 3 retries."
>
> Summary policy: "Summarize issue, sentiment, urgency, likely owner, missing context, and Slack-style escalation note. Do not claim Zendesk, Pinecone, Slack, ticket updates, or customer messages occurred."
>
> Deploy, run once, show me issue summary, customer sentiment, urgency, likely owner, missing context, and escalation note draft.
>
> Leave the workflow deployed. Print the Web UI link.\
> One-line note: why this rung of the composition ladder?

***

**3. Convert visitor entry pass workflow blueprint**

> Using the AgenticFlow CLI, deploy the visitor-entry-pass-pack blueprint. Use this visitor request:
>
> "Visitor: Aisha Morgan | Email: <aisha.morgan@example.com> | Host: Priya Shah | Visit date: 2026-06-12 | Office: SF HQ | Purpose: vendor security review | ID check: passport verified by reception | Badge type: day pass"
>
> Entry policy: "Require visitor name, valid email, host, date, office, purpose, ID check, and badge type. Draft entry pass text, host notification draft, and security checklist. Do not claim email verification, badge generation, Slack, Gmail, or access-control updates occurred."
>
> Deploy, run once, show me status, missing fields, entry pass text, host notification draft, and security checklist.
>
> Leave the workflow deployed. Print the Web UI link.\
> One-line note: why this rung of the composition ladder?

***

**4. Convert sales anomaly detector workflow blueprint**

> Using the AgenticFlow CLI, deploy the sales-anomaly-detector-pack blueprint. Use these sales rows:
>
> "Category: Subscriptions | Current week: 84200 | Baseline week: 80100 | Transactions: 316\
> Category: Services | Current week: 18400 | Baseline week: 35600 | Transactions: 22\
> Category: Hardware | Current week: 12600 | Baseline week: 11900 | Transactions: 41"
>
> Anomaly policy: "Flag category movement above 25% up or down. Calculate percentage change, identify possible investigation questions, and draft finance alert email. Do not claim QuickBooks, Gmail, accounting updates, or email delivery occurred."
>
> Deploy, run once, show me category movement table, detected anomalies, investigation questions, and finance alert email draft.
>
> Leave the workflow deployed. Print the Web UI link.\
> One-line note: why this rung of the composition ladder?

***

**5. Add Tax Deadline Compliance Pack workflow blueprint**

> Using the AgenticFlow CLI, deploy the tax-deadline-compliance-pack blueprint. Use this tax calendar:
>
> "Entity: Acme Robotics LLC | Jurisdiction: California and federal US | Upcoming: 2026-06-15 federal estimated tax payment; 2026-07-31 quarterly payroll filing; 2026-08-15 sales tax return | Owner: Finance Ops | Notes: payroll filing data is missing contractor classification review"
>
> Company profile: "Series A hardware startup with 42 employees, multi-state sales, and external CPA review. Do not provide legal or tax advice; prepare operational reminders, risk flags, and CPA questions only."
>
> Deploy, run once, show me the deadline table, risk summary, missing inputs, CPA questions, and internal action checklist.
>
> Leave the workflow deployed. Print the Web UI link.\
> One-line note: why this rung of the composition ladder?

***

**6. Sales Leaderboard Coach Workflow**

> Using the AgenticFlow CLI, deploy the sales-leaderboard-coach blueprint. Use these deal rows:
>
> "Ava | Closed Won | $18,000 | New business\
> Ben | Closed Won | $12,500 | Expansion\
> Ava | Proposal | $22,000 | New business\
> Mia | Closed Won | $9,000 | Renewal\
> Ben | Lost | $7,500 | New business"
>
> Team context: "Period: first week of June 2026. Team target: $60,000 closed won. Tone: motivating but honest, celebrate wins and call out next best actions."
>
> Deploy, run once, show me the deal summary, leaderboard JSON, leaderboard table, team progress, rep coaching notes, Slack message, and next-best actions.
>
> Leave the workflow deployed. Print the Web UI link.\
> One-line note: why this rung of the composition ladder?

***

**7. Daily Verse Email Workflow Blueprint**

> Using the AgenticFlow CLI, deploy the daily-verse-email blueprint. Use these inputs:
>
> Reflection focus: encouragement for a busy workday\
> Recipient email: your own email
>
> Deploy, run once, show me the devotional email body, subject line, and send confirmation.
>
> Leave the workflow deployed. Print the Web UI link.\
> One-line note: why this rung of the composition ladder?

***

### Get Started

* **Try AgenticFlow free:** <https://agenticflow.ai/>
* **Latest changelog:** <https://docs.agenticflow.ai/changelog>
* **Join our Discord:** <https://qra.ai/discord>
* **Found a bug?** Email <support@agenticflow.ai> with a reproducible case.


# Office Hour #48: Gemini 3.5 Flash, Trigger Reliability & UI Stability

### 📺 Quick Recap

Office Hour #48 brings a new model addition alongside a stability-focused release that resolves a full set of user-facing workflow and workspace issues affecting debugging accuracy, run traceability, connection discoverability, and mobile usability.

This release includes:

* **Gemini 3.5 Flash** added to the PixelML Provider

And fixes for:

* Workflow run detail inputs rendering incorrectly for integer fields
* Workflow run provenance label mismatch on detail pages
* `Test input` navigation from Workspace History routing to an invalid destination
* OpenAI-compatible provider count/detail mismatch behavior
* Marketplace mobile launcher overlap and accessibility issue
* Trigger edit modal not reflecting saved schedule values
* Workspace-wide agent memory retrieval issues

🎥 Watch the full session:

{% embed url="<https://www.youtube.com/watch?v=DLB4ik8FOok>" %}

***

### ✅ Release Highlights

* **Gemini 3.5 Flash is now available via PixelML Provider.** Google's fast, cost-efficient multimodal model is now accessible directly in AgenticFlow — no extra setup required.
* **Workflow run debugging is now more reliable.** Run details now display integer inputs correctly and preserve trigger provenance labels.
* **History retest flow is now usable.** `Test input` now routes users to the correct workflow target.
* **Connections are more discoverable and consistent.** OAuth categories and OpenAI-compatible provider views now align with expected management flows.
* **Mobile Marketplace interactions are safer.** Floating launcher overlap and accessibility naming issues were addressed.
* **Agent scheduling and memory continuity are improved.** Trigger Editor now reflects saved values, and memory retrieval works consistently in affected setups.

### 🔍 What Changed & Why

#### 1. Gemini 3.5 Flash Now Available via PixelML Provider

Google's **Gemini 3.5 Flash** is now available in AgenticFlow through the **PixelML Provider**.

Gemini 3.5 Flash is a fast, cost-efficient multimodal model with a large context window — well suited for high-throughput workflows, document analysis, and tasks where response speed matters.

To use it, open the Model Selector, select **PixelML** from the provider list, and choose **Gemini 3.5 Flash** from the model list.

***

#### 2. Workflow Run Detail Now Correctly Displays Integer Inputs

Workflow run detail pages could show some number fields as blank, even when valid values were used in the run.

This made run reproduction and debugging less reliable because the UI did not reflect the actual input used to execute the run.

Run detail now displays those number fields correctly in the Inputs card.

**Before**

![](/files/rTSDuiDusYpVqJS89SaY)

**After (current capture)**

![](/files/HcCspUJARsVwX7mFVuxz)

#### 3. Workflow Run Detail Now Preserves API Key Trigger Provenance

Some workflow runs triggered by API key were labeled as `Anonymous User` on the detail page, while History showed the correct trigger source.

This provenance mismatch could mislead incident reviews, support handoff, and audit/debug workflows.

Trigger labels are now consistent between History and Detail views.

**Before**

![](/files/rTSDuiDusYpVqJS89SaY)

**After (current capture)**

![](/files/HcCspUJARsVwX7mFVuxz)

#### 4. Workspace History `Test input` Now Routes to a Usable Target

From Workspace History, clicking `Test input` could route users to a page that returned `Workflow not found`.

The action appeared available but opened an invalid destination, preventing users from quickly re-testing inputs from a run row.

Navigation has been fixed so `Test input` opens a usable destination in workspace context.

**Before**

![](/files/lbDfF1ZhUSdajge9LWVQ)

**After (current capture)**

![](/files/CzYmV5Ij5EhcoyJw5gqv)

#### 5. OpenAI-Compatible Provider Management View Is Now Consistent with Reported State

The Connections list could report OpenAI-compatible providers as connected, while the provider detail page showed no corresponding provider rows.

This created a data-consistency gap between summary and detail views and made provider management unclear.

The OpenAI-compatible provider surface has been aligned so list-level status and detail-level manageability are consistent.

**Before**

![](/files/3XmTDJY7oJaLbEH64Nqg)

**After (current capture)**

![](/files/C24KUEobOQa53OghuxxL)

#### 6. Marketplace Mobile Launcher No Longer Obstructs Primary CTA

On mobile viewport widths, the floating support/chat launcher could overlap the Marketplace template `Download` CTA, partially blocking tap area.

The launcher button also lacked an accessible name, creating an accessibility issue on a primary acquisition surface.

Mobile spacing and launcher accessibility semantics have been improved so the CTA remains unobstructed and launcher controls are screen-reader friendly.

**Before**

![](/files/zAQLxS9CNNrbqoz9qt0a)

**After (current capture)**

![](/files/oJLrfOAvawWI6jFcYzif)

#### 7. Trigger Edit Modal Now Reflects Saved Selection

When editing an existing scheduled trigger, the modal could open with default values instead of the saved trigger configuration.

The outer agent view still showed the correct saved trigger, but modal initialization mismatch prevented confident editing and caused confusion about real run cadence.

The Trigger Editor now opens with the saved schedule values so users always edit the true current setup.

![](/files/0raWNQCcXbmVF77cR2gR)

#### 8. Workspace-Wide Agent Memory Retrieval Restored

In affected workspace scenarios, agents could miss stored memory context across conversations.

The issue affected multiple agents in those workspaces and could require users to repeat context manually.

Memory retrieval behavior has been improved so agents can consistently access stored context in ongoing threads.

![](/files/g7Kq2UKyilYdT4CghyQK)

***

### 🐛 Bug Fixes Included

* Fixed integer workflow inputs rendering as blank on run detail pages
* Fixed API-key-triggered runs being mislabeled as `Anonymous User` on detail pages
* Fixed `Test input` routing from Workspace History to invalid embed targets
* Fixed OpenAI-compatible provider list/detail consistency for provider visibility and management
* Fixed Marketplace mobile launcher overlap with primary `Download` CTA
* Fixed missing accessibility naming for floating launcher controls on mobile surfaces
* Fixed Trigger Editor modal initialization mismatch with saved schedule values
* Fixed workspace-wide agent memory retrieval issues in affected setups

***

#### 🚀 5 Workflow Blueprint Prompts <a href="#id-6-workflow-blueprint-prompts" id="id-6-workflow-blueprint-prompts"></a>

Copy any of the prompts below into **Claude Code / Codex / Ishi** (with the **AgenticFlow CLI** installed) to deploy a fully working workflow in minutes — no manual node-wiring required.

**1. Content Brief from URL**

> Using the AgenticFlow CLI, deploy the content-brief blueprint. Source URL: <https://www.paulgraham.com/startupideas.html>. Target audience: early-stage founders. Content goal: rank for keyword "how to find startup ideas".
>
> Deploy, run once, show me the full brief including angle, outline, and SEO keywords.
>
> Leave the workflow deployed. Print the Web UI link.\
> One-line note: why this rung of the composition ladder?

***

**2. Pricing Page Analyser**

> Using the AgenticFlow CLI, deploy the pricing-page-analyser blueprint. Analyse <https://www.notion.so/pricing>.
>
> Deploy, run once, show me the tiers table, pricing psychology breakdown, and conversion optimisation checklist.
>
> Leave the workflow deployed. Print the Web UI link.\
> One-line note: why this rung of the composition ladder?

***

**3. Onboarding Email Sequence**

> Using the AgenticFlow CLI, deploy the onboarding-email-sequence blueprint. Use these inputs:
>
> Product: Notion — an all-in-one workspace for notes, docs, tasks, and databases.\
> User persona: freelance designer who just signed up for a free trial.\
> Aha moment: first project page created with a template.\
> Sender: The Notion Team
>
> Deploy, run once, show me all 5 emails (Day 0 to Day 14).
>
> Leave the workflow deployed. Print the Web UI link.\
> One-line note: why this rung of the composition ladder?

***

**4. SEO Meta Writer**

> Using the AgenticFlow CLI, deploy the seo-meta-writer blueprint. Page URL: <https://posthog.com/blog/what-is-product-analytics>. Primary keyword: "product analytics". Brand: PostHog.
>
> Deploy, run once, show me the title tag options, meta descriptions, OG copy, and H1 recommendation.
>
> Leave the workflow deployed. Print the Web UI link.\
> One-line note: why this rung of the composition ladder?

***

**5. Performance Review Drafter**

> Using the AgenticFlow CLI, deploy the perf-review-drafter blueprint. Use these inputs:
>
> Employee: Alex Chen | Role: Product Designer | Period: Q1 2025\
> Achievements: Led onboarding redesign (+22% activation). Delivered 3 feature designs on time. Ran 8 user research sessions.\
> Areas to improve: Needs clearer stakeholder communication. Could be more proactive cross-team.\
> Goals next period: Ship mobile redesign by Q2. Run monthly design critiques.\
> Rating: Exceeds expectations | Reviewer: Sarah Manager | Email: <your@email.com>
>
> Deploy, run once, show me the full review and confirm the email was sent.
>
> Leave the workflow deployed. Print the Web UI link.\
> One-line note: why this rung of the composition ladder?

***

### 🔗 Get Started

* **Try AgenticFlow free:** <https://agenticflow.ai/>
* **Latest changelog:** <https://docs.agenticflow.ai/changelog>
* **Join our Discord:** <https://qra.ai/discord>
* **Found a bug?** Email <support@agenticflow.ai> with a reproducible case.


# Office Hour #47: Model Selector Overhaul & Smarter Chat

### 📺 Quick Recap

Office Hour #47 focused on a major **Model Selector redesign** and a set of targeted **Chat improvements** — making it easier than ever to find the right model, understand its capabilities at a glance, and attach files intelligently.

Here's what shipped:

**Model Selector**

* Redesigned **3-column layout** — provider list, model list, and model settings always visible side by side
* **Max Input / Max Output token counts** displayed for every model
* **Vision** and **Reasoning** capability icons shown inline next to model names
* **Provider icons** in the left-hand provider list for faster visual scanning
* Automatic scroll to the currently selected model when the selector opens

**Chat**

* Image uploads are now **restricted to Vision-capable models** only, with clearer capability feedback
* Added support for **.json file attachments**
* File attachments now render as **cards** (file name + type) instead of raw text

**Bug Fixes**

* Agent chat handles file attachments more reliably
* Unsupported file types and oversized files are now filtered before sending
* Telegram publishing integration restored after a service disruption

🎥 Watch the full session:

{% embed url="<https://youtu.be/ZaO1WpdjjRI?si=rZHbGMc4SK_GWtNe>" %}

**Overview:** This release reshapes the **Model Selector** — the surface every agent and chat session passes through — into a three-panel layout that keeps the provider list, model list, and tuning controls visible at the same time. Each model now surfaces its **Max Input / Max Output token counts** and inline **Vision** / **Reasoning** capability badges, so capability discovery happens before you commit to a conversation. On the chat side, image uploads are now gated to Vision-capable models, `.json` attachments are supported, and file attachments render as cards instead of raw text. Plus a cluster of fixes that improve file attachment handling and the Telegram publishing integration.

#### 🎛️ Model Selector — New 3-Column Layout <a href="#model-selector-new-3-column-layout" id="model-selector-new-3-column-layout"></a>

<figure><img src="/files/fedizaP0xU3miz30alEU" alt=""><figcaption></figcaption></figure>

* **Three panels, always visible.** Provider list on the left, model list in the center, model settings (Temperature, Max Output, Max Input) on the right — no more stacking or collapsing. Compare models across providers and tune parameters without losing your place in the list.
* **Token limits surfaced inline.** Each model shows its **Max Input** and **Max Output** counts directly in the selector, so context-window questions get answered before you start the conversation.​![](/files/hRH9EGUPOpCnn3I9N1gk)
* **Vision & Reasoning capability badges.** Two new inline icons appear next to every model name — 👁 **Vision** for image input support and 🧠 **Reasoning** for extended chain-of-thought. Capability discovery is instant, especially for newer or less-familiar models.​​![](/files/CvbXF00XBjRdLZrnzXzs)![](/files/ot7zITwGQkhj8GFINK4W)
* **Provider icons in the left panel.** Faster visual scanning when picking among the dozens of providers wired into AgenticFlow.![](/files/DSCwHs9t2Uyz56bmsCS1)

​

* **Auto-scroll to the active model.** Opening the selector now jumps the center panel to whichever model is currently selected, instead of dropping you at the top of the list.

#### 💬 Chat Improvements <a href="#chat-improvements" id="chat-improvements"></a>

* **Image uploads gated to Vision-capable models.** The image attachment button is disabled when the active model lacks the Vision badge, so users can pick a compatible model before sending an image. Switch to any 👁 Vision model to attach images.![](/files/ZjYTLkJKD7j2aM2iMT7D)

​​

* **`.json` file attachments supported.** Pass structured data — API responses, configuration payloads, dataset samples — directly into a conversation without copy-pasting.![](/files/ywQ8cCuffRy3XkwLrOUB)

​​\* **File attachments render as cards.** Attached files now appear as compact cards showing the file name and type label, replacing the previous raw-text rendering that was easy to lose track of in longer threads.

#### 🐞 Bug Fixes & Stability

* **File attachments in agent chat are more reliable.** Agent conversations now continue normally when a supported file is attached.
* **Unsupported file types and oversized files are filtered before send.** Unsupported formats and over-limit files are caught at upload time with clear feedback. Supported attachment types in agent chat: plain text, PDF, images (on Vision-capable models), JSON, and common document formats, within the per-file size limit.
* **Telegram publishing restored.** The connection has been restored; Telegram remains a fully supported publishing channel for agent outputs and workflow triggers.

![](/files/hpbTtr9tWRN2N7OOXtWU)\
![](/files/Vozf1yae4ghDbOXyZ9XM)

***

#### 🚀 6 Workflow Blueprint Prompts <a href="#id-6-workflow-blueprint-prompts" id="id-6-workflow-blueprint-prompts"></a>

Copy any of the prompts below into **Claude Code** (with the **AgenticFlow CLI** installed) to deploy a fully working workflow in minutes — no manual node-wiring required.

**1. RSS Digest → Email**

> Using the AgenticFlow CLI, deploy the rss-digest-email blueprint. Use the Hacker News RSS feed (<https://hnrss.org/frontpage>) as the source. Set topic to "Hacker News", max\_items to 5, and recipient\_email to your own email.
>
> Deploy, run once, show me the 5-item digest that was generated.
>
> Leave the workflow deployed. Print the Web UI link. One-line note: why this rung of the composition ladder?

***

**2. Job Description Writer**

> Using the AgenticFlow CLI, deploy the job-description-writer blueprint. Use these inputs:
>
> Role: Senior Data Engineer | Seniority: Senior\
> Responsibilities: Design and maintain data pipelines. Build ETL workflows in Python. Own data quality monitoring.\
> Stack: Python, Spark, dbt, Snowflake, Airflow, AWS\
> Company blurb: Series B fintech building real-time credit risk infrastructure.\
> Location: Remote (US/EU)
>
> Deploy, run once, show me the full job description.
>
> Leave the workflow deployed. Print the Web UI link.\
> One-line note: why this rung of the composition ladder?

***

**3. Contract Reviewer**

> Using the AgenticFlow CLI, deploy the contract-reviewer blueprint. Paste in this clause-heavy freelancer contract:
>
> "Payment: Client will pay within 90 days of invoice. IP Ownership: All work product including pre-existing tools shall be exclusive property of Client. Termination: Client may terminate without notice or payment for delivered work. Non-Compete: Provider shall not work in any industry for 2 years post-termination. Liability cap: $100."
>
> Party role: Service Provider (Freelancer). Jurisdiction: California, USA.
>
> Output scope: operational red flags and questions for counsel only. Do not provide legal advice.
>
> Deploy, run once, show me the red flags and negotiation checklist.
>
> Leave the workflow deployed. Print the Web UI link.\
> One-line note: why this rung of the composition ladder?

***

**4. Invoice Parser**

> Using the AgenticFlow CLI, deploy the invoice-parser blueprint. Parse this invoice text:
>
> "Invoice #INV-2025-0042 | Date: May 15 2025 | Due: June 14 2025\
> From: Acme Design Studio, <billing@acmedesign.com>\
> To: TechCorp Inc.\
> UI/UX Design (40h × $150) = $6,000 | Prototype Dev (20h × $150) = $3,000 | Revisions (5h × $150) = $750\
> Subtotal: $9,750 | Tax 8.5%: $828.75 | Total: $10,578.75 | Net 30"
>
> Currency: USD.
>
> Deploy, run once, show me the extracted JSON fields.
>
> Leave the workflow deployed. Print the Web UI link.\
> One-line note: why this rung of the composition ladder?

***

**5. Changelog Writer**

> Using the AgenticFlow CLI, deploy the changelog-writer blueprint. Use these raw commits:
>
> "feat: add dark mode toggle to settings\
> fix: login button unresponsive on mobile Safari\
> feat: export dashboard data to CSV\
> fix: websocket cleanup in connection handler\
> perf: reduce initial bundle size by 35% with code splitting\
> feat: add two-factor authentication via SMS and authenticator app"
>
> Version: v2.5.0. Product: MyApp. Audience: end users.
>
> Deploy, run once, show me the formatted changelog.
>
> Leave the workflow deployed. Print the Web UI link.\
> One-line note: why this rung of the composition ladder?

***

**6. Email Classify & Draft Reply**

> Using the AgenticFlow CLI, deploy the email-classify-reply blueprint. Use this inbound email:
>
> "Hi, I signed up for the Pro plan last week but I was charged twice on my credit card. Please check and correct the duplicate charge. My account email is <john@acme.com> — John"
>
> Sender: John | Your name: Support Team | Company: SaaS Co.
>
> Deploy, run once, show me the classification JSON and the drafted reply.
>
> Leave the workflow deployed. Print the Web UI link.\
> One-line note: why this rung of the composition ladder?

***

### 🔗 Get Started

* **Try AgenticFlow free:** <https://agenticflow.ai/>
* **Model library overview:** <https://docs.agenticflow.ai/>
* **Latest changelog:** <https://docs.agenticflow.ai/changelog>
* **Join our Discord:** <https://qra.ai/discord>
* **Found a bug?** Email <support@agenticflow.ai> with a reproducible case — the team will prioritize it.


# Office Hour #46: Recap & Workflow Blueprint Prompts

### 📺 Quick Recap

April's frontier model wave landed fast. In Office Hour #46, Sean walked through **Claude Opus 4.7, GPT-5.5, and DeepSeek V4 Pro + V4 Flash** inside AgenticFlow, then stress-tested them with a one-prompt **ISS Orbital Tracker** demo.

We also covered:

* **Time-aware workspace updates** – timezone standardization & Tasks-tab timestamps
* **Advanced MCP authentication** & Composio MCP deprecation
* **Stability fixes** across the platform
* **DeepSeek migration notes** – legacy DeepSeek models should migrate to **DeepSeek V4 Flash before May 31, 2026**
* **6 practical Claude Code + AgenticFlow CLI workflow demos** for everyday business automation

🎥 Watch the full session:

{% embed url="<https://www.youtube.com/watch?v=4AGjuzmjcks>" %}

**Overview:** April brought a back-to-back cluster of frontier model launches — **Claude Opus 4.7** (16 Apr), **GPT-5.5** (23 Apr), and **DeepSeek V4 Pro + V4 Flash** (24 Apr). All four are wired into AgenticFlow within days of release, so you can swap them into existing agents and workflows without changing a line of configuration. On the engine side, this release continues the timezone work documented in #45, ships the advanced MCP auth options builders have been asking for, and removes Composio MCP after upstream routing changes.

### 🧠 New Frontier Models

* **Claude Opus 4.7 — the new coding leader.** Anthropic's April release jumps to **87.6% on SWE-bench Verified** (up from 80.8% on Opus 4.6) and **64.3% on SWE-bench Pro**, putting it ahead of GPT-5.4 (57.7%) and Gemini 3.1 Pro (54.2%) on real-world software engineering. Reach for Opus 4.7 as the default model on long-horizon agent loops, multi-file refactors, code review, and any workforce slot where the agent needs to plan, call tools repeatedly, and recover from its own mistakes. Same $5/$25 per-million pricing as Opus 4.6.
* **GPT-5.5 — the operator and tool-call champion.** OpenAI's late-April release dominates agentic execution benchmarks: **82.7% on Terminal-Bench 2.0** (vs. Opus 4.7 at 69.4% and Gemini 3.1 Pro at 68.5%), **78.7% on OSWorld-Verified**, and **98.0% on Tau2-bench Telecom** for customer-service workflows. Available via the standard OpenAI provider at $5/$30 per million with a 1M-token context window. Best when an agent has to drive a real shell, click through web environments, or run long customer-facing dialog trees.
* **DeepSeek V4 Flash on the AgenticFlow provider — the new default.** The 284B/13B-active model is available directly under our AgenticFlow provider with no extra setup, and its quality is already at the peak we'd previously have split between two tiers: **79.0% on SWE-bench Verified**, **91.6% on LiveCodeBench**, and reasoning strong enough to retire the old `deepseek-reasoner` slot. Use V4 Flash as your default DeepSeek model — chat, coding, reasoning, bulk classification, content generation, lightweight tool-using agents — there's no longer a reason to split.
* **DeepSeek V4 Pro on the PixelML provider — frontier-tier for specialized work.** New 1.6T-parameter MoE (49B active), lands as the **#2 open-weights reasoning model** on the Artificial Analysis Intelligence Index. The efficiency story: at 1M-token context, V4 Pro uses **\~27% of the inference FLOPs and \~10% of the KV cache** compared to V3.2. Reach for V4 Pro only when you have a specialized frontier-tier workload — extreme long-context reasoning, research-grade analysis, or evals where the very top of the open-weights leaderboard matters. For day-to-day work, V4 Flash is the right call.
* **Practical heads-up on DeepSeek V4.** DeepSeek's own evals show V4 Pro / V4 Flash answer with high confidence even when they don't know (94–96% answer rate on AA-Omniscience). Pair them with retrieval (Knowledge tab) or grounding tools when factual accuracy is load-bearing.
* **⚠️ Legacy DeepSeek models retiring 31 May 2026 (PST).** The previous-generation API model IDs — `deepseek-chat`, `deepseek-reasoner`, and the **DeepSeek V3.2 / V3.2 Speciale / V3.2 Exp** entries — are scheduled for retirement after **May 31, 2026 (PST)**. Migrate every one of them to **DeepSeek V4 Flash** — its quality already covers both the previous chat and reasoner slots, so there's no need to split your fleet. Reach for **V4 Pro** only when you have a specialized frontier-tier workload that genuinely needs the larger model. The DeepSeek base URL and your existing API key stay the same — only the model field changes.

<figure><img src="/files/mRC7UVTJbQiFQGX1KsDW" alt=""><figcaption></figcaption></figure>

### 🌍 Global Consistency & User Experience

* **Platform-wide timezone standardization.** We've completely overhauled how time is calculated and displayed across the platform. Every timestamp now dynamically syncs with your browser's local timezone instead of defaulting to UTC — drastically reducing confusion when reading chat history, scheduled triggers, or task logs.
* **Precise chat history tracking.** Messages and activity logs in Chat History are now mapped to your exact local time down to the minute. When an agent runs a scheduled task, the time reflected in the chat matches your real-time expectation — no mental math, no UTC offset arithmetic.

<figure><img src="/files/bpLj6fdPfCugnqDzIdJn" alt=""><figcaption></figcaption></figure>

* **Streamlined Tasks-tab timestamps.** Automated task execution logs in the new Tasks tab now mirror the same local timezone used in the chat interface. Cross-referencing "when did this trigger actually fire" against a chat thread is finally a single glance instead of a calculation.

#### 🔐 Integrations & Security <a href="#integrations-and-security" id="integrations-and-security"></a>

* **Advanced MCP authentication protocols.** Building custom integrations is now more flexible: you can configure API key authentication directly via custom HTTP headers (e.g. `x-api-key: your_key_here`) rather than being locked into a single bearer-token shape. This unblocks every internal API and self-hosted MCP server that uses provider-specific header conventions.

<figure><img src="/files/xMpOrFlu1EkMmbh1A4W0" alt=""><figcaption></figcaption></figure>

* **Composio MCP deprecated.** We removed the Composio MCP integration after the provider changed their core routing endpoints. If you had Composio-routed tools in a workflow, swap them for the equivalent direct integration — most are already available natively in the Marketplace.

#### 🐞 Bug Fixes & Stability <a href="#bug-fixes-and-stability" id="bug-fixes-and-stability"></a>

* **Knowledge retrieval setting now persists on reload.** Fixed a state mismatch in Agent settings where toggling "Automatic Knowledge Retrieval" to ON would visually reset to OFF on a browser tab reload, even though the value was correctly saved server-side. The UI now reflects the true database state on every reload.

<figure><img src="/files/i4q5gjr1Qa5ehKAsDt5Y" alt=""><figcaption></figcaption></figure>

* **Workflow `.json` round-trip integrity.** Fixed a serialization issue affecting workflow migration. Workflows downloaded as `.json` from AgenticFlow now upload back into any other workspace cleanly, preserving node fields through the import flow.

<figure><img src="/files/i6cht3CFJXbqp9SU6rcc" alt=""><figcaption></figcaption></figure>

***

### 🚀 6 Workflow Blueprint Prompts

Copy any of the prompts below into **Claude Code** (with the **AgenticFlow CLI** installed) to deploy a fully working workflow in minutes — no manual node-wiring required.

#### 1. Email → Structured Data

> Using the AgenticFlow CLI, deploy the email-to-structured blueprint. Use this sample email as input:
>
> "Hi, I ordered the Pro plan last Tuesday (order #48291) and need help locating the activation key for my team. Can someone point me to the next step? — James"
>
> Deploy, run once, show me the extracted JSON (intent, urgency, category, entities, summary, suggested action).
>
> Leave the workflow deployed. Print the Web UI link. One-line note: why this rung of the composition ladder?

***

#### 2. Competitor URL Snapshot

> Using the AgenticFlow CLI, deploy the competitor-url-snapshot blueprint. Use [https://notion.so](https://notion.so/) as the competitor URL. Set your product to "a lightweight project management tool for solo founders".
>
> Deploy, run once, show me the positioning analysis, top 5 claims, weaknesses, and 3 counter-moves.
>
> Leave the workflow deployed. Print the Web UI link. One-line note: why this rung of the composition ladder?

***

#### 3. Job Application Package

> Using the AgenticFlow CLI, deploy the job-app-package blueprint. Use this job description:
>
> "Senior Software Engineer - Payments Infrastructure at Stripe. Requirements: 5+ years SWE experience, Python/Go/Java, distributed systems, AWS/GCP, track record scaling to millions of requests. Nice to have: fintech/payments domain, PCI-DSS, Kubernetes."
>
> CV: "Jane Doe. Senior SWE at Acme Corp 2021-2024: built payment microservices 50K txns/day in Python/FastAPI, migrated monolith to AWS Lambda -40% latency, mentored 3 engineers. SWE at StartupXYZ 2019-2021: Node.js APIs, Postgres, Kafka. BSc CS NUS 2019. Skills: Python, TypeScript, AWS, Postgres, Docker, Kubernetes."
>
> Recipient email: your own. Tone: confident.
>
> Deploy, run once, show me the fit score and cover letter draft.
>
> Leave the workflow deployed. Print the Web UI link. One-line note: why this rung of the composition ladder?

***

#### 4. Meeting Notes → Recap Email

> Using the AgenticFlow CLI, deploy the meeting-notes-email blueprint. Use these raw meeting notes as input:
>
> "Q2 planning, attendees: sarah (PM), dan (eng), mia (design). decided to cut mobile app from roadmap - too much dev time. dan will finish auth by friday. mia to redo onboarding screens by end of month. need to agree on pricing before june 1. sarah owns pricing doc. next meeting in 2 weeks."
>
> Meeting title: Q2 Planning. Recipient: <team@example.com>.
>
> Deploy, run once, show me the structured recap email that would be sent.
>
> Leave the workflow deployed. Print the Web UI link. One-line note: why this rung of the composition ladder?

***

#### 5. Lead Qualifier

> Using the AgenticFlow CLI, deploy the lead-qualifier blueprint. Qualify this lead:
>
> Company: Linear ([https://linear.app](https://linear.app/)) Your product: "an AI-powered sprint planning tool for engineering teams" ICP: "Series B+ tech companies, 20-200 engineers, US/EU"
>
> Deploy, run once, show me the fit score, pain-point alignment, budget signals, and recommended outreach angle.
>
> Leave the workflow deployed. Print the Web UI link. One-line note: why this rung of the composition ladder?

***

#### 6. Customer Feedback Digest

> Using the AgenticFlow CLI, deploy the customer-feedback-digest blueprint. Use this batch of feedback:
>
> "Love the product, but the mobile app login flow needs polish — 3 stars" "---" "Onboarding was confusing; I needed clearer steps for connecting my calendar — 2 stars" "---" "Best tool I've used this year, saves me 3 hours/week on reports — 5 stars" "---" "I need clearer in-app guidance before upgrading teams — 3 stars" "---" "The AI summaries are useful, but I want more control over tone — 4 stars"
>
> Product name: MyApp.
>
> Deploy, run once, show me the sentiment breakdown, top themes, and product recommendations.
>
> Leave the workflow deployed. Print the Web UI link. One-line note: why this rung of the composition ladder?

***

### 🔗 Get Started

* **Try AgenticFlow free:** <https://agenticflow.ai/>
* **CLI reference:** <https://docs.agenticflow.ai/developers/agenticflow-cli>
* **Latest changelog:** <https://docs.agenticflow.ai/changelog>
* **Join our Discord:** <https://qra.ai/discord>
* **Found a bug?** Email <support@agenticflow.ai> with a reproducible case — the team will prioritize it.


# Office Hour #45: Core Stability, Traceability & Bug Fixes

{% embed url="<https://youtu.be/VfTkY9EQTGA?si=zsaleFFYCuJHwEik>" %}

## Overview

Office Hours #45 focused on reliability work across agent execution, workforce runs, workflow inputs, trace visibility, and CLI behavior.

## Engine Stability & Critical Fixes

* **Agent task cleanup memory behavior improved.** HTTP clients are now closed after agent tasks finish, reducing unnecessary worker memory growth.
* **Multi-agent metadata workspace mapping fixed.** Resolved a case where high-load runs could be associated with the wrong `workspace_id`.
* **Parallel-research workforce behavior improved.** Research agents now run their tools independently, and the synthesizer produces clean attributed output.
* **Workforce agents use attached tools more consistently.** Workforce slot prompts now enforce tool use when plugins are attached.
* **Workflow run input handling improved.** `af workflow run` accepts both flat and wrapped body shapes. The `--wait` flag polls until a terminal state and returns final output inline.
* **Public workforce URLs fixed.** `af workforce publish` now returns the correct `/v1/workforce/public/...` paths and includes a ready-to-paste `curl` snippet plus Web UI canvas link.

## Traceability & Configuration Safety

* **Agent Debug Mode (Trace View).** Agent threads now show execution trace details, including tool calls, decisions, and intermediate output.
* **Task Dashboard.** Workspace task status, duration, output, and failure reasons are visible from the side navigation.
* **Agent & Workflow Versioning.** Agents and workflows can save configuration snapshots for rollback and publish-specific-version workflows.

## Platform & Infrastructure Updates

* **50 concurrent active schedules per workspace.** The active schedule ceiling increased for overlap-heavy automation.
* **Standardized workflow inputs.** Build, Run, and Shared views now use a unified workflow input schema.
* **Suggested Replies for shared agents.** Guest viewers on shared Agent links can use Suggested Replies.
* **API-key auth on Marketplace and MAS Workforce endpoints.** Programmatic management paths now support API-key authentication.
* **Auto-refreshed model lists for OpenAI-compatible providers.** Connected provider model lists refresh before display.
* **New Gemma models.** Gemma 4 26B A4B IT and Gemma 4 31B IT are available through PixelML and AgenticFlow providers.
* **Custom HTTP headers for self-hosted and third-party connections.** OpenAI-compatible endpoints can use custom auth and routing headers.

## CLI & Desktop-Agent Contract

* **AgenticFlow CLI v1.10.** The `workflow`, `agent`, and `workforce` deploy verbs are organized as a composition ladder.
* **12 tested blueprints.** Workflow, agent, and workforce blueprints can be deployed from the CLI.
* **Live marketplace catalog from the CLI.** `af marketplace list/get/try` reads the unified backend catalog and delegates to the correct clone flow.
* **AI Toolkit v4.3 routing.** Plugin packs for Claude Code, OpenAI Codex CLI, Cursor, and Gemini CLI use the shared composition-ladder decision rule.
* **CLI docs added.** Developer docs explain the CLI surface for persistent demo stacks.
* **Long-running agent defaults improved.** Blueprint-deployed agents now default to `recursion_limit` 100.
* **Cleaner `af --help`.** Deprecated commands are hidden by default and can be shown with `AF_SHOW_DEPRECATED=1`.


# Office Hour #44: Workflow Output, Model Updates & UI Fixes

{% embed url="<https://www.youtube.com/watch?v=gikWqpFsZxo>" %}

## Overview

Office Hours #44 shipped workflow output improvements, new model options, and a set of UI fixes around profile display, iPad layout, template workflow warnings, and template search.

## Improvements

* **Workflow output image downloads.** Workflow output images now include a download button instead of only a static link.
* **GLM model additions.** GLM-5 and GLM-5 Turbo are available through PixelML Provider or a z.ai connection.
* **Qwen model additions.** Qwen 3.5 9B and Qwen 3.5 Flash are available under the AgenticFlow provider.

## Fixes

* Fixed profile cover photos not displaying.
* Adjusted iPad system prompt layout for smaller screens.
* Fixed missing key-connection error indicators on workflows included with downloaded agent templates.
* Improved template search result accuracy.


# Office Hour #43: Ishi Sub-Agent & Skills Navigation

{% embed url="<https://youtu.be/CXNUeKCa__8>" %}

## Overview

Office Hours #43 focused on Ishi sub-agent work and the skills navigation surface.

## Improvements

* **Ishi sub-agent updates.** Continued work on Ishi as AgenticFlow's first-party desktop AI agent.
* **Skills library expanded.** The skills surface includes 46 skills across 12 categories.
* **Skills navigation moved to the sidebar.** Skills are easier to find from the main sidebar navigation.


# Office Hour #42: Nano Banana 2 & Agent Knowledge UI

{% embed url="<https://youtu.be/RUg1PT1gfj8?si=zPHxhuQEGAqvAibQ>" %}

## Overview

Office Hours #42 added Nano Banana 2, improved Agent Knowledge UI behavior, and fixed several workflow and agent-status issues.

## Improvements

* **Nano Banana 2.** Added Nano Banana 2 support.
* **Agent Knowledge UI.** When creating Knowledge in an Agent, the creation section now displays in table format or text format based on the selected creation mode.

## Fixes

* Fixed agents appearing as Unpublished even after being published.
* Fixed `No triggers added` appearing despite configured triggers.
* Fixed the `Include Google Search` option in the Web Retrieval node.
* Removed outdated nodes: `Image_to_video V1`, `Image_to_video V2`, and `Image_to_video V3`.


# Office Hour #41: Gemini 3.1 Pro & Sub-Agent Settings

{% embed url="<https://youtu.be/hidbV057xgs?si=zYI1nBi8utTxuvy6>" %}

## Overview

Office Hours #41 added Gemini 3.1 Pro, introduced sub-agent settings in the Agent Editor, improved chatbot branding, and fixed workflow image uploads on shared links.

## Improvements

* **Gemini 3.1 Pro.** Added Gemini 3.1 Pro support.
* **Sub-agent settings.** Added an option to enable sub-agents directly in Agent Editor settings.
* **Chatbot logo customization.** Users can customize chatbot logos by updating the Agent avatar.

## Fixes

* Fixed users being unable to upload images when accessing a workflow through a shareable link.


# Office Hour #40: Published Agent Status Fix

{% embed url="<https://youtu.be/foLQPaeO_BM?si=mCw3kSzPO9oQrPI3>" %}

## Fixes

* Resolved a regression where published agents were not showing as **Published** in the UI. Status now updates correctly after publish.


# Office Hour #39

{% embed url="<https://youtu.be/B3I1WySssrQ?si=pE0-qIb4ABO6UgCt>" %}

Office Hours session recording.


# Office Hour #38: System Prompt Editor Fixes

{% embed url="<https://youtu.be/KGaV_1zf77A?si=YOtnSENkRn2zHhQG>" %}

## Fixes

* **Agent System Prompt field.** Fixed Markdown toolbar editing across Firefox and Chrome.
* **Editor preview formatting.** Editor preview now preserves line breaks and leading spaces.

## Note

The `{{ }}` syntax for referencing variables in Agents was temporarily unavailable at the time of this Office Hours session.


# Office Hour #37: Workflow, Ask AI, Member Page & ChatV2 Fixes

{% embed url="<https://www.youtube.com/watch?v=wCIwf74AL70>" %}

## Fixes

* **Workflow audio transcription.** Fixed an issue where workflows could fail to transcribe MP3 files, including single-step workflows using only the Audio Transcription node.
* **Ask AI node AppConnection error.** Fixed an Ask AI workflow node failure caused by invalid UUID and missing required fields during AppConnection creation.
* **Member page refresh permissions.** Fixed a refresh issue that incorrectly showed a `Permission denied` screen.
* **ChatV2 image upload storage error.** Fixed an image upload storage-link issue that prevented images from attaching correctly.


# Office Hour #36: Tasks Page & Workflow Fixes

{% embed url="<https://youtu.be/9O5vilwTW2s?si=C9sQjh7Oa39Jn-jZ>" %}

## Overview

Office Hours #36 introduced the Tasks page and shipped fixes across chatbot creation, workflow extraction, agent configuration, templates, PDF export, and web search.

## Improvements

* **Tasks page.** Introduced a Tasks page for managing workflow activity.

## Fixes

* Fixed chatbot agents not being created through one-click setup.
* Fixed text extraction failures in the workflow node.
* Restored missing input placeholders in agent configuration.
* Fixed opening text not displaying when Chat V2 was active.
* Fixed duplicating templates resulting in empty agent templates.
* Fixed MAS templates not duplicating.
* Fixed Export Data to File producing an empty PDF in workflow nodes.
* Fixed an issue with the built-in Web Search workflow node.


# Office Hour #35: Debug Tray & Ishi Launch

{% embed url="<https://youtu.be/QRkNmwVGnA4>" %}

## Overview

Office Hours #35 introduced Debug Tray execution visibility and Ishi, AgenticFlow's first-party desktop AI agent.

## Improvements

* **Debug Tray.** Added execution-step tracing for agent runs.
* **Ishi desktop AI agent.** Introduced Ishi as AgenticFlow's first-party desktop AI agent.
* **AgenticFlow Credits in Ishi.** Added AgenticFlow Credits integration.
* **MCP Server integration in Ishi.** Added MCP server integration for Ishi workflows.
* **Task Dashboard roadmap.** Shared roadmap direction for task visibility.
* **Agent & Workflow Versioning roadmap.** Shared roadmap direction for versioning workflows.


# Office Hour #34: Desktop AI Assistant Layer

{% embed url="<https://youtu.be/SNPeHVIshVE>" %}

## Overview

Office Hours #34 introduced the desktop AI assistant layer for AgenticFlow-powered build and operations workflows.

## Improvements

* **Desktop AI assistant layer.** Added desktop workflow support connected to AgenticFlow.
* **AgenticFlow-connected desktop workflows.** Demonstrated desktop workflows powered by AgenticFlow.
* **Agent Skills.** Added install, create, and customize flows for AI capabilities.
* **AgenticFlow MCP Server integration.** Expanded tool connectivity through MCP.
* **Skill Creator.** Added support for creating custom skills.
* **Trace Debugging and Closed-Loop Development.** Added development workflow improvements for tracing and iteration.


# Office Hour #33: Desktop AI Architect Preview

{% embed url="<https://youtu.be/Vlh2wCHWm0s>" %}

## Overview

Office Hours #33 previewed desktop AI architect workflows, including voice-to-infrastructure patterns and physical robotics integration concepts.

## Improvements

* **Meta-agent pattern for voice-to-infrastructure workflows.**
* **Physical robotics integration concept.**
* **Vision for 2026.**


# Office Hour #32: Model Comparison & Creative Workflow Updates

{% embed url="<https://youtu.be/CNwPzTh3GVo>" %}

## Overview

Office Hours #32 covered model comparison work, concept video workflows, and UGC image feedback templates.

## Improvements

* **Model comparison.** Discussed GPT-5-2 and Claude Opus 4.5 comparison workflows.
* **Concept video series with Notebook LM.**
* **UGC image feedback template.**


# Office Hour #31: DeepSeek, Video Understanding & Image Generation

{% embed url="<https://youtu.be/xsgYNU4IxaM>" %}

## Overview

Office Hours #31 added DeepSeek model updates, video understanding with Gemini, credit-based image generation, Copilot Ask Mode, and Chat V2 beta.

## Improvements

* **DeepSeek V3.2 integration.**
* **Video understanding with Gemini.**
* **Image generation using credits.**
* **New Copilot Ask Mode.**
* **Chat V2 beta.**


# Office Hour #30: Marketplace 2.0 & Model Updates

{% embed url="<https://youtu.be/nYgcXLhAyJ8>" %}

## Overview

Office Hours #30 covered Marketplace 2.0, publication management, model updates, Robomotion MCP collaboration, and Zero to One Build Sessions.

## Improvements

* **Marketplace 2.0.**
* **Publication Management Dashboard.**
* **Claude Opus 4.5 integration.**
* **Robomotion MCP collaboration.**
* **Zero to One Build Sessions launch.**


# Office Hour #29: Black Friday Recap & Nano Banana Pro

{% embed url="<https://youtu.be/frfUb1C4yJQ>" %}

## Overview

Office Hours #29 covered Nano Banana Pro whiteboards, RoboMotion MCP integration, Tasks page UI preview, GLM 4.5 Air, and AWS Qualified Badge updates.

## Improvements

* **Nano Banana Pro Whiteboards.**
* **RoboMotion MCP integration.**
* **Tasks page UI preview.**
* **GLM 4.5 Air model.**
* **AWS Qualified Badge.**


# Office Hour #28: GPT-5.1 Series + Gemini 3 Pro Preview + Skills Deep Dive

Published November 22nd, 2025. This historical recap summarizes product updates, demos, and builder-facing improvements from the session.

## Recording

{% embed url="<https://www.youtube.com/watch?v=TmdJlAR3Esg>" %}

### GPT-5.1 Series Now Available

* GPT-5.1, Codex & Codex Mini
* Adaptive thinking levels
* Top benchmark performance (\~70 score)
* Outperforms o1
* Configurable thinking/effort levels (balance speed vs thoroughness)

### Gemini 3 Pro Preview

* Currently topping AI leaderboard

### Skills Feature Deep Dive

* Works with ALL models (GPT, Claude, Gemini, etc.) - not just Claude!
* Portable, reusable workflows
* Stored in AI Drive
* Dynamic context loading (only loads when needed)
* Cross-conversation and cross-agent functionality
* Combine multiple skills in one agent

### Skills vs System Prompts vs MCP

* Detailed comparison based on Anthropic blog
* When to use each approach
* Best practices for implementation

## Demonstrations

* Travel Planner skill - real-world itinerary generation
* Skills working across different models
* Dynamic skill loading and management

## Support

For reproducible product issues, email <support@agenticflow.ai> with workspace context, affected agent/workflow/template details, screenshots or screen recording, and steps to reproduce.


# Office Hour #27: Kimi K2 Thinking Model + Code Execution + Agent API Launch

Published November 11th, 2025. This historical recap summarizes product updates, demos, and builder-facing improvements from the session.

## Recording

{% embed url="<https://www.youtube.com/watch?v=KAM2P6ZkENE>" %}

### Kimi K2 Thinking Model

* \#3 globally ranked model
* 6x cheaper than Sonnet 4.5 ($0.60 vs $6 per 1M input tokens)
* Exceptional tool-calling capabilities
* Scores 61 on Agentic Index (vs 16 for Gemini Flash)
* Now available in AgenticFlow

### Code Execution Tool (Beta)

* Agents can write and execute Python code
* Isolated execution environments
* Extends capabilities beyond plugins
* Enables: YouTube downloaders, PDF generation, API integrations

### Recursion Limit Configuration

* New setting: 10-100 (default 25)
* Control agent execution loops
* Manage costs effectively
* Prevent infinite loops

### Self-Improving Agents

* Combine AI Drive + Skills
* Agents modify their own knowledge base
* Improve performance over time
* Adaptive learning capabilities

### Agent API Launch

* Full programmatic access
* Create, read, update, delete agents via API
* Trigger agents programmatically
* API Documentation live at docs.agenticflow\.ai/api-reference
* Example boilerplate code on GitHub

### Citations (Beta Sneak Peek)

* Track where agents get information
* Enhanced transparency and trust

## MCP Client Connections

* Support any MCP-compatible service
* Hugging Face integration
* Zapier connectivity
* Expanded integration ecosystem

## Support

For reproducible product issues, email <support@agenticflow.ai> with workspace context, affected agent/workflow/template details, screenshots or screen recording, and steps to reproduce.


# Office Hour #26: Designer Agent + Video Agent + Let AI Work While You Sleep (MCP)

Published November 4th, 2025. This historical recap summarizes product updates, demos, and builder-facing improvements from the session.

## Recording

{% embed url="<https://www.youtube.com/watch?v=-hwRQJYmenk>" %}

### Pixel ML Designer Agent Template

* Create on-brand advertisements and posters using Nano Banana (Gemini 2.5 Flash Image)
* Automatic logo integration and brand guideline adherence
* System prompts tailored to brand colors, fonts, and style
* One-shot creative generation for marketing teams
* Template includes workflow and brand assets

### Pixel ML Video Agent Template

* Generate brand-specific videos with Veo 3.1
* Two-step workflow: Start frame generator + End frame generator + Video generation
* Maintains brand consistency throughout video
* Uses Nano Banana for frame generation with logo placement
* Template includes complete workflow setup

### Veo 3.1 Reference Image Feature (NEW)

* Image-to-video generation capability
* Reference images for character, location, or object consistency
* Combine multiple reference images in a single video
* Available in both Veo 3.1 and Veo 3.1 Fast
* Enhanced creative control over video output

### AgenticFlow MCP Enhanced - "Let AI Work While You Sleep"

* Claude Desktop and ChatGPT can now CREATE agents for you
* Conversational agent and workflow building
* Agent self-correction with feedback loops
* API error handling and automatic fixes
* No manual configuration needed

### Agent Management via MCP

* List agents in your workspace
* Get agent details and configurations
* Create new agents conversationally
* System prompt generation by AI
* Examples demonstrated:
  * Lead Qualification Agent
  * Email Inbox Management Agent
  * Smart prioritization and scoring

### Workflow Management via MCP

* List workflows in your workspace
* Get workflow details and structure
* Create new workflows conversationally
* Execute workflows and get results
* Example: Competitor Analysis Workflow with Tavily integration

### Agent Feedback Loops

* Agents receive API error messages
* Self-correction when creation fails
* Retry with fixes automatically
* Validates requirements and adjusts
* Reduces manual intervention

### MCP Connection Setup

* Detailed setup guide provided in documentation
* Custom connector configuration in Claude Desktop
* URL: <http://mcp.agenticflow.ai/mcp>
* OAuth-style connection flow
* Always Allow option for seamless automation

### Designer Agent Workflow

* Input: URL (logo), topic, user prompt
* Uses Nano Banana (Gemini 2.5 Flash Image) for image editing
* System prompt with brand guidelines
* Output: Branded advertisement/poster
* Maintains logo placement and brand colors

### Video Agent Workflow

* Step 1: Generate start frame with Nano Banana
* Step 2: Generate end frame with brand elements
* Step 3: Veo 3.1 video generation with start/end frames
* Resolution: 720p or 1080p options
* Aspect ratio: 16:9 supported
* Duration: Short-form video (TVC-style)

### Veo 3.1 Reference Image Parameters

* Model: Veo 3.1 or Veo 3.1 Fast
* Aspect ratio: Configurable
* Resolution: 720p or 1080p
* Reference images: Up to 3 images
* Use cases: Character consistency, location matching, object placement

### Designer Agent Use Cases

* Marketing campaign creatives
* Social media advertisements
* Product launch posters
* Brand-consistent graphics
* Automated creative generation for agencies

### Video Agent Use Cases

* Product advertisements (e.g., AirPods Pro)
* Brand video content
* Social media video ads
* TVC-style short-form content
* Client-specific branded videos

### MCP Automation Use Cases

* Lead qualification and scoring
* Email inbox management and prioritization
* Competitor analysis research
* Automated agent creation for clients
* Self-service agent building for teams

## Support

For reproducible product issues, email <support@agenticflow.ai> with workspace context, affected agent/workflow/template details, screenshots or screen recording, and steps to reproduce.


# Office Hour #25: Veo 3.1 + New Plugin System + New Skill System

Published October 28th, 2025. This historical recap summarizes product updates, demos, and builder-facing improvements from the session.

## Recording

{% embed url="<https://www.youtube.com/watch?v=06oYfiOWSRg>" %}

### Veo 3.1 in AgenticFlow

* Start/end frame support
* Scene extension capabilities
* Image-to-video conversion
* Pricing: $0.40/s (Standard), $0.15/s (Fast)
* Integration with Gemini 2.5 Flash for prompts

### New Plugin System

* Add built-in actions as tools
* OpenAI integration
* Pixel ML operator support
* Per-agent plugin management (\~9 recommended)
* Use MAS when you need more plugins

### New Skill System

* Composable, portable skills (skill.md)
* On-demand loading for efficiency
* Bigger than MCP alone
* Skills load only when needed
* Cross-conversation and cross-agent functionality

### MAS Video Workflow

* Complete pipeline: script -> frames -> prompt -> combine clips
* Generate longer videos from multiple clips
* Gemini 2.5 Flash image plugin integration
* Veo 3.1 Fast for quick clip generation

## Agent Editor Enhancements

* Plugin tab added
* Skill tab added
* Model selection with aspect ratio
* Start/last frame URL configuration

## Iteration 3 Progress

* Development cycle underway (ends Nov 7)
* Fixes ship within iteration
* Continuous improvements

## Support

For reproducible product issues, email <support@agenticflow.ai> with workspace context, affected agent/workflow/template details, screenshots or screen recording, and steps to reproduce.


# Office Hour #24: AWS Select Partner + Claude Haiku 4.5 + Skills Launch

Published October 21st, 2025. This historical recap summarizes product updates, demos, and builder-facing improvements from the session.

## Recording

{% embed url="<https://www.youtube.com/watch?v=IHqqGVU3HzU>" %}

### AWS Select Partner Achievement

* AgenticFlow achieved AWS qualification
* Foundation Technical Review completed
* CIS 3.0 security scanning passed
* Enterprise-grade security and compliance

### Claude Haiku 4.5

* 3x cheaper than Sonnet 4
* Scores 73.3% on benchmarks (vs Sonnet 4's 72.7%)
* Specifically trained for agentic workflows
* Superior price/performance ratio

### Claude Skills Launch

* Bigger than MCP!
* Specialized instruction sets for complex tasks
* Teach agents how to perform sophisticated operations
* Coming to AgenticFlow Marketplace in early November

### AgenticFlow Skill

* Open source skill on GitHub
* Teaches Claude how to build workflows and agents
* Create custom skills in 5 minutes using AI assistants
* Works with ANY model (GPT-4, Gemini, etc.)

### Memory System Use Cases

* LinkedIn Post Writer demo
* Customer Support Agent demo
* Real-world applications of Memory 5 system
* Production-ready templates

## Developer Resources

* Pixel ML Skills repository on GitHub
* AgenticFlow Skill available for contribution
* Every agent can use skills across all models

## Support

For reproducible product issues, email <support@agenticflow.ai> with workspace context, affected agent/workflow/template details, screenshots or screen recording, and steps to reproduce.


# Office Hour #23: MCP OAuth Upgrade + Project-Level Isolation + Memory System

Published October 14th, 2025. This historical recap summarizes product updates, demos, and builder-facing improvements from the session.

## Recording

{% embed url="<https://www.youtube.com/watch?v=RQ4aA6ZN6yI>" %}

### MCP OAuth Upgrade

* Re-enabled key integrations (Pipedream/Composer)
* Cleaner OAuth flow
* Faster, more secure connections
* Simpler setup for Google Docs/Sheets and more
* OAuth handshake for MCP servers

### Project-Level Isolation

* Scope tools, memory, and access per project
* Prevent cross-pollution between projects
* Keep workstreams clean and organized
* Safer multi-team and multi-client setups

### Memory System ("Drive")

* Persistent file system for agents
* Browse, upload, and use files across sessions
* View directory first, record progress
* Recover context reliably
* Memory best practices and patterns

## Developer Features

* Project isolation patterns for teams
* Enhanced security and organization
* Improved context management

## Support

For reproducible product issues, email <support@agenticflow.ai> with workspace context, affected agent/workflow/template details, screenshots or screen recording, and steps to reproduce.


# Office Hour #22: OpenAI Dev Day Special: Apps in ChatGPT + Sora 2 & SeeDance 1.0

Published October 7th, 2025. This historical recap summarizes product updates, demos, and builder-facing improvements from the session.

## Recording

{% embed url="<https://www.youtube.com/watch?v=qfSC0oYONEw>" %}

### Apps in ChatGPT

* One-click publish AgenticFlow agents to ChatGPT App Store
* MCP integration in development
* Reach 800M weekly ChatGPT users
* Build once, publish everywhere

### Agentic Commerce Protocol

* Agents can now checkout and purchase
* Coming to AgenticFlow for Rachel and custom agents
* Enable commerce capabilities in workflows

### OpenAI Agent Builder

* OpenAI entered the agent space
* AgenticFlow maintains key advantages:
  * Multi-model support (Claude, Gemini, Grok, local models)
  * Advanced workflows
  * Superior integration capabilities

### Sora 2 & Sora 2 Pro API

* Now integrated in AgenticFlow
* Pricing: $0.10/sec (720p), $0.40/sec (1080p)
* API access for video generation

### ByteDance C-Dance 1.0

* 70-80% cheaper than Sora
* Integrated and ready to use
* Pricing: $0.03/sec (720p)
* 1080p at 5x lower cost than Sora

## Ready-to-Import Templates

* Mr. Beast Thumbnail Designer
* Poster Resizing Agent
* Product Image Agent
* Workflow exports for Sora and C-Dance
* All JSON files available in #office-hours channel

## Support

For reproducible product issues, email <support@agenticflow.ai> with workspace context, affected agent/workflow/template details, screenshots or screen recording, and steps to reproduce.


# Office Hour #21: Claude Sonnet 4.5 Deep Dive + DeepSeek 3.2 & GLM 4.5

Published September 30th, 2025. This historical recap summarizes product updates, demos, and builder-facing improvements from the session.

## Recording

{% embed url="<https://www.youtube.com/watch?v=_p-EkfYGLMg>" %}

### Claude Sonnet 4.5

* Hands-on usage demonstration
* Practical tips and best practices
* Cloud Code setup (npm/global steps)

### Model Comparisons

* DeepSeek 3.2 highlights
* GLM 4.5 overview
* Price/performance analysis across models

### MCP Server Integration

* Tools via Cloud Code
* MCP endpoints & health checks inside flows
* Enhanced integration capabilities

### Multi-Agent Workflows

* Design, validate, and iterate workflows
* Workflow validation tool usage
* Competitor analysis workflow example

### System Prompt Management

* Self-updating prompts
* File-based prompt management
* Dynamic prompt handling

## Session Details

* \~53-minute replay with live demo
* Chapters and deep Q\&A
* Practical implementation examples

## Support

For reproducible product issues, email <support@agenticflow.ai> with workspace context, affected agent/workflow/template details, screenshots or screen recording, and steps to reproduce.


# Office Hour #20: AgenticFlow MCP in ChatGPT + Google URL Context (Gemini 2.5)

Published September 23rd, 2025. This historical recap summarizes product updates, demos, and builder-facing improvements from the session.

## Recording

{% embed url="<https://www.youtube.com/live/Qvm-5pVp7P4>" %}

### AgenticFlow MCP in ChatGPT

* Connect via Developer Mode to control workspace
* 10,000+ MCP actions available
* Browse and compose workflows directly from ChatGPT
* Search External MCP to explore tools and compose steps

### Google URL Context (Gemini 2.5)

* Ingest URLs and PDFs as model context
* No manual scraping required
* Use with Gemini 2.5 Pro/Flash models

### Web to Blog Demo

* Synthesize multiple sources
* Output to Google Docs or Markdown
* Complete content pipeline

## Setup Instructions

* Enable Dev Mode: Settings -> Connectors -> Advanced -> Developer Mode
* Add source: AgenticFlow MCP
* Paste AgenticFlow API key
* Start building with ChatGPT

## Support

For reproducible product issues, email <support@agenticflow.ai> with workspace context, affected agent/workflow/template details, screenshots or screen recording, and steps to reproduce.


# Office Hour #19: ChatGPT MCP Copilot + MAS Templates & UGC Art Generator

Published September 16th, 2025. This historical recap summarizes product updates, demos, and builder-facing improvements from the session.

## Recording

{% embed url="<https://www.youtube.com/watch?v=a8j-OumNXo0>" %}

### ChatGPT MCP Integration

* Connect ChatGPT to AgenticFlow via Developer Mode
* OAuth + API key authentication
* ChatGPT can list and run AgenticFlow workflows
* Access to 10,000+ tools in AgenticFlow

### Copilot Experience

* Build agents and flows with natural language
* Use ChatGPT subscription + memory
* Conversational workflow creation
* Cost: GPT-5 \~$10 per 1M tokens

### MAS Templates

* Deep Research MAS
* UGC Art Generator
* Script-to-Video MAS
* Director MAS with iteration and memory

## Developer Features

* Enable MCP in ChatGPT Developer Mode
* Authorize AgenticFlow and paste API key
* List workflows, fetch details, and trigger actions
* "Office Hour Materials" added to Docs

## Rollout Timeline

* Production release targeted in \~1 week
* Cloud integration planned

## Support

For reproducible product issues, email <support@agenticflow.ai> with workspace context, affected agent/workflow/template details, screenshots or screen recording, and steps to reproduce.


# Office Hour #18: Veo 3 + Multi-Agent Video Generator + MAS Embeds & Express Designer

Published September 9th, 2025. This historical recap summarizes product updates, demos, and builder-facing improvements from the session.

## Recording

{% embed url="<https://www.youtube.com/watch?v=bulZrdgltWo>" %}

### Veo 3 Integration

* Google Veo 3 and Veo 3 Fast available in workflows, agents, and MAS
* Aspect ratio and quality selectors
* Access via OpenRouter with Pixel ML key (pass-through costs)
* Seed videos with start images and prompts

### Multi-Agent Video Generator

* 3 agents collaborating: script -> start frames -> scene videos
* Orchestrated workflow for complete video production
* Powered by Gemini 2.5 Flash ("Nano Banana") for prompt generation

### Express Designer Agent

* One-shot banner and slide generation
* Import/export functionality
* Public embeds available

### MAS Enhancements

* Plugins support
* Conditionals and loops
* State modifiers
* Pause/wait functionality
* Chain workflows (call another workflow)

### Publish & Share

* MAS share links
* iframe embeds
* Starter template clone (Deep Research MAS)
* Toggle Share to make agents/MAS public

## Key Features Demonstrated

* 3 agents orchestrated for video generation
* 5 start frames generated per video
* 1-click public embed
* Clonable MAS templates

## Support

For reproducible product issues, email <support@agenticflow.ai> with workspace context, affected agent/workflow/template details, screenshots or screen recording, and steps to reproduce.


# Office Hour #17: Nano Banana (Gemini 2.5 Flash Image) + Virtual Try-On + 16:9 Trick

Published September 2nd, 2025. This historical recap summarizes product updates, demos, and builder-facing improvements from the session.

## Recording

{% embed url="<https://www.youtube.com/watch?v=1Qr3bDanfyc>" %}

### Gemini 2.5 Flash Image Integration ("Nano Banana")

* Google's latest image model now available in AgenticFlow
* Advanced image editing and composition capabilities
* Virtual try-on workflows for clothes, jewelry, and accessories
* Mix and edit images while preserving subject identity
* World-model style results for realistic compositions

### Virtual Try-On Workflows

* Build professional try-on experiences for e-commerce
* Jacket, clothing, and jewelry demonstrations
* Maintain subject identity across edits
* Real business value and client-facing applications

### Aspect Ratio Breakthrough

* Overcome square-only limitation in AI Studio
* Generate 16:9 and custom aspect ratios with workflow seed image trick
* 360 panorama edit experiments
* Flexible output formats for different use cases

### AgenticFlow Setup

* Provider configuration for Gemini 2.5 Flash Image
* Prompt optimization tips for best results
* Workflow packaging as client services
* Access via Google AI Studio

## Business Applications

* Package image workflows as services
* Client deployment strategies
* Education and training use cases
* E-commerce virtual try-on solutions
* Creative composition services

## Key Demonstrations

* Virtual try-on: jackets and earrings
* Image mixing and editing workflows
* 16:9 aspect ratio generation trick
* 360 panorama editing
* Client-facing agent deployment

## Model Capabilities

* Advanced editing features
* Image mixing and composition
* Subject identity preservation
* World-model realistic outputs
* Custom aspect ratio support

## Support

For reproducible product issues, email <support@agenticflow.ai> with workspace context, affected agent/workflow/template details, screenshots or screen recording, and steps to reproduce.


# Office Hour #16: Discord Bot Integration + Visual AI Agents + Qualcomm Win

Published August 26th, 2025. This historical recap summarizes product updates, demos, and builder-facing improvements from the session.

## Recording

{% embed url="<https://www.youtube.com/watch?v=06oYfiOWSRg>" %}

### Qualcomm Innovation Challenge Win

* Top 10 placement in Qualcomm Vietnam Innovation Challenge
* Cash prize and partnership opportunities
* New MOU with enterprise startup for government solutions
* Snapdragon phone integration for local AI workforce

### Discord Bot Integration

* Deploy AgenticFlow agents directly to Discord channels
* Step-by-step agent duplication and configuration
* Privacy-preserved chat history with user-specific sessions

### Visual Agent Templates

* Iris agent generates and edits AI images seamlessly
* One-shot image creation and editing
* Visual AI capabilities demonstration

### GPT-5 Nano Support

* New model integration
* Optimized temperature settings for best performance
* Enhanced reasoning capabilities

## Platform Highlights

* Workflow red dot connection system for tool integration
* Public agent deployment via shareable links
* Embeddable chat widgets for websites
* Multiple deployment options: Discord, web chat, and iframe

## Team Updates

* Team expansion with new developers
* Customer success members added
* Mountain retreat team celebration

## Support

For reproducible product issues, email <support@agenticflow.ai> with workspace context, affected agent/workflow/template details, screenshots or screen recording, and steps to reproduce.


# Office Hour #15: Discord Bot Agent NOW LIVE + Multi-Agent System V2 + Chrome Extension Preview

Published August 19th, 2025. This historical recap summarizes product updates, demos, and builder-facing improvements from the session.

## Recording

{% embed url="<https://www.youtube.com/watch?v=BLK0kT1U3PM>" %}

### Discord Bot Agent (LIVE)

* Deploy AgenticFlow agents directly to Discord servers
* Simple setup via Discord Developer portal
* Configure and deploy within AgenticFlow
* Transform Discord servers into AI-powered workspaces

### Multi-Agent System V2

* Enhanced visual workflow builder
* Drag-and-drop interface for complex agent orchestration
* Improved UI and workflow management
* Advanced MAS templates and research workflows

### Chrome Extension Preview

* Browser automation capabilities in final testing
* Chrome extension integration for web control

### MCP Integrations Enhanced

* WordPress MCP server demo for content management automation
* Support for any MCP-compatible service
* Enhanced protocol support for external services

## Key Features

* Visual workflow builder for MAS
* Discord bot configuration walkthrough
* Browser automation preview
* External service connections via MCP

## Support

For reproducible product issues, email <support@agenticflow.ai> with workspace context, affected agent/workflow/template details, screenshots or screen recording, and steps to reproduce.


# Office Hour #14: GPT-5 Nano NOW LIVE + Multi-Agent System Demo

Published August 12th, 2025. This historical recap summarizes product updates, demos, and builder-facing improvements from the session.

## Recording

{% embed url="<https://www.youtube.com/watch?v=EoVAyd4dcbE>" %}

### GPT-5 Nano Integration

* Available NOW in AgenticFlow
* All existing credits work with GPT-5 Nano
* Same-day integration with OpenAI announcement
* Advanced reasoning model with chain-of-thought built-in

### Extended Context Length

* 400K token context window
* Process 300K+ words in a single conversation
* Game-changer for agent development

### Multi-Agent System Demo

* Deep research template with task management
* Sophisticated workflows for complex tasks
* Enhanced agent coordination

## Platform Updates

* Seamless model selection in agent settings

## Benchmark Performance

* GPT-5 advanced reasoning capabilities
* Optimized for agentic workflows
* Superior context handling

## Support

For reproducible product issues, email <support@agenticflow.ai> with workspace context, affected agent/workflow/template details, screenshots or screen recording, and steps to reproduce.


# Office Hour #13: SOTA OCR with Mistral + MAS V2 UI Preview & Deep Research Templates

Published August 5th, 2025. This historical recap summarizes product updates, demos, and builder-facing improvements from the session.

## Recording

{% embed url="<https://www.youtube.com/watch?v=BzmD6ayjLsU>" %}

### Mistral OCR

* State-of-the-art OCR with 94.89% accuracy score
* Outperforms Google Document AI & GPT-4
* Process complex documents in under 3 seconds
* Support for scanned PDFs, images, and multi-language documents
* Extract data from charts, tables, and mathematical formulas

### Batch Processing

* Handle up to 1,000 pages in a single OCR run
* Cost-effective at just $1-2 via Open Router
* Available in workflows via Pixel ML Open Router

### MAS V2 UI Preview

* New snake layout for better workflow organization
* Enhanced navigation and agent organization
* Improved workforce configuration interface

### Deep Research Templates

* Ready-to-clone templates now available
* Pre-built workflows for research, sales, and business analysis
* Template cloning and customization support

## Developer Features

* OCR node available in workflows
* Multi-modal capabilities
* Advanced configuration options

## Support

For reproducible product issues, email <support@agenticflow.ai> with workspace context, affected agent/workflow/template details, screenshots or screen recording, and steps to reproduce.


# Office Hour #12: AgenticFlow MCP Integration + Multi-Agent Teams + 10,000+ Tools

Published July 29th, 2025. This historical recap summarizes product updates, demos, and builder-facing improvements from the session.

## Recording

{% embed url="<https://www.youtube.com/watch?v=n0CB4ernzRI>" %}

### AgenticFlow MCP Integration

* Connect Claude Desktop and ChatGPT to AgenticFlow
* Auto-discover 10,000+ external actions without manual configuration
* Build AI copilots that automatically find and use external services
* New MCP tools: list, search, and get external MCP apps

### Multi-Agent System UI Redesign

* Supervisor-subagent architecture
* Enhanced team coordination and workflow management
* Improved visual interface for agent orchestration

### Max Payload Upgrade

* Support for 10,000+ tools in a single workspace
* Massive expansion of integration capabilities

### Workflow Debugging

* AgenticFlow validate tool for self-debugging workflows
* Automatic error detection and correction
* Enhanced reliability for complex automations

### Team Deployment

* Deploy agent teams directly to Discord/Slack
* Real-time collaboration within team workspaces
* Seamless integration with communication platforms

### Pre-built MAS Templates (Preview)

Coming in August - 5 ready-to-use multi-agent system templates:

1. Research Team
2. Sales Team
3. Content Team
4. Support Team
5. Competition Analysis Team

## Key Demonstrations

* Gmail automation workflow with copilot
* Building workflows that self-debug
* Connecting MCP to Claude Desktop
* Creating custom copilots with AgenticFlow MCP
* Multi-Agent System architecture walkthrough
* Discord/Slack deployment process

## Support

For reproducible product issues, email <support@agenticflow.ai> with workspace context, affected agent/workflow/template details, screenshots or screen recording, and steps to reproduce.


# Office Hour #11: AgenticFlow MCP Server + Autonomous Workflow Creation

Published July 22nd, 2025. This historical recap summarizes product updates, demos, and builder-facing improvements from the session.

## Recording

{% embed url="<https://www.youtube.com/watch?v=J9mjj5F-Bik>" %}

### AgenticFlow MCP Server

* Connect Claude Desktop directly to AgenticFlow
* First-ever MCP server demonstration
* List, search, create, and edit workflows from Claude Desktop
* Debug and submit actions through natural language

### Autonomous Workflow Creation

* Claude can now create workflows autonomously
* Just describe what you need, Claude builds it
* Edit workflows through conversation
* No manual workflow building required

### GoHighLevel Integration

* Auto-reply CRM agents
* Schedule automated responses
* Fetch and respond to customer conversations
* Complete tutorial available

## Key Features

* Natural language workflow generation
* Live workflow editing and debugging
* Multi-integration support
* Conversational automation design

## Paradigm Shift

* From manual building to autonomous creation
* AI as your workflow developer
* True no-code revolution

## Support

For reproducible product issues, email <support@agenticflow.ai> with workspace context, affected agent/workflow/template details, screenshots or screen recording, and steps to reproduce.


# Office Hour #10: Kimi K2 1 TRILLION Parameter Open Model + n8n Agent & Multi-Agent Progress

Published July 15th, 2025. This historical recap summarizes product updates, demos, and builder-facing improvements from the session.

## Recording

{% embed url="<https://www.youtube.com/watch?v=HBJ1zXTXi2k>" %}

### Kimi k2 Model Integration

* First open-source 1 TRILLION parameter model now available in AgenticFlow
* Performance on par with Claude Opus at 20X lower cost
* Excellent for software development tasks
* Available via Pixel ML Open Router

### n8n Agent Preview

* Create complex n8n workflows from natural language descriptions
* Seamless integration between AgenticFlow and n8n instances
* Extends agent capabilities with n8n's extensive node library

### Built-in Database

* Store workflow outputs directly in AgenticFlow
* No more dependency on external services like Google Sheets or Airtable
* Native data storage solution

### Bulk Run Capabilities

* Execute workflows 100+ times with table-based inputs
* Parallel processing support

### Workflow Sharing

* Share workflows via secure URLs
* View-only permissions for collaboration

### Multi-Agent System Work

* Conditional branching and advanced task management added

### Developer Ecosystem

* Create MCP servers for popular tools (2000+ APIs available)
* Community-driven ecosystem expansion

## Support

For reproducible product issues, email <support@agenticflow.ai> with workspace context, affected agent/workflow/template details, screenshots or screen recording, and steps to reproduce.


# Office Hours #1-#7: Early Video Archive

The first AgenticFlow Office Hours sessions covered the early builder workflow, MCP work, embeds, webhooks, scheduling, Copilot improvements, and the first multi-agent previews.

| Session | Focus                                                                          |
| ------- | ------------------------------------------------------------------------------ |
| #1      | New features, MCP workflow, PDF knowledge, and multi-agent sneak peek          |
| #2      | iFrame embed, webhooks, and MCP deep dive                                      |
| #3      | BYOK Claude 4, Gemini 2.5 Pro, Mia Ask Mode, webhook triggers, and embeds      |
| #4      | Copilot enhancements, workflow scheduling, DeepSeek AI, and bug-fix priorities |
| #5      | Scheduling autonomous agents, Hugging Face MCP, and UI/UX overhaul             |
| #6      | Hyper-personalized lead engagement, Telegram bot workflow, and MCP 2.0         |
| #7      | Multi-agent previews, voice interaction, Copilot integration, and workflow UX  |


# Legacy Product Updates: March 2024 - June 2025

This archive summarizes early AgenticFlow product updates before the Office Hours changelog moved into the current release-note format.

## June 25th, 2025 - Iteration 6.10 -> 6.23 - "Knowledge Revamp, Voice Dictation & Multi-Agent Preview"

{% embed url="<https://www.loom.com/share/6cf7c88f009a48e5b08d590f4de6e9b3?sid=989c5984-4bf7-43d0-987b-84b5e559e02a>" %}

{% embed url="<https://www.loom.com/share/f86bb5acd90f4eb299b86d957be5bba4?sid=43332f3f-3703-43b3-af52-f158554b410d>" %}

#### Added

* Schedule Trigger - run any workflow or agent on cron-like schedules (daily, weekly, or custom) from the new Trigger -> Schedule tab.
* Streamable-HTTP transport - plug any Hugging Face Space into MCP as a tool with one click; premiered with an image-generation Space demo.
* Copilot schema-safe JSON - Copilot now auto-validates and emits perfect JSON when generating workflows, slashing manual fixes (shown while drafting new OpenAI/Claude docs).

#### Improved

* Agent Builder UI/UX - cleaner preview pane, theme picker (font sizes & colours), and smarter auto-suggest-as-you-type for prompts.
* MCP Tool Management - new filter lets you untick tools so agents only "see" what they need, boosting accuracy to 80-90 % and blocking destructive actions.

#### Fixed

* Ops-week bug-squash (Jun 3) - knocked out UX glitches, preview-render hiccups, and theme quirks.

## June 10th, 2025 - Iteration (5.27 - 6.9) - Schedule/Webhook Triggers, "Mia" Copilot, HuggingFace MCP & UI Polish

#### Fixed

* Focused bug-squash sprint: assorted UX glitches, preview rendering and theme issues addressed during the Jun 3 "ops week" session

## May 27th, 2025 - Iteration (5.13 - 5.26) - BYOK Claude 4, Gemini 2.5 Pro, AI Copilot "Mia" Ask Mode, Webhook triggers, Agent Embedding, Export & Import Agents + Workflows

{% embed url="<https://www.loom.com/share/669729e3fb814307ab590a15830c8035?sid=ce8ec70b-21b4-4075-a945-e5eed8b16278>" %}

#### Major Features

1. AI Copilot "Mia" (ASK Mode)

* Debut of our in-workspace Copilot, pre-loaded with 750K+ tokens of MCP/agent knowledge
* Assists you in authoring new workflows and agents end-to-end
* Able to digest prompts, generate JSON workflow files, and import them back into your workspace

2. Bring-Your-Own-Key (BYOK) for Cutting-Edge Models

* Full support for Anthropic Claude 4 , Google Gemini 2.5 Pro & Flash , and OpenAI GPT-4.1 (mini/nano)
* Plug in your own API keys under "Connections" -> choose "Google GNI" or "OpenAI" -> select your preferred model

3. Webhook Triggers

* New Trigger tab on your agent: configure GET/POST endpoints, auth types (Basic/API-Key), and JSON payload mapping
* Agents can now react to external events (from Telegram, WhatsApp, your backend) in real time

4. Agent Embedding (Iframe & Share Links)

* Public agents now expose a copy-and-paste iframe widget or shareable URL
* Embed your live agent into any website or blog post with one snippet

5. Export & Import Agents + Workflows

* Download agents or workflows as a single JSON file
* Import into another workspace to replicate setups or share with teammates

#### UX & Polish

* Theme & Branding : choose global theme or custom hex color for your agent chat UI
* Avatar & Icon Revamp : revamped chat icons; fixed avatar upload/save bug
* Welcome Message Fixes : ensures custom greeting displays on public embeds

## May 12th, 2025 - 2,500 APIs and 10,000 tools in Workflow - Power & Flexibility for Your Automations

Up to 2,500 MCP Nodes : Scale your workflows massively by using thousands of MCP units as individual nodes. Optimized LLM for MCP : Smarter language models now fuel your MCP nodes for more accurate outcomes. Pixel ML Credits Dashboard : Instantly view and manage your credit consumption in one clear dashboard.

## May 5th, 2025 - Straico Support - UI & Workflow Enhancements - Smoother Experience, Better Control

Straico API Integration : Tap into Straico's data streams to enrich and automate your processes.

Table-Navigation Sidebar : Jump between data tables in seconds with our new left-hand menu. Publish Reliability Fix : Squashed the rare bug causing agents to fail on publish. Explore & Create Flow : Refreshed modals and embed scripts (including WordPress docs) for a friction-free agent-creation journey. Library Management Panel : Browse, organize, and deploy reusable assets from one central hub. Stripe & Billing UI : Updated links and streamlined payment flows for faster, more secure subscriptions. General UI Polish : Improved modal scrolling, template toggles, and overall interface tidiness.

## April 21st, 2025 - Under-the-Hood Improvements - Smarter, Faster, More Reliable Workflows

LLM Credit Management : Seamlessly track and bill your AI usage credits right from your workspace. Visual Node Mapping : See and configure your workflow steps with an intuitive node-map view. Large-Payload Support : Handle longer messages and richer data without truncation. Enhanced Firecrawl Extraction : Automatically merge multi-part API responses into a single, clean output. Performance & Stability Boost : Under-the-scenes fixes to keep your automations running smoothly.

## April 12th, 2025 - New Features - Instant AI Assistant for ECommerce

Seamless Onboarding : Customers simply enter their email, and our platform automatically scrapes their website to gather product catalog data, frequently asked questions, and other key details. Automated Catalog & FAQ Integration : The assistant is instantly trained on your store's information, enabling it to understand your product offerings and answer customer queries 24/7. Effortless Setup and Deployment : No technical expertise required-just embed the assistant on your website and provide a few basic details, and it's ready to support your customers around the clock. Always-On, Smarter Support : Provides real-time, intelligent customer assistance, helping drive engagement and boost sales by guiding shoppers to find what they need.

This release brings advanced AI capabilities to online retail, simplifying setup and ensuring that customers receive quick, reliable support without needing human intervention around the clock.

## April 11th, 2025 - Faster, Smarter Workflow Execution

We've turbocharged our workflow engine so your automated tasks run more smoothly and reliably. Enhanced our API integration and improved error handling to ensure seamless operation throughout the platform. New tools help you trigger and manage tasks more intuitively, ensuring that your daily processes are more responsive than ever.

## April 4th, 2025 - Easier Account and Subscription Management

Enjoy smarter workspace invitations and more secure subscription handling-preventing duplicate entries and streamlining team collaboration. We've also introduced new search capabilities to help you find and interact with data faster, meaning you spend more time on highvalue work.

## March 21st, 2025 - Effortless Data Integration & Streaming

Our platform now handles complex data inputs (like lists, objects, and media) without extra manual work, making setup simpler for you. We added realtime data streaming and history features for better tracking of your workflow actions, so you always know what's happening behind the scenes.

## February 24th, 2025 - Personalized Chat and Visual Tools

Customize your interaction experience with enhanced chatflows-choose unique role names, avatars, and welcome messages to suit your style. Creative tools now let you generate and edit images from text, bringing your ideas to life with ease. We also ensured that temporary data resets automatically to keep every session clean and reliable.

## January 24th, 2025 - Improvements - Personalized Chatflow Configuration

Tailor your interactive workflows with customizable role settings including names, avatars, and welcome messages. This update helps you create unique, engaging conversation experiences for every use case.

## January 23rd, 2025 - New Features - Visual Content Creation Tools

Unleash your creativity with powerful image generation and visual editing nodes. Transform text into custom visuals and refine your media content effortlessly-all directly within AgenticFlow.

## January 22nd, 2025 - Improvements - Optimized Data Operations Experience

A redesigned data management interface now centralizes your test and online data operations. Batch imports, inline editing, and more intuitive navigation mean managing your records is faster and more efficient.

## January 17th, 2025 - Improvements - Enhanced Workspace Invitations

Inviting team members is now both quicker and more secure. With time-limited invitation links and clear notifications, adding collaborators to your workspace is simpler than ever.

## January 10th, 2025 - New Features - Dynamic Variable Management

Our new variable system automatically resets temporary values with every session-ensuring your workflows always start fresh while reducing the chance of data misconfiguration.

## December 25th, 2024 - New Features - Model & Version Management

Monitor and manage the different versions of your workflows and plugins with ease. You can now review performance metrics, track changes over time, and roll back to previous versions as needed without affecting your live services.

## December 25th, 2024 - Manage Models, Versions & More

We've added new controls to monitor and manage the different versions of your automation workflows-this means you can easily review changes or revert to a previous version if needed. Chatflow, our conversational mode for building interactive experiences, is here along with flexible publishing options so you can schedule updates exactly as required.

## December 24th, 2024 - Manage Models, Versions & More

We've added new controls to monitor and manage the different versions of your automation workflows-this means you can easily review changes or revert to a previous version if needed. Chatflow, our conversational mode for building interactive experiences, is here along with flexible publishing options so you can schedule updates exactly as required.

## December 11th, 2024 - New Features - Conversational Workflow Enhancements (Chatflow)

Introducing Chatflow-a dedicated workflow type optimized for interactive, conversationdriven scenarios. Combined with expanded publishing options and scheduling triggers, this update helps you build smarter, chatbased applications for customer service and more.

## November 28th, 2024 - Better Prompt Sharing and Developer Tools

Save your favorite prompts to a shared resource library, making it simpler to maintain consistency across projects. Our enhanced integration tools now offer greater flexibility to seamlessly connect AgenticFlow with your existing systems.

## November 1st, 2024 - AI-Created Agents and More Options

Describe what you need in plain language and our system will generate a custom agent for you-cutting down on setup time and complexity. Choose from an expanded range of AI models that are tailored to meet both everyday and advanced challenges.

## October 24th, 2024 - Ready-to-Use Templates and a Fresh Look

Kickstart your projects with preconfigured templates designed to get you up and running quickly. Our newly redesigned homepage now highlights your recent work, favorites, and personalized recommendations from our community for an even smoother browsing experience.

## October 14th, 2024 - ReadytoUse Templates & a Refreshed Homepage

Rolled out a suite of interactive, preconfigured templates that enable you to create AI agents and workflows quickly and easily. The redesigned homepage now highlights your recent work, favorites, and personalized recommendations, giving you a clear overview of your most important projects at a glance. Further refinements in agent templates and visual content tools have enhanced the intuitive and engaging nature of the platform.

## August 30th, 2024 - Refined User Interface & Dashboard Enhancements

Made significant enhancements to the visual presentation of workspaces with updated dashboards, improved filetoURL inputs, and more intuitive chat interfaces. New system prompts and updated navigation elements help streamline your daytoday interactions, making it easier to find and manage projects. Performance tweaks throughout the user interface deliver a more responsive and enjoyable experience across the platform.

## July 26th, 2024 - Secure Credential Management & Collaborative Tools

Introduced tools for secure credential management and updated workspace settings to better support team collaboration. Enhanced file upload and sharing features ensure your media and data transfer reliably, while new options in agent settings improve the personalization of your workspace. UI updates and performance enhancements across the agent and chat functionalities have resulted in a smoother collaborative experience.

## June 28th, 2024 - Robust Multimedia and Data Integration

Enhanced video template nodes and visual processing tools now empower you to edit and generate dynamic multimedia content with ease. New integrations, such as seamless support for Google Sheet data via JSON, streamline the way you manage external data sources within your workflows. Behindthescenes updates (such as improved message queuing) contribute to a faster, more reliable automation experience.

## May 31st, 2024 - Improved Social Integration & User Collaboration

Upgraded social workflow frames and introduced new features to better manage public workspaces and account settings. Added user info APIs and streamlined export/import capabilities, making it easier for teams to collaborate and share workflows. Refinements to UI elements helped create a cleaner, more intuitive experience across the platform.

## April 26th, 2024 - Enhanced Validation & New Workflow Nodes

Strengthened input validation with improved data schema checks that help prevent errors during workflow execution. Introduced new nodes-such as textbased scraping and API call nodes-that simplify the creation of custom automation processes without extra manual work. Unified node settings across the platform for a more consistent and userfriendly experience.

## March 29th, 2024 - Optimized Core Components & Monitoring

Extensive refactoring of the core system improved response times and overall stability. Enhanced monitoring tools now provide you with realtime insights into workflow performance, ensuring that the platform runs reliably even under heavy use.

## March 11th, 2024 - Inception and Core Foundations

Launched the initial core components of AgenticFlow, establishing a robust platform built to support powerful, automated workflows that form the basis of everything you use today.


# Quickstart Hub

Get up and running with AgenticFlow in 5-15 minutes. These quickstart guides are designed for fast wins and immediate productivity.

## Start Here

### [Your First 5 Minutes](/get-started/your-first-5-minutes)

The absolute fastest way to get started. Complete your first automation in under 5 minutes.

**Perfect for**: Everyone, especially first-time users

***

## Choose Your Focus

### [Choose Your Path](/get-started/choose-your-path)

Role-based guidance to help you navigate the documentation based on your goals.

**Perfect for**: Understanding which features to learn first

***

## Feature Quickstarts (10-15 Minutes Each)

### [Agents Quickstart](/get-started/agents-quickstart)

Build your first AI agent with the visual configuration builder.

**You'll learn**:

* Creating an AI agent in minutes
* Configuring the 11-tab system
* Adding tools and knowledge
* Deploying and testing your agent

**Perfect for**: Building chatbots, AI assistants, customer service bots

***

### [Workflows Quickstart](/get-started/workflows-quickstart)

Create your first automated workflow with the drag-and-drop builder.

**You'll learn**:

* Building sequential automation
* Connecting nodes
* Using user inputs and actions
* Running and testing workflows

**Perfect for**: Process automation, data processing, integrations

***

### [Workforce Quickstart](/workforce/quickstart-15-min)

Deploy your first multi-agent team in 15 minutes.

**You'll learn**:

* Creating agent teams
* Visual orchestration with React Flow
* Agent communication patterns
* Team deployment and monitoring

**Perfect for**: Complex multi-step tasks, agent collaboration, advanced automation

***

## Additional Resources

### [Plans & Credits](/get-started/plans-and-credits)

Understanding the AgenticFlow pricing model and credit system.

### [API Keys Setup](/developers/api-keys)

Configure your AI provider API keys (Claude, OpenAI, Gemini, etc.)

## What to Do Next?

After completing a quickstart, dive deeper:

* **Agents** → [Full Agents Documentation](/ai-agents/03-agents)
* **Workflows** → [Full Workflows Documentation](/workflows/04-workflows)
* **Workforce** → [Full Workforce Documentation](/workforce/05-workforce)
* **Learn More** → [Learning Hub](/learn/02-learn)
* **Use Cases** → [Industry Examples](/use-cases/10-use-cases)

***

**Need help?** Check our [Troubleshooting Guide](/support/troubleshooting) or [Contact Support](/support/contact-support)


# Your First 5 Minutes

Get up and running with AgenticFlow in just 5 minutes - no technical experience required

**Having trouble getting started?** This guide walks you through your first successful experience with AgenticFlow, step-by-step, with actual screenshots and no assumptions about your technical background.

> **🎯 Goal**: By the end of these 5 minutes, you'll have created and tested your first AI agent, understand how credits work, and know exactly what to do next.

***

## Before You Start

**What You Need:**

* An AgenticFlow account (if you don't have one, [sign up here](https://agenticflow.ai))
* 5 minutes of uninterrupted time
* No technical skills required!

**What You'll Learn:**

* How to navigate the AgenticFlow dashboard
* How to create your first AI agent in under 2 minutes
* How to test your agent with a simple task
* How the credit system works
* Where to get help when you're stuck

***

## Step 1: Your Dashboard Tour (30 seconds)

When you first log into AgenticFlow, you'll see the Marketplace:

<figure><img src="/files/e23rlzY3mYZ1WH3XuoJp" alt=""><figcaption></figcaption></figure>

**Key Areas to Know:**

1. **Top Bar**: Quickly search templates and manage your profile and projects.
2. **+ Create Buttons**: Blue buttons to create new agents or workflows.
3. **Left Sidebar**: Navigate Marketplace, AI Studio (Agents, Workflows, Connections), AI Chat, Documents, and Settings.
4. **Credits Remaining**: See how many credits you have left to run agents and workflows.
5. **Main Area**: Browse, select, and use templates.
6. **Copilot chat**: AI Assistant helps answer your questions about AgenticFlow based on system documentation.

> **💡 Tip**: If your screen looks different, you might be in a different section. Click "Home" in the left sidebar to get to your dashboard.

***

## Step 2: Create Your First Agent (2 minutes)

Let's create a simple AI assistant. AgenticFlow has a sophisticated agent system, but we'll start simple.

### 2.1 Start Creating an Agent

1. **Click the "+ Create Agent" button** in the top right corner
2. **Enter basic information**:
   * **Agent Name**: `My Writing Assistant`
   * **Description**: `Helps me write better emails and content`
3. **Click "Create Agent"**

<figure><img src="/files/iorBtEuAseh50z3M75yt" alt=""><figcaption></figcaption></figure>

### 2.2 Configure Your Agent (The Real Power)

After creation, you'll see the agent configuration interface with multiple tabs. For now, we'll just set up the basics:

1. **Click the "System Prompt" tab**
2. **Replace the default prompt with this**:

```
You are a helpful writing assistant. You help users:
- Write professional emails
- Improve their writing style  
- Check grammar and tone
- Suggest better word choices

Always be friendly and constructive in your feedback.
```

3. **The system auto-saves** - you'll see a checkmark when saved

<figure><img src="/files/AF4JtYiuQukJD6O2lAyo" alt=""><figcaption></figcaption></figure>

> **💡 Advanced Note**: AgenticFlow agents can do much more (connect to 300+ tools, use knowledge bases, manage tasks, etc.) but we're starting simple.

***

## Step 3: Test Your Agent (1 minute)

Now let's make sure your agent actually works.

### 3.1 Start a Conversation

1. **Click "Chat" or "Test"** to open the chat interface
2. **Type this test message**: "Help me write a professional email to thank a client for their business"
3. **Press Enter or click Send**

<figure><img src="/files/23VaJ3C3ug6nWa4gMGax" alt=""><figcaption></figcaption></figure>

### 3.2 See the Magic Happen

Your agent should respond with a helpful email template within 10-20 seconds.

<figure><img src="/files/c2JSYxBroFODGApfHLPM" alt=""><figcaption></figcaption></figure>

### 3.3 What If Nothing Happens?

**If your agent doesn't respond:**

* Check your internet connection
* Make sure you have credits remaining (top right corner)
* Try a shorter, simpler message like "Hello"
* If still stuck, [join our Discord](https://qra.ai/discord) for instant help

***

## Step 4: Understand Credits (30 seconds)

Notice the credit counter in the bottom left? Here's what you need to know:

<figure><img src="/files/xadzvMc9UeybY21wc3vV" alt=""><figcaption></figcaption></figure>

**How Credits Work:**

* Each agent interaction costs 3-4 credits
* You get free credits to start with
* Different actions cost different amounts
* You can see your usage in Settings > Billing

**Don't Worry About Running Out:**

* The platform will warn you before you run out
* You can purchase more credits or upgrade your plan
* Free tier is generous enough for learning and testing

To view usage details, go to **Settings** (click your profile avatar or the bottom-left gear icon) → **Usage**.

<figure><img src="/files/DDbKd2wkLDMnKGL2o2lA" alt=""><figcaption></figcaption></figure>

***

## Step 5: What's Next? (1 minute)

Congratulations! You've successfully:

* ✅ Created your first AI agent
* ✅ Tested it with a real task
* ✅ Understood how credits work

### Immediate Next Steps

**Try These Simple Tasks with Your Agent:**

* "Help me write a follow-up email"
* "Make this text more professional: \[paste some text]"
* "What's a better way to say 'please let me know'?"

**When You're Ready for More:**

1. **Explore Templates**: Click "Templates" to see pre-built agents
2. **Create a Workflow**: Try the visual workflow builder
3. **Add Tools**: Connect your agent to Gmail, Slack, or other apps
4. **Join the Community**: [Discord](https://qra.ai/discord) for tips and help

***

## Getting Help

**If Something Doesn't Work:**

1. **Check the FAQ**: Common issues and solutions
2. **Join Discord**: <https://qra.ai/discord> - Real people, real-time help
3. **Email Support**: <support@agenticflow.ai>
4. **Community Forums**: <https://community.agenticflow.ai>

**Documentation that Actually Helps:**

* [Agents Quickstart](/get-started/agents-quickstart) - Deeper dive into agents
* [Workflows Quickstart](/get-started/workflows-quickstart) - Visual automation builder
* [Templates](/get-started/templates) - Ready-to-use solutions

***

## Troubleshooting Common Issues

### "I can't find the Create Agent button"

* Make sure you're on the main dashboard
* Look in the top right corner for blue buttons
* Try refreshing the page

### "My agent isn't responding"

* Check you have credits remaining
* Try a simpler message first
* Check your internet connection

### "The interface looks different from the screenshots"

* We update the interface regularly
* Core functionality remains the same
* [Contact support](mailto:support@agenticflow.ai) if you're completely lost

### "I'm out of credits already"

* Free tier includes substantial credits for testing
* Check Settings > Billing to see usage
* Consider upgrading if you're using it actively

***

**🎉 Success!** You've completed your first 5 minutes with AgenticFlow. You now know more than 80% of new users and have a working AI agent you can improve and expand.

**Questions?** We're here to help - [join our Discord](https://qra.ai/discord) and say hello!


# Choose Your Path

Find your perfect starting point for AgenticFlow - whether you're building chatbots, automating processes, or developing enterprise solutions

Welcome to AgenticFlow! We've designed multiple learning paths to help you get started based on your goals and experience level. Pick the path that best describes what you want to achieve.

***

## 🎯 **What Do You Want to Build?**

### 👥 **Path 1: "I want to build a Multi-Agent System/AI Workforce" 🌟**

**Perfect for**: Complex automation, multi-agent collaboration, advanced AI orchestration, enterprise workflows

**You'll learn**:

* Visual workflow builder with React Flow
* Multi-agent orchestration and delegation
* AI-powered decision trees and conditional logic
* Real-time collaboration and monitoring
* Advanced node types (Agent, Tool, Trigger, State)

**Start here**: 👉 [**🎨 Visual Workforce Builder Guide**](/workforce/multi-agent-systems-guide) → [**Workforce Quickstart**](/workforce/quickstart-15-min)

**Time to first result**: \~15 minutes ⏱️

***

### 🤖 **Path 2: "I want to build a chatbot/AI assistant"**

**Perfect for**: Customer service, personal assistants, Q\&A bots, support agents

**You'll learn**:

* How to create conversational AI agents
* Setting up knowledge bases for accurate responses
* Integrating with communication channels (Slack, Discord, websites)
* Managing multi-turn conversations

**Start here**: 👉 [**Agents Hub**](/ai-agents/03-agents) → [**Agents Quickstart**](/get-started/agents-quickstart)

**Time to first result**: \~10 minutes ⏱️

***

### ⚙️ **Path 3: "I want to automate business processes"**

**Perfect for**: Data processing, email automation, content generation, workflow automation

**You'll learn**:

* Building visual and traditional workflows
* Connecting multiple apps and services
* Processing files and data in bulk
* Setting up triggers and scheduling

**Start here**: 👉 [**Workflows Quickstart**](/get-started/workflows-quickstart)

**Time to first result**: \~15 minutes ⏱️

***

### 🏢 **Path 4: "I need advanced AI solutions"**

**Perfect for**: Enterprise integration, team collaboration, advanced security, compliance

**You'll learn**:

* Multi-agent orchestration and delegation
* Enterprise security and compliance features
* Role-based access control and team management
* Webhook integrations and API development

**Start here**: 👉 [**Key Concepts**](/learn/key-concepts) → [**Multi-Agent Orchestration**](/workforce/multi-agent-systems-guide)

**Time to first result**: \~30 minutes ⏱️

***

### 👨‍💻 **Path 5: "I'm a developer building integrations"**

**Perfect for**: API integrations, custom nodes, platform extensions, webhook development

**You'll learn**:

* Complete API reference and SDKs
* Building custom workflow nodes
* Creating MCP integrations
* Platform extension development

**Start here**: 👉 [**API Reference**](/developers/api) → [**CLI Command Reference**](/developers/agenticflow-cli-capabilities)

**Time to first result**: \~20 minutes ⏱️

***

## 🚀 **Quick Start Options**

### **⚡ Just Get Me Started! (5 minutes)**

If you want to see AgenticFlow in action immediately:

👉 [**Your First 5 Minutes**](/get-started/your-first-5-minutes)

This guide walks you through creating your first working agent in under 5 minutes with zero setup.

### **🧠 I Want to Understand First (10 minutes)**

If you prefer to understand the concepts before diving in:

👉 [**Key Concepts**](/learn/key-concepts)

Learn about agents, workflows, integrations, and the platform architecture.

***

## 🎯 **By Use Case**

### **Customer Service & Support**

* [Agent Hub](/ai-agents/03-agents) - Build customer service agents
* [MCP Integrations](/integrations/07-integrations) - Connect to communication tools

### **Content & Marketing**

* [Use Case Examples](/use-cases/10-use-cases)
* [MCP Integrations](/integrations/07-integrations)
* [Workflows Hub](/workflows/04-workflows)

### **Data & Analytics**

* [Workflows Hub](/workflows/04-workflows)
* [Research & Analysis](/use-cases/10-use-cases)
* [Integration Hub](/integrations/07-integrations)

### **Sales & CRM**

* [Sales & GTM Ideas](/use-cases/10-use-cases)
* [MCP Integrations](/integrations/07-integrations)
* [Workflows Hub](/workflows/04-workflows)

***

## 🔧 **By Technical Level**

### **🟢 Beginner (No coding required)**

* Visual workflow builder
* Pre-built templates
* Drag-and-drop agent creation
* **Start**: [Your First 5 Minutes](/get-started/your-first-5-minutes)

### **🟡 Intermediate (Some technical knowledge)**

* Custom integrations
* Advanced agent configurations
* Multi-step workflows
* **Start**: [Workflows Quickstart](/get-started/workflows-quickstart)

### **🔴 Advanced (Developer/Technical)**

* API development
* Custom node creation
* Enterprise deployment
* **Start**: [API Reference](/developers/api)

***

## 🎓 **Learning Resources**

### **Interactive Learning**

* [Video Series](/learn/video-series) - Guided walkthroughs
* [Use Cases & Examples](/use-cases/10-use-cases) - Real-world implementations
* [Learning Hub](/learn/02-learn) - Courses and tutorials

### **Reference Materials**

* [Node Reference](/reference/nodes) - Workflow node catalog
* [MCP Integrations](/integrations/07-integrations) - 300+ integrations
* [Support & Troubleshooting](/support/12-support) - Common issues and solutions

### **Community Support**

* [Discord Community](https://qra.ai/discord) - Real-time help and discussions
* [Feature Requests](https://agenticflow.featurebase.app/) - Vote on upcoming features
* [Support Hub](/support/12-support) - Frequently asked questions

***

## 🚨 **Need Help Choosing?**

Not sure which path is right for you? Here are some questions to help:

### **Ask yourself**:

1. **Do you want multiple AI agents working together?** → Go with **Workforce** (Path 1) 🌟
2. **Do you want something that talks back?** → Go with **Agents** (Path 2)
3. **Do you want to connect different apps automatically?** → Go with **Workflows** (Path 3)
4. **Are you building for a team or enterprise?** → Go with **Enterprise** (Path 4)
5. **Do you need custom integrations or APIs?** → Go with **Developer** (Path 5)

### **Still unsure?**

👉 **Start with** [**Your First 5 Minutes**](/get-started/your-first-5-minutes) - it's designed to work for everyone and will help you discover what you want to build.

### **Want personal guidance?**

* [Join our Discord](https://qra.ai/discord) and ask the community
* [Email our support team](mailto:support@agenticflow.ai)
* [Watch the video series](/learn/video-series) for live-style Q\&A

***

## 🎯 **Quick Links by Goal**

| I Want To...                  | Start Here                                      | Time  |
| ----------------------------- | ----------------------------------------------- | ----- |
| **Build AI Workforce** 🌟     | [Workforce Hub](/workforce/05-workforce)        | 15min |
| **Build a chatbot**           | [Agents Hub](/ai-agents/03-agents)              | 10min |
| **Automate emails**           | [Workflows Hub](/workflows/04-workflows)        | 15min |
| **Process data in bulk**      | [Workflows Hub](/workflows/04-workflows)        | 20min |
| **Multi-agent orchestration** | [Workforce Hub](/workforce/05-workforce)        | 20min |
| **Integrate with my app**     | [API Reference](/developers/api)                | 20min |
| **See what's possible**       | [Use Cases & Examples](/use-cases/10-use-cases) | 5min  |
| **Get help from humans**      | [Discord Community](https://qra.ai/discord)     | 1min  |

***

**🎉 Ready to get started?** Pick your path above, or jump straight into [Your First 5 Minutes](/get-started/your-first-5-minutes) to see AgenticFlow in action!

**💬 Questions?** We're here to help in [Discord](https://qra.ai/discord) or [email](mailto:support@agenticflow.ai).


# The AgenticFlow Playbook

The complete playbook for getting the best out of AgenticFlow — how to pick the right primitive (workflow, agent, or workforce), build each layer step-by-step, and ship it to real users. Every step in

This is the long-form guide to building on AgenticFlow *well* — not just making something run, but making the choices that keep it cheap, reliable, and shippable. It's written for two readers at once:

* **You**, working in the visual builder at [app.agenticflow.ai](https://app.agenticflow.ai)
* **Your AI copilot** (Ishi, Claude Code, Cursor, Codex…), driving the AgenticFlow CLI on your behalf

Every section ends with a **📋 copy-paste prompt**. Paste it into your AI copilot and it will do the step for you. That's the AgenticFlow ecosystem working as designed: *you brief your AI, your AI talks to our CLI, the CLI configures AgenticFlow, and AgenticFlow serves your customers.*

If you only have 20 minutes, do the [CLI Walkthrough](/welcome-to-agenticflow/cli-walkthrough) first. This playbook is the full journey.

***

## Part 1 — Think in three primitives

Everything you'll ever build on AgenticFlow is one of three things, or a composition of them:

| Primitive     | What it is                                                                                          | Reach for it when…                                                                     | Cost profile                          |
| ------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------- |
| **Workflow**  | A deterministic pipeline of nodes (LLM, scraping, API calls, image/video, data)                     | The task is a repeatable SOP: same inputs, same steps, every time                      | Lowest — a handful of credits, \~30s  |
| **Agent**     | A conversational AI with tools (web search, MCP apps, code execution, knowledge bases, *workflows*) | A human is in the conversation and the AI must decide which tool to use                | Medium — pay for judgment per turn    |
| **Workforce** | A team: a graph of agents, decision gates, and tools with shared state                              | The deliverable needs planning, routing, and quality control with no human in the loop | Highest — multiple agents per mission |

**The golden rule: build at the lowest rung that solves the problem.** The most common (and most expensive) mistake is building an agent where a workflow would do, or a workforce where an agent would do.

The three primitives **compose upward**:

* A workflow plugs into an agent as a **tool** — the agent decides *when* to run your SOP.
* A workflow plugs into a workforce as a **node** — the team gets a cheap deterministic baseline.
* Agents plug into workforces as **team members** with distinct roles.

Build the deterministic part once. Let every higher layer reuse it.

**📋 Copy-paste prompt — decide what to build:**

```
I want to automate this on AgenticFlow: [DESCRIBE YOUR TASK IN 2-3 SENTENCES].

Apply the composition ladder: is this a workflow (repeatable SOP, no judgment),
an agent (conversation + tool decisions), or a workforce (autonomous mission with
quality control)? Recommend the LOWEST rung that genuinely solves it, tell me why,
and name the closest AgenticFlow blueprint to start from. Run `af bootstrap --json`
first if you have CLI access.
```

***

## Part 2 — Set up once (5 minutes)

**In the browser:** sign up at [app.agenticflow.ai](https://app.agenticflow.ai) — workspace and project auto-create. Grab an API key from **Settings → API Keys** if your AI copilot will drive the CLI.

**For your AI copilot:**

```bash
npm install -g @pixelml/agenticflow-cli
af login                 # paste your API key
af bootstrap --json      # THE command — run it first, every session
```

`af bootstrap --json` returns your entire workspace in one call: auth status, existing agents and workforces, the full blueprint catalog with deploy commands, available models, and a command cheat-sheet. An AI that starts with bootstrap never guesses.

Also point your copilot at the built-in playbooks — guides written specifically for AI operators:

```bash
af playbook first-touch          # orientation
af playbook mas-graph-building   # before hand-authoring any workforce graph
```

**📋 Copy-paste prompt — onboard your AI copilot:**

```
You have the AgenticFlow CLI available (`af`). Start by running `af bootstrap --json`
and `af playbook first-touch`. Summarize for me: what's already in my workspace,
which blueprints look relevant to [MY BUSINESS/USE CASE], and what you'd build first.
Don't create anything yet.
```

***

## Part 3 — The Workflow layer: your productized SOP

A workflow is the thing you can sell fifty of per week at fixed marginal cost. Start here.

### 3.1 Deploy from a blueprint, then make it yours

Hundreds of blueprints ship with the platform. Deploy the closest one, inspect it, and customize — it's minutes, not hours:

```bash
af blueprints list --json                                  # browse (or filter in the UI templates gallery)
af blueprints get --id website-audit-lead-report --json    # inspect BEFORE deploying
af workflow init --blueprint website-audit-lead-report --json
```

Customizing is where the value is. Real example: the `website-audit-lead-report` blueprint scrapes a prospect's site, writes an audit, and emails it. For a lead-generation funnel you may want the report *returned* instead of auto-emailed (side effects should be opt-in) — so you remove the email nodes and reshape the inputs. Same skeleton, your funnel.

### 3.2 The conventions that save you an afternoon

* **Update uses the create shape.** `af workflow get` returns nodes wrapped in `{"nodes": {"nodes": [...]}}`; `af workflow update --body` expects the flat create shape plus `output_mapping`, `project_id`, and `public_runnable`. Run `af workflow validate --body @file.json` before every update — the local validator catches shape issues instantly.
* **Templating reaches into everything.** `{{input_var}}` works inside `api_call` URLs (`https://api.example.com/quote/{{ticker}}`), node prompts, and headers. `response_type` is `"json"` or `"string"` — use `"string"` for CSV, RSS, or XML sources.
* **Test data sources from inside a run, not from your laptop.** Public APIs treat platform infrastructure differently than your home IP — some want a browser `User-Agent` header (a normal node config field), a few won't serve datacenter ranges at all. One test run tells you immediately.
* **Debug at the node level.** `af workflow run --wait --json` returns the final output at `.output.content` and every node's inputs/outputs under `.state.nodes_state[]`. Final outputs summarize; node states explain.

### 3.3 Ship it

A finished workflow can run four ways: manually, on a **schedule** (cron), from a **webhook** (your website's form → workflow), or **inside an agent or workforce** (Parts 4 and 5). If a workforce will call it, set `public_runnable: true` now — you'll need it in Part 5.

**📋 Copy-paste prompt — build your first workflow:**

```
Build me an AgenticFlow workflow for this SOP: [DESCRIBE — e.g. "given a prospect's
website URL, produce a client-ready audit of their lead-capture gaps"].

Steps: (1) run `af blueprints list --json` and pick the closest blueprint;
(2) deploy it with `af workflow init`; (3) customize it to my SOP — remove any
side-effect nodes (email/posting) so it RETURNS the result instead; (4) run it once
with realistic test inputs using --wait, then read .state.nodes_state[] and confirm
every node's real output looks right — not just the final text; (5) give me the
workflow ID, the run output, and what it would cost per run in credits.
```

***

## Part 4 — The Agent layer: the front door

Your team (or your clients) shouldn't need to know workflow IDs. They should ask a chat window in plain language — and the right SOP should fire.

### 4.1 Scaffold with tools included

```bash
af agent init --blueprint research-assistant --json
# → an agent with web_search, web_retrieval, api_call, string_to_json attached
```

### 4.2 Attach your workflow as a tool

This is the composition move that makes the agent more than a chatbot:

```bash
af agent update --agent-id <id> --patch --body '{
  "name": "Client Intelligence Assistant",
  "system_prompt": "...when the user wants a website audit, call the audit workflow tool...",
  "tools": [{
    "run_behavior": "auto_run",
    "workflow_id": "<your workflow id>",
    "description": "Generate a client-ready website audit. Inputs: website_url, audit_focus. Use whenever the user asks to audit or review a website.",
    "timeout": 300
  }]
}' --json
```

Two details carry all the weight:

* **`--patch` is load-bearing.** It fetch-merges-puts, so MCP clients, plugins, and the rest of your config survive a partial update.
* **The tool `description` is the advertisement to the agent's brain.** Write it like a function docstring: when to use it, what the inputs mean. A good description is the difference between the agent calling your SOP and the agent winging it.

### 4.3 Structured output — the contract

When an agent's answer must be machine-readable (routing decisions, form-filling, anything a workforce gate will read), enable JSON mode with this exact contract:

```json
"response_format": {
  "enable": true,
  "prompt": "Return the plan as JSON.",
  "schema": {
    "name": "mission_plan",
    "strict": true,
    "schema": {
      "type": "object",
      "additionalProperties": false,
      "properties": { "route": { "type": "string", "enum": ["workflow", "research"] } },
      "required": ["route"]
    }
  }
}
```

Both halves matter: the `{name, strict, schema}` wrapper, and `"additionalProperties": false` on **every** object level — that's how strict mode works, and AgenticFlow passes your schema through faithfully.

### 4.4 The model-split rule

**Pin structured-output agents to a structured-output-native model** (`agenticflow/gpt-4o-mini` class): native strict-schema parsing at 10–20× lower cost per decision. **Spend frontier models on prose and judgment** — research, writing, critique. Splitting model spend this way is the single biggest lever on your credit bill.

### 4.5 Ship it

An agent is deployable the moment it works: public chat URL, web widget embed on your site, or publish to Discord / Slack / Telegram / WhatsApp (100 credits per platform). For an agency, that's a client-facing deliverable with zero deployment work.

**📋 Copy-paste prompt — build your front-door agent:**

```
Create an AgenticFlow agent that acts as the front door for my team.

(1) Scaffold from the research-assistant blueprint (`af agent init`).
(2) Rename it to "[NAME]" and write a system prompt for this job: [DESCRIBE — e.g.
"help my team research prospects and prepare for client calls"].
(3) Attach my workflow <WORKFLOW_ID> as a tool with a docstring-quality description
of when to use it. Use `af agent update --patch` so nothing else gets clobbered.
(4) Test it: send a message that SHOULD trigger the workflow tool and confirm from
the response that the tool actually ran. Then send one that shouldn't, and confirm
it didn't.
(5) Give me the agent ID and the public chat link.
```

***

## Part 5 — The Workforce layer: the team that runs without you

A workforce is for **missions**: "here's a goal; come back with a verified deliverable." Not a chat, not a fixed pipeline — planning, routing, judgment, and quality control with nobody watching.

### 5.1 The autonomous desk — one command

The highest-leverage workforce pattern ships as a blueprint (CLI ≥ 1.10.7):

```bash
af workforce init --blueprint autonomous-desk --json
```

One command creates four agents and wires the full graph:

```
trigger → Planner (structured JSON: route + research questions)
        → decision gate
            ├─ workflow route → runs your deployed WORKFLOW (cheap deterministic baseline)
            └─ research route → Researcher (live web tools)
        → shared state merges either branch into one draft
        → Critic (structured verdict: approved / score / itemized feedback)
        → QA gate
            ├─ approved → Editor → output
            └─ rejected → Researcher revises against the critic's feedback → Editor → output
```

To give the desk your Part-3 workflow as a deterministic execution route:

```bash
af workflow update --workflow-id <wf_id> --body '{... "public_runnable": true ...}' --json
af workforce init --blueprint autonomous-desk \
  --tool-workflow-id <wf_id> \
  --tool-workflow-purpose "one-line description the planner uses to route missions" \
  --tool-workflow-input '{"your_field": "{{nodes.agent_planner.output.structured_output.workflow_input_primary}}"}' \
  --json
```

### 5.2 Why the critic gate is the whole point

In a live production run of this exact desk, the mission was: *"Evaluate whether Apple still deserves a spot on our conservative long-term watchlist."* The planner routed it through the attached stock-brief workflow, which returned a clean live-data draft in thirty seconds. Then the critic **rejected it — 6/10** — because the mission asked for peer-valuation comparisons and quantified margin impact that a generic SOP doesn't cover. The QA gate sent it to the revision pass, the researcher deepened it with live web evidence against the critic's itemized feedback, and the editor shipped a final brief that plainly flagged what remained unverifiable.

Total human involvement after the trigger: zero. That's what you're buying at this layer: **not parallelism — quality control that runs without you.** The workflow produced the cheap baseline; agent judgment was spent only on the delta the mission demanded.

### 5.3 Hand-authoring custom graphs

The desk covers plan→verify→revise missions. For custom topologies, have your copilot read `af playbook mas-graph-building` first — it's the field-verified rulebook. The rules that matter most:

| You want              | Write                                                    |
| --------------------- | -------------------------------------------------------- |
| Trigger field         | `{{trigger.message}}`                                    |
| Agent's reply         | `{{nodes.<name>.output.last_message}}`                   |
| Agent's JSON field    | `{{nodes.<name>.output.structured_output.<field>}}`      |
| Shared state variable | `{{variables.<name>}}`                                   |
| Workflow result       | `{{nodes.<name>.output.output.workflow_output.content}}` |

* **References must be exact — including the `.output` hop.** A mistyped reference renders as an empty string, not an error (prompts often legitimately contain literal `{{...}}` text). So smoke-run every new graph once and check `node_start.node_input` in the event stream before trusting a mission.
* **Condition-node edges** use `connection_type: "condition"` with `{branch_index: 0}`; `-1` is the default/else branch — always wire one.
* **Branch merging:** each branch gets a `state_modifier` writing the same `variables.<x>`; downstream nodes read `{{variables.<x>}}` without caring which branch ran.
* **Workflow invocation** from a graph is a `plugin` node wrapping `call_other_workflow` — `workflow_input` is a JSON *string*, and the target workflow must be `public_runnable`.
* **Deploys diff nodes by name** — to change a node's type, rename it.

### 5.4 Ship it

```bash
af workforce publish --workforce-id <id> --json
```

That mints a public URL and a run endpoint anyone can trigger without platform auth:

```bash
curl -X POST https://api.agenticflow.ai/v1/workforce/public/<key>/run \
  -H 'Content-Type: application/json' \
  -d '{"trigger_data":{"message":"<mission>"},"stream":true}'
```

The run streams live JSON events — you can watch the planner hand off, the workflow execute, the critic pass judgment, node by node. `af workforce rotate-key` invalidates a leaked URL.

**📋 Copy-paste prompt — deploy your autonomous desk:**

```
Deploy an AgenticFlow autonomous desk for my missions.

(1) Run `af workforce init --blueprint autonomous-desk --dry-run --json` and show me
the plan. (2) Deploy it, attaching my workflow <WORKFLOW_ID> as the deterministic
route: set the workflow public_runnable first, and map its inputs from the planner's
structured output with --tool-workflow-input. (3) Publish it and give me the public
URL. (4) Run this test mission through the public endpoint and narrate the event
stream to me node by node — which route the planner chose, what the critic scored,
whether the revision pass fired:

Mission: [PASTE A REAL MISSION — e.g. "Evaluate whether <COMPANY> still deserves a
spot on our conservative long-term watchlist. I care about valuation stretch, margin
pressure, and pending legal exposure."]

(5) Show me the final deliverable and tell me what it cost in credits.
```

***

## Part 6 — Operating well: the habits that compound

**Verify at the node level, always.** Workflows: `.state.nodes_state[]`. Workforces: the event stream (`node_start` shows each node's *substituted* inputs — the fastest way to catch a templating mistake; `node_end` shows per-node status and output). Final outputs summarize; node-level state explains.

**Put a critic downstream of anything risky.** A node can produce a thin or empty result while the run itself completes. A QA-gate agent turns those into revision passes instead of shipped garbage. This is cheaper than it sounds — the critic is a small structured-output model.

**Split your model spend.** Small structured-output models for routing and verdicts; frontier models for research, writing, and critique. Revisit this whenever your credit bill surprises you.

**Blueprints are starting points, not products.** Deploy the closest one, then patch (`af agent update --patch`, `af workflow update`, `af workforce deploy`). Everything in this playbook — the audit workflow, the front-door agent, the desk — started life as a blueprint.

**Everything user-facing ends in a publish.** Chat URL, widget, messaging platforms, workforce public endpoint, webhooks, schedules. The artifact you build is already deployed the moment it works — use that.

**Let your AI copilot do the driving.** The CLI is built for it: `af bootstrap --json` as the single source of truth, `--json` on every command, local validators, schemas on demand (`af schema agent`, `af workforce node-types`), and built-in playbooks. Your job is the brief; the copilot's job is the plumbing.

***

## Part 7 — Troubleshooting quick reference

| Symptom                                                                      | Cause                                                           | Fix                                                                                                                                          |
| ---------------------------------------------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `workflow update` rejected with missing-field errors                         | Update expects the flat create shape                            | Send `nodes` as a flat array + include `output_mapping`, `project_id`, `public_runnable`; pre-check with `af workflow validate --body @file` |
| Workflow "succeeds" but the output is full of N/A                            | An upstream fetch returned an error page                        | Read `.state.nodes_state[]`, check the fetch node's `status_code` and body; add a `User-Agent` header or switch source                       |
| Agent create rejected: "Schema is missing required fields {'schema','name'}" | Bare JSON schema in `response_format`                           | Wrap it: `{"name": "...", "strict": true, "schema": {...}}`                                                                                  |
| Structured-output agent fails at runtime inside a workforce                  | Strict mode requires `additionalProperties: false`              | Add it to every object level of the schema; pin the agent to a structured-output-native model                                                |
| Workforce run "succeeds" but agents complain about empty inputs              | A template reference is off (usually the missing `.output` hop) | Check `node_start.node_input` in the event stream; fix refs to `{{nodes.<name>.output.<field>}}`                                             |
| Condition gate always takes the default branch                               | Gate is reading a field that isn't there                        | Confirm the upstream agent has `response_format` enabled and the gate reads `...output.structured_output.<field>`                            |
| Workflow node in a workforce fails with "Workflow is not public runnable"    | The invoked workflow isn't public-runnable                      | `af workflow update --workflow-id <id>` with `"public_runnable": true`                                                                       |
| Node type won't change on redeploy                                           | Deploys diff nodes by name; updates can't change type           | Rename the node (forces delete + create)                                                                                                     |
| Authenticated `workforce run` returns a user-info 400                        | Known API-key auth issue                                        | Publish the workforce and use the public run endpoint, or run from the web UI                                                                |

***

## The one-shot mega prompt

If you want the whole stack in one brief, paste this into your AI copilot:

```
You're my AgenticFlow operator. Build my three-layer automation stack end to end.

My business: [2-3 SENTENCES — who you serve, what you sell]
My repeatable SOP: [THE THING YOU DO OVER AND OVER — this becomes the workflow]
My team's front door: [WHO ASKS FOR THINGS AND HOW — this becomes the agent]
My missions: [THE BIG RECURRING ASKS — these go to the autonomous desk]

Process — follow the composition ladder, lowest rung first:
1. `af bootstrap --json`, then `af playbook first-touch`.
2. WORKFLOW: closest blueprint → deploy → customize to my SOP → remove side-effect
   nodes so it returns results → test-run and verify node-by-node via
   .state.nodes_state[].
3. AGENT: research-assistant blueprint → my front-door system prompt → attach the
   workflow as a tool with a docstring-quality description → test that the tool
   fires when it should and doesn't when it shouldn't.
4. WORKFORCE: `af workforce init --blueprint autonomous-desk` with my workflow
   attached as the deterministic route (--tool-workflow-id; set public_runnable
   first). Publish it. Run one realistic mission through the public endpoint and
   narrate the event stream.
5. Report: every resource ID and public URL, what each layer costs per run, and
   the one thing you'd improve next.

Rules: preview with --dry-run before creating; use --patch for agent updates;
small structured-output models for routing decisions, frontier models for prose;
verify every layer by RUNNING it, not by reading its config back.
```

***

## Where to go next

* [CLI Walkthrough — Build a Demo Stack](/welcome-to-agenticflow/cli-walkthrough) — the 20-minute hands-on version
* [Workforce Hub](/workforce/05-workforce) — multi-agent concepts and the visual builder
* [Workflow Nodes Reference](/reference/nodes) — every node type
* [Plans & Credits](/get-started/plans-and-credits) — what things cost
* `af playbook mas-graph-building` — the graph-authoring rulebook, inside the CLI


# Agents Quickstart

Complete guide to AgenticFlow's advanced agent system - based on actual code implementation

**New to AgenticFlow?** This guide covers the actual agent system as implemented in the platform - it's more sophisticated than typical AI chatbots.

## What Makes AgenticFlow Agents Different?

Unlike simple chatbots, AgenticFlow agents are configurable AI workers with:

* **300+ Tool Integrations** via MCP (Model Context Protocol)
* **Advanced Knowledge Management** with hybrid search (10-file limit per agent)
* **Task Management System** built-in for tracking work
* **Sub-Agent Architecture** for delegation and specialization
* **Workflow Integration** - agents can execute custom automations
* **Webhook Triggers** for enterprise system integration
* **Voice Input** with speech-to-text capabilities
* **File System Memory** for persistent context

***

## Creating Your First Agent (3 minutes)

AgenticFlow uses a "create-then-configure" approach rather than a wizard.

### Step 1: Initial Creation

1. **Click "Agents"** in the left sidebar
2. **Click "New Agent"**, then **click "from scratch"**
3. **Fill out basic info**:
   * **Name**: Choose a clear, descriptive name
   * **Description**: Optional, for your reference
4. **Click "Create Agent"**

The agent is created with defaults:

* Model: `agenticflow/gpt-4o-mini`
* Temperature: 0.1
* Welcome message: "Hello, how can I help you today?"
* Private visibility

<figure><img src="/files/xtsPr4ku9ygTes9gumEM" alt=""><figcaption></figcaption></figure>

### Step 2: Configuration Interface

After creation, you'll see **20 configuration tabs**. This is where the real power lies:

<figure><img src="/files/UTExG5PXdVhdLuZhqVaD" alt=""><figcaption></figcaption></figure>

***

## Core Configuration

### 1. Basic Information

* **Avatar Selection**: Built-in avatar picker or upload custom
* **Voice Input**: Enable speech-to-text for conversations
* **Description**: Update anytime

### 2. AI Model Configuration

**Available Models**:

* Multiple providers: OpenAI, Google Gemini, Anthropic Claude
* Automatic provider connection setup
* Welcome credits for PixelML provider

**Advanced Parameters**:

* **Temperature**: 0-1 creativity slider (default: 0.1)
* **Max Output Tokens**: 2000-50000 (optional, default: unlimited)
* **Max Input Tokens**: 2000-50000 (optional, default: unlimited)

<figure><img src="/files/cc5SLsA5fa5jKkzP463C" alt=""><figcaption></figcaption></figure>

### 3. System Prompt (Most Important)

* **Rich Markdown Editor** with formatting support
* **Auto-save** to prevent data loss
* This defines your agent's personality and capabilities

**Template System Prompt**:

```markdown
You are a [ROLE] specializing in [DOMAIN].

## Your Capabilities
- [List specific skills]
- [What you're expert at]
- [What tools you can use]

## Your Personality  
- Professional and helpful
- Ask clarifying questions when unsure
- Provide specific, actionable advice

## When helping users:
1. Understand their exact needs
2. Ask questions if anything is unclear  
3. Provide detailed, helpful responses
4. Offer concrete next steps
```

***

## Advanced Features (Where AgenticFlow Shines)

### 4. Knowledge Integration (RAG System)

**Text Knowledge** (Up to 10 files per agent):

* **Search Types**: Hybrid (default), Semantic, Full-text
* **Advanced Settings**:
  * **Top K**: 1-10 results (default: 5)
  * **Threshold**: 0-1 similarity (default: 0.2)
  * **Query Rewrite**: AI query optimization (default: on)
  * **Reranking**: Result reranking (default: off)
* **Auto-retrieval**: Automatic knowledge search

<figure><img src="/files/zHXweebPUfEcNhiwBd7J" alt=""><figcaption></figcaption></figure>

**Table Knowledge**:

* Structured data integration
* Queryable datasets

<figure><img src="/files/tLc4jvjer37L38nMZ8at" alt=""><figcaption></figcaption></figure>

### 5. MCP Tool Integrion (300+ Connectors)

**Model Context Protocol (MCP)** provides access to:

* **Connected MCP Servers**: Workspace-level integrations
* **Registry Servers**: Platform-wide tool library

**Per-Tool Configuration**:

* **Custom Description**: How agent sees the tool
* **Run Behavior**:
  * Auto-run (agent decides when to use)
  * Request Confirmation (asks user first)
* **Timeout**: 1-300 seconds (default: 150)
* **Tool Selection**: Enable/disable specific tools within each MCP server

**Tool Categories Available**:

* AI & ML Services
* Business Management & CRM
* Communication (Email, Slack, SMS)
* Data Analytics & Databases
* Developer Tools & APIs
* E-commerce & Payments
* Marketing & Social Media
* Productivity & Project Management

<figure><img src="/files/jN9refHeCba51cc9anwQ" alt=""><figcaption></figcaption></figure>

### 6. Workflow Integration (Custom Automation)

Agents can execute your custom workflows as tools:

* **Workflow Selection**: Choose from workspace workflows
* **Tool Configuration**:
  * **Description**: How the agent sees this workflow
  * **Run Behavior**: Auto-run vs Request Confirmation
  * **Timeout**: Execution time limit
  * **Input Override**: JSON parameter customization
* **Connection Detection**: Automatically identifies missing connections

<figure><img src="/files/jOOWAOf5oBph9sD75zMH" alt=""><figcaption></figcaption></figure>

### 7. Sub-Agent System

* **Hierarchical Architecture**: Agents can manage other agents
* **Delegation**: Route specialized queries to expert sub-agents
* **Coordination**: Master agent orchestrates multiple specialists

### 8. Task Management

Built-in task system for agents:

* **Task States**: Pending, In Progress, Completed, Cancelled, Blocked, Deferred
* **Priority Levels**: Low, Medium, High
* **Context Tracking**: Tasks linked to conversations

### 9. File System Tools

* **Memory Persistence**: Agents can read/write files
* **Session Context**: Maintain context across conversations
* **Document Management**: Handle and reference files

### 10. Advanced Chat Features

**Message Management**:

* **Suggested Messages**: Pre-defined conversation starters
* **Welcome Message**: Custom greeting
* **Auto-suggestions**: AI-powered response suggestions

**Chat Theming**:

* **Color Themes**: Default, Orange, Blue, Green, Yellow, Violet
* **Font Sizes**: Small, Medium, Large
* **Branding**: Hide/show "Powered by" attribution

### 11. Webhook Triggers (Enterprise Integration)

**External System Integration**:

* **HTTP Methods**: GET, POST, PUT, DELETE
* **Authentication**: None, Basic Auth, Bearer Token
* **Response Codes**: Configurable success handling
* **Custom Endpoints**: Unique webhook URLs per agent

***

## Testing Your Agent

### Chat Interface Features

Once configured, your agent supports:

* **Streaming Responses**: Real-time message generation
* **Multimodal Input**: Text, voice, file uploads
* **Tool Execution**: Visual previews of tool calls
* **Thread Management**: Conversation persistence
* **Anonymous Access**: Public agents work without login

### What Should Happen

1. **Natural Conversation**: Agent responds according to system prompt
2. **Tool Usage**: Agent automatically uses connected tools when relevant
3. **Knowledge Retrieval**: Searches knowledge base when needed
4. **Task Creation**: Can create and track tasks if enabled

<figure><img src="/files/GNoWsyE2pDdX9Y5iNBMD" alt=""><figcaption></figcaption></figure>

***

## Deployment Options

### Publishing Levels

* **Private**: Only you can access
* **Public**: Listed in public directory
* **Public Visible**: Accessible by direct link only

### Integration Options

* **Embed Code**: JavaScript widget for websites
* **API Access**: RESTful agent interaction
* **Webhook Endpoints**: External system triggers

### Sharing Features

* **Embeddable Chat**: Custom-branded chat widgets
* **Direct Links**: Share agent access links
* **Template Creation**: Convert agent to reusable template

***

## Pro Tips for Building Effective Agents

### 1. Start Simple, Then Expand

* Begin with basic chat functionality
* Add tools one at a time
* Test each addition thoroughly

### 2. Optimize Knowledge Base

* Use the 10-file limit strategically
* Choose high-quality, relevant documents
* Adjust search parameters based on testing

### 3. Tool Configuration Strategy

* Start with auto-run disabled for new tools
* Enable auto-run only after testing
* Use descriptive tool names for better AI understanding

### 4. System Prompt Best Practices

* Be specific about the agent's role and capabilities
* Include examples of good responses
* Set clear boundaries and limitations
* Update based on real conversations

### 5. Performance Monitoring

* Review chat logs regularly
* Monitor tool usage patterns
* Adjust configuration based on user feedback

***

## Understanding Costs

AgenticFlow uses a **bucket-based credit system**:

* **Base Cost**: \~4.0 credits per conversation turn
* **Tool Usage**: Additional costs for external API calls
* **Model Costs**: GPT-4 costs more than GPT-3.5
* **Knowledge Retrieval**: Included in base cost
* **File Processing**: May incur additional charges

**Credit Sources**:

* Subscription plans (with monthly credit buckets)
* One-time top-ups (non-expiring)
* Promotional credits
* Welcome credits (for new users)

***

## Troubleshooting Common Issues

### Agent Not Responding

* Check workspace credit balance
* Verify model configuration
* Ensure system prompt isn't empty

### Tools Not Working

* Check MCP server connection status
* Verify tool permissions and authentication
* Review timeout settings

### Knowledge Base Issues

* Ensure files are properly uploaded (max 10 per agent)
* Check search threshold settings
* Verify file format compatibility

### Performance Problems

* Reduce knowledge base size if responses are slow
* Adjust temperature for more consistent responses
* Consider switching to faster model (GPT-3.5 vs GPT-4)

***

## What's Next?

Once you have a working agent:

1. **Explore Templates**: Browse pre-built agents for inspiration
2. **Add MCP Integrations**: Connect to your favorite tools and services
3. **Create Workflows**: Build custom automation sequences
4. **Set Up Webhooks**: Integrate with external systems
5. **Build Sub-Agents**: Create specialized agent teams

**Advanced Features to Explore**:

* Multi-agent conversations
* Workflow orchestration
* Enterprise webhook integrations
* Custom knowledge base optimization
* Task management workflows

***

## Getting Help

**Need Assistance?**

1. **Discord Community**: <https://qra.ai/discord> - Real-time help
2. **Documentation**: Browse related guides
3. **Support Email**: <support@agenticflow.ai>
4. **Feature Requests**: <https://agenticflow.featurebase.app/>

**🎨 Visual Guides**:

* [**Agents Hub**](/ai-agents/03-agents) - **Complete agent configuration guide**
* [**Workflows Hub**](/workflows/04-workflows) - Drag-and-drop workflow creation
* [**Workforce Hub**](/workforce/05-workforce) - Multi-agent team orchestration

**Related Guides**:

* [Workflows Quickstart](/get-started/workflows-quickstart) - Build custom automation
* [MCP Integration Guide](/integrations/agenticflow-mcp) - Connect external tools
* [Key Concepts](/learn/key-concepts) - Understanding the platform

***

**Congratulations!** You now understand AgenticFlow's agent system. Unlike simple chatbots, you can build configurable AI workers that integrate with tools, manage tasks, and orchestrate complex workflows.

**Questions?** [Join our Discord](https://qra.ai/discord) - we're here to help you build amazing AI agents!


# Workflows Quickstart

Complete guide to AgenticFlow's dual workflow systems - traditional automation and visual workforce builder

**New to AgenticFlow?** Start with [Your First 5 Minutes](/get-started/your-first-5-minutes) guide first.

## What Makes AgenticFlow Workflows Different?

AgenticFlow has **TWO distinct workflow systems** for different use cases:

1. **Traditional Workflows** - Sequential step-based automation (like Zapier)
2. **Workforce** - Visual multi-agent workflow builder with React Flow

This is a workflow automation platform with 80+ node types and advanced configuration features.

***

## System 1: Traditional Workflows (Sequential Automation)

### What Are Traditional Workflows?

Linear, step-by-step automations that process data through a sequence of actions:

**Real Examples from the Platform**:

* Text processing → AI analysis → Email generation → Send
* Web scraping → Data extraction → Google Sheets export
* Image upload → AI enhancement → Background removal → Social media post
* CSV import → Bulk analysis → Report generation → Notification

### Available Node Types (80+ Actual Nodes)

**AI & Language Models**:

* `openai_ask_assistant` - GPT model interactions
* `openai_ask_chat_gpt` - Chat completions
* `claude_ask` - Anthropic Claude integration
* `gemini_ask` - Google's Gemini AI
* `pml_llm` - PixelML language models
* `perplexity_search` - AI-powered search
* `straico_prompt_completion` - Multi-model AI platform

**Image Processing**:

* `generate_image` - AI image generation
* `enhance_image_v2` - Image enhancement
* `face_swap` - Face replacement
* `remove_background` - Background removal
* `magic_upscale` - AI upscaling
* `inpainting` - Fill image areas
* `comfyui_gen_image` - Custom ComfyUI workflows

**Data Operations**:

* `web_scraping` - HTML content extraction
* `firecrawl_scrape` - Advanced web scraping
* `api_call` - HTTP API integration
* `google_search` - Search integration
* `dataset_import` - Data import/export
* `knowledge_retrieval` - RAG search

**Communication**:

* `email_sender` - Template-based email
* `telegram_send_message` - Telegram integration
* `telegram_send_photo` - Media sending

**Video & Audio**:

* `text_to_speech` - Voice generation
* `speech_to_text` - Transcription
* `image_to_video` - Video creation
* `lipsync` - Video lip synchronization
* `youtube_upload` - YouTube integration

**Integrations**:

* `mcp_run_action` - Model Context Protocol tools
* `replicate_run_model` - Replicate AI models
* `fal_run_model` - Fal.ai integration
* `google_sheet_export` - Spreadsheet creation

### Building a Traditional Workflow

#### Step 1: Create New Workflow

1. **Click "Workflows"** in sidebar
2. **Click "New Workflow"**
3. **Choose "Build from Scratch"** or **Select Template**

#### Step 2: Configure Basic Info

* **Name**: Descriptive workflow name
* **Description**: What this workflow does

<figure><img src="/files/UR5txAdW4R75BUqU4SqC" alt=""><figcaption></figcaption></figure>

#### Step 3: Build Your Workflow

**The Interface**:

* **Form-based Builder**: Step-by-step configuration
* **Drag-and-Drop Reordering**: Rearrange workflow steps
* **Variable System**: Use `{{variable}}` syntax to pass data between steps
* **Real-time Validation**: Immediate error checking

**Building Process**:

1. **Add Input Node**: Define what data comes into the workflow
2. **Add Processing Nodes**: Choose from 80+ available actions
3. **Configure Each Step**: Set parameters using form interfaces
4. **Add Output Node**: Define what results are returned
5. **Connect with Variables**: Use `{{step_name.output}}` syntax

<figure><img src="/files/sIjY8CL8pY9HMxbtvSXJ" alt=""><figcaption></figcaption></figure>

#### Step 4: Test Your Workflow

**Execution Modes**:

* **Single Run**: Test with specific inputs
* **Table Run**: Bulk processing with CSV data
* **API Execution**: Programmatic triggering
* **Scheduled Runs**: Time-based automation

**Real-time Monitoring**:

* **Status Tracking**: `created | not_started | queued | running | success | failed | cancelled`
* **Progress Visualization**: See each step's execution state
* **Error Handling**: Detailed error messages and retry options
* **Performance Metrics**: Execution time and resource usage

<figure><img src="/files/kTREkBMirFJqvP52KnoJ" alt=""><figcaption></figcaption></figure>

***

## System 2: Workforce (Visual Multi-Agent Builder)

### What is Workforce?

A visual, node-based workflow builder using **React Flow** for complex multi-agent scenarios:

**Technology**:

* **React Flow**: Professional node-based editor
* **Flowgram.ai Integration**: Advanced layout and collaboration features
* **Real-time Collaboration**: Multi-user editing
* **Auto-layout**: Intelligent node positioning

### Workforce Node Types

```typescript
WorkforceNode Types:
- WorkforceAgentNode      // AI Agent interactions  
- WorkforceToolNode       // Workflow/tool execution
- WorkforceTriggerNode    // Workflow triggers
- WorkforceStateModifierNode // State management
```

**Connection Types**:

* `next_step` - Sequential flow
* `condition` - Conditional branching
* `ai_condition` - AI-powered decisions

### Building a Workforce Workflow

#### Visual Editor Features

* **Drag-and-Drop Canvas**: Intuitive node placement
* **Connection System**: Visual data flow arrows
* **Real-time Execution Overlay**: See execution progress in real-time
* **Keyboard Shortcuts**: Power-user productivity features
* **Auto-layout**: Automatic node organization

#### Agent Integration

* **Multiple AI Providers**: OpenAI, Claude, Gemini, Perplexity, DeepSeek
* **Tool Orchestration**: Agents can use traditional workflows as tools
* **Knowledge Integration**: Hybrid search across knowledge bases
* **MCP Client Support**: Extended tool capabilities

<figure><img src="/files/206YMrcxfydEL0Qf7xP2" alt=""><figcaption></figcaption></figure>

***

## Advanced Workflow Features

### Connection System (300+ Integrations)

**Connection Categories**:

* **AI Services**: OpenAI, Claude, Gemini, Replicate, FAL
* **Communication**: Email, Slack, Telegram, SMS
* **Data**: Google Sheets, Databases, APIs
* **Storage**: Cloud storage, file systems
* **Automation**: Zapier-like integrations

**Authentication Types**:

* OAuth2 (with automatic refresh)
* API Key authentication
* Basic authentication
* Custom authentication headers

### Bulk Processing System

**Table Workflows**:

* **CSV Upload**: Process hundreds of rows efficiently
* **Progress Tracking**: Real-time progress for bulk operations
* **Error Handling**: Failed row identification and retry
* **Parallel Processing**: Optimized for large datasets

**Performance Features**:

* **Queue Management**: Efficient job processing
* **Resource Optimization**: Dynamic scaling based on load
* **Cache Layer**: Redis-based performance optimization

### API & Integration Features

**REST API Access**:

* **Programmatic Control**: Full workflow automation via API
* **Webhook Triggers**: External system integration
* **Authentication**: Multiple auth methods (Basic, Bearer token)
* **Rate Limiting**: Built-in API protection

**Enterprise Features**:

* **Workspace Management**: Team-based workflow organization
* **Role-based Access**: Granular permission controls
* **Audit Logging**: Complete execution history
* **Performance Monitoring**: Performance tracking and alerting

### Template System

**Pre-built Templates**: Categories include:

* **Marketing**: Content generation, social media automation
* **Data Processing**: CSV analysis, web scraping, data enrichment
* **Content Creation**: Blog posts, video generation, image processing
* **Analysis**: Sentiment analysis, competitive research
* **Communication**: Email campaigns, customer support automation

**Template Features**:

* **One-click Cloning**: Duplicate and customize workflows
* **Public Marketplace**: Share workflows with community
* **Version Control**: Template updates and change tracking
* **Collaboration**: Team template libraries

***

## Choosing the Right System

### Use Traditional Workflows When:

* **Sequential Processing**: Step-by-step data transformation
* **Bulk Operations**: Processing large datasets (CSV files)
* **Simple Logic**: Linear workflows without complex branching
* **Integration Focus**: Connecting multiple services in sequence
* **Scheduled Automation**: Time-based recurring tasks

**Examples**:

* Email marketing sequences
* Data processing pipelines
* Content generation workflows
* API integrations and data sync

### Use Workforce When:

* **Complex Decision Trees**: Multiple conditional paths
* **Multi-Agent Scenarios**: Different AI specialists for different tasks
* **Real-time Collaboration**: Teams building workflows together
* **Visual Complexity**: Workflows with many branches and conditions
* **Agent Orchestration**: Managing multiple AI agents working together

**Examples**:

* Customer service routing (different agents for different issues)
* Complex analysis workflows (research → analysis → reporting → decision)
* Multi-step approval processes
* Dynamic content creation with multiple review stages

***

## Practical Example: Building Your First Workflow

Let's build a "Content Analyzer" that processes text and generates insights:

### Traditional Workflow Approach

**Steps**:

1. **Text Input** - User provides content to analyze
2. **Sentiment Analysis** - AI determines emotional tone
3. **Key Topics** - Extract main themes
4. **Summary Generation** - Create concise summary
5. **Action Items** - Generate next steps
6. **Email Report** - Send results to user

**Node Configuration**:

```
Input: Text Content
↓ ({{text_content}})
Sentiment Analysis: OpenAI Ask Assistant
↓ ({{sentiment_analysis.result}})  
Topic Extraction: Claude Ask
↓ ({{topics.result}})
Summary Generation: GPT-4
↓ ({{summary.result}})
Email Generation: Template + Send Email
```

### Testing and Iteration

1. **Start Simple**: Build with 2-3 nodes first
2. **Test Each Step**: Run individual nodes to verify output
3. **Add Complexity**: Gradually add more processing steps
4. **Monitor Performance**: Check execution times and costs
5. **Optimize**: Adjust model choices and parameters

***

## Cost Management

### Credit System (Actual Implementation)

**Bucket-Based Credits**:

* **Workspace Credits**: Shared across team members
* **Expiring Buckets**: Subscription credits expire monthly
* **Non-Expiring**: Top-up credits persist
* **Automatic Refunds**: Failed workflows get credit refunds

**Cost Factors**:

* **Base Execution**: \~4.0 credits per workflow run
* **Node Costs**: Different nodes have different pricing
* **Model Costs**: GPT-4 more expensive than GPT-3.5
* **External API Calls**: Additional costs for third-party services

**Cost Optimization**:

* Choose appropriate models for each task
* Use caching when possible
* Optimize workflow logic to reduce unnecessary steps
* Monitor usage in workspace billing dashboard

***

## Troubleshooting Common Issues

### Workflow Not Running

* **Check Credits**: Ensure workspace has sufficient credits
* **Verify Connections**: Ensure all external services are connected
* **Validate Variables**: Check variable syntax `{{variable_name}}`
* **Review Logs**: Use execution logs to identify failures

### Performance Problems

* **Node Optimization**: Choose faster models when appropriate
* **Parallel Processing**: Use workforce for concurrent execution
* **Cache Strategy**: Implement caching for repeated operations
* **Resource Limits**: Monitor timeout settings

### Integration Issues

* **Connection Status**: Verify OAuth tokens haven't expired
* **API Limits**: Check third-party service rate limits
* **Data Format**: Ensure data matches expected node input formats
* **Error Handling**: Implement proper error handling in workflows

***

## What's Next?

### Advanced Features to Explore

1. **MCP Integration**: Connect to Model Context Protocol tools
2. **Custom Connections**: Build integrations with your internal systems
3. **Webhook Automation**: Set up external trigger systems
4. **Bulk Processing**: Handle large-scale data operations
5. **Multi-Workflow Orchestration**: Chain workflows together

### Learning Path

1. **Master Templates**: Study pre-built workflows for your industry
2. **Build Progressively**: Start simple, add complexity gradually
3. **Join Community**: Share workflows and get feedback
4. **Monitor Performance**: Use analytics to optimize workflows
5. **Scale Up**: Move from single workflows to workflow orchestration

***

## Getting Help & Resources

**Community & Support**:

* **Discord**: <https://qra.ai/discord> - Real-time help
* **Documentation**: Complete guides for all features
* **Support**: <support@agenticflow.ai>
* **Feature Requests**: <https://agenticflow.featurebase.app/>

**🎨 Visual Guides**:

* [**Workflows Hub**](/workflows/04-workflows) - **Complete drag-and-drop guide**
* [**Agents Hub**](/ai-agents/03-agents) - 11-tab agent configuration
* [**Workforce Hub**](/workforce/05-workforce) - Multi-agent team orchestration

**Related Guides**:

* [Agents Quickstart](/get-started/agents-quickstart) - Build AI assistants
* [MCP Integration](/integrations/agenticflow-mcp) - Connect external tools
* [Templates Guide](/get-started/templates) - Use pre-built solutions

***

**🎉 Congratulations!** You now understand AgenticFlow's comprehensive workflow system. Whether you need simple sequential automation or complex multi-agent orchestration, you have the tools to build sophisticated business automation.

**Questions?** [Join our Discord community](https://qra.ai/discord) - we're here to help you build amazing workflows!


# Quickstart Templates

Templates in AgenticFlow AI

### Overview

Templates in AgenticFlow AI are ready-to-use workflows powered by large language models (LLMs). These templates are designed to help you quickly implement effective solutions across various business use cases without the need for extensive setup or customization. Our mission is to provide a diverse range of templates that can be easily adapted to meet your specific needs.

<figure><img src="/files/Q1MXDu3MCb1LpmTq2eWx" alt=""><figcaption></figcaption></figure>

### Key Features of Templates

* **Ready-to-Use**: Start automating tasks immediately with pre-built workflows.
* **Customizable**: Clone and modify templates to better suit your unique requirements.
* **Diverse Use Cases**: Access templates designed for different business scenarios, ensuring a solution for various needs.

### Using Templates

Templates can be used as they are, or you can clone them to create a customized version. Cloning a template creates a copy in your account, giving you full permission to modify it according to your preferences. This flexibility allows you to tailor workflows to your specific business processes while leveraging the robust framework provided by AgenticFlow AI.

#### How to Use Templates

1. **Access Templates**: Navigate to the Templates section from your AgenticFlow AI home page.
2. **Browse and Select**: Browse through the available templates to find one that fits your needs.
3. **Use** : Choose to use the template immediately by clicking **“Download”**.
4. **Customize**: Modify the cloned template to better align with your specific requirements.

<figure><img src="/files/XuJyq4ZP83CmUJPPCDT5" alt=""><figcaption></figcaption></figure>

### Categories of Templates

Templates are categorized based on their most frequent use cases, making it easier for you to find the right solution. Categories include:

* **Featured**: Highlighted templates that showcase popular and powerful workflows.
* **Operations**: Workflows designed to streamline and optimize business operations.
* **Marketing**: Templates focused on enhancing marketing efforts, such as content creation and customer engagement.
* **Research**: Analytical workflows to assist with data collection and analysis.
* **Sales**: Solutions aimed at improving sales processes and customer relationship management.
* **Other**: A variety of templates for miscellaneous use cases.

### Integration with Other Components

#### [Agents](#agents)

Agents in AgenticFlow AI utilize these templates to automate tasks and processes efficiently. By integrating templates with your AI agents, you can enhance their capabilities and streamline operations.

#### [Workflows](/workflows/04-workflows)

Templates often incorporate various tools powered by LLMs, enabling complex analysis and task automation. These workflows are designed to work seamlessly within the templates, providing powerful functionality with minimal setup.

#### [Data](#data)

Templates can be configured to work with multiple data formats, such as PDF, CSV, and audio files. This flexibility ensures that you can integrate your data sources easily and accurately.

#### [API Keys](#api-keys)

For templates requiring integration with third-party services, you can enter your own API keys. This allows you to leverage the capabilities of various vendors and enhance the functionality of your workflows.

### Conclusion

Templates in AgenticFlow AI offer a quick and effective way to implement AI-powered workflows across different business scenarios. With ready-to-use solutions, customizable options, and integration capabilities, you can harness the power of LLMs to drive efficiency and growth in your organization. Explore the available templates today and start transforming your business processes with AgenticFlow AI.

If you have any questions or need assistance, reach out to our [support team](mailto:support@agenticflow.ai) or [join our community forums](https://community.agenticflow.ai/) or [our Discord](https://qra.ai/discord) for further guidance.


# Plans & Credits

Different User Plans at AgenticFlow AI

AgenticFlow AI offers a variety of plans to suit your needs, each supporting different numbers of users, credits per execution, specific data sizes, and access to certain Large Language Models (LLMs). Below is an overview of the available plans and their specifications. For the most updated list, please visit the AgenticFlow AI pricing page.

### Overview of Plans

#### Free Plan

* **Users**: 1 user
* **Credits**: 100 credits per day
* **Data Size**: 10 MB
* **LLM Access**: Limited to basic models
* **Ideal For**: Individual users

#### Starter Plan

* **Users**: 1 user
* **Credits**: 7,500 credits per month
* **Data Size**: 100 MB
* **LLM Access**: Access to all latest LLMs
* **Bulk Workflow Runs**
* **Schedule Workflow Runs**
* **Ideal For**: Small teams and medium-sized projects

#### Advanced Plan

* **Users**: Up to 10 users
* **Credits**: 100,000 credits per month
* **Data Size**: 1 GB
* **LLM Access**: Access to advanced models
* **Private share links**
* **Ideal For**: Teams building workflows collaboratively

#### Advanced Plus Plan

* **Users**: Up to 50 users
* **Credits**: 300,000 credits per month
* **Data Size**: 5 GB
* **LLM Access**: Access to advanced models
* **Private share links**
* **Ideal For**: Larger teams building workflows collaboratively

#### Enterprise Plan

* **Users**: Unlimited users
* **Credits**: Custom credits per month
* **Data Size**: Custom data size
* **LLM Access**: Full access to all models
* **Ideal For**: Large enterprises with extensive needs

#### Custom Plans

For organizations with unique requirements, AgenticFlow AI offers custom plans. Contact our sales team to design a plan that fits your specific needs.

### Upgrading or Downgrading Your Plan

You can upgrade or downgrade your plan at any time based on your usage and workload. Simply visit your account settings and select the desired plan to adjust your subscription.

***

For the most updated list of plans and detailed pricing information, please visit the [AgenticFlow AI Pricing Page](https://agenticflow.ai/#pricing).


# Security Overview

Security and data-handling overview for AgenticFlow.

This page summarizes AgenticFlow security and data-handling practices. It is not a SOC 2, ISO 27001, HIPAA, PCI, GDPR, or other certification statement. Any compliance commitments, data residency requirements, support SLAs, or private deployment terms must be agreed in a signed enterprise agreement.

## Current Hosting

AgenticFlow is operated primarily in the United States unless a separate written agreement states otherwise. Region-specific hosting, customer-controlled cloud deployments, and private infrastructure are enterprise options that must be scoped separately.

## Platform Controls

AgenticFlow uses standard security controls for a SaaS workflow platform, including access controls, credential handling, and monitored production infrastructure. Specific controls may vary by plan, deployment model, integration, and third-party provider.

## Data Handling

Workflows, agents, knowledge bases, files, prompts, outputs, and integration payloads may be processed to provide the service. Some actions use third-party providers such as model APIs, storage providers, observability tools, payment processors, or analytics services.

Users should not send regulated or highly sensitive data unless their plan, configuration, provider settings, and contractual terms support that use case.

## AI Providers

Built-in and bring-your-own-key model calls may be processed by external AI providers. Provider handling depends on the model, route, API key, and provider terms in effect at the time of use.

## Security Questions

For security questions or vulnerability reports, email <support@agenticflow.ai> with a clear subject line.


# Learning Hub

Welcome to the AgenticFlow Learning Hub! Whether you're a beginner or looking to master advanced features, we have structured learning paths designed for you.

## Learning Paths

### For Beginners

1. [Your First 5 Minutes](/get-started/your-first-5-minutes) - Quick start
2. [Key Concepts](/learn/key-concepts) - Understand the fundamentals
3. Feature quickstarts ([Agents](/get-started/agents-quickstart), [Workflows](/get-started/workflows-quickstart), [Workforce](/workforce/quickstart-15-min))
4. Feature quickstarts ([Agents](/get-started/agents-quickstart), [Workflows](/get-started/workflows-quickstart), [Workforce](/workforce/quickstart-15-min))

### For Intermediate Users

1. [Use Cases & Examples](/use-cases/10-use-cases) - Learn from real examples
2. [Video Tutorials](/learn/video-series) - Visual learning
3. Feature deep dives in each section

### For Advanced Users

1. [API Documentation](/developers/api) - Technical integration
2. [Agent Hub](/ai-agents/03-agents) - Agent capabilities
3. [Developer Hub](/developers/api) - Platform internals

### For Team Leaders

1. [Security Overview](/policies/security-overview) - Security and data-handling overview
2. [Team Collaboration](/ai-agents/sharing) - Multi-user workflows

***

## Key Concepts

Start by understanding the core concepts that power AgenticFlow:

* [Key Concepts](/learn/key-concepts) - Core platform concepts
* [Knowledge Bases & RAG](/data-and-knowledge/06-data-knowledge) - How data works
* [MCPs & Integrations](/integrations/overview) - Tool connections

***

## Video Tutorials

Learn visually with our curated video content.

### [Video Tutorial Library](/learn/video-series)

* Topic-based tutorials
* Feature walkthroughs
* Office Hours recordings
* Community showcases

### Popular Video Series

* Getting Started Series
* Agent Builder Masterclass
* Workflow Automation 101
* Workforce Orchestration
* Integration Tutorials

***

## How to Navigate the Documentation

New to documentation? Read our [Navigation Guide](/welcome-to-agenticflow/navigation-guide) to learn:

* How the docs are organized
* Finding what you need quickly
* Using search effectively
* Understanding the structure

***

## Learning by Doing

### Templates & Examples

* [Agent Hub](/ai-agents/03-agents) - AI agents
* [Workflow Hub](/workflows/04-workflows) - Workflows
* [Workforce Hub](/workforce/05-workforce) - Multi-agent teams
* [Use Cases](/use-cases/10-use-cases) - Industry examples

### Hands-On Practice

* [Quickstart Guides](/get-started/01-quickstart) - Structured practice
* [Integration Guides](/integrations/07-integrations) - Step-by-step connections
* [Developer Hub](/developers/api) - API documentation

***

## Community & Support

### Learning Resources

* [Support Hub](/support/12-support) - Ask questions, share knowledge
* [Video Tutorials](/learn/video-series) - Video learning resources
* [Discord Community](https://qra.ai/discord) - Real-time help

### Getting Help

* [Support Hub](/support/12-support) - Quick answers and troubleshooting
* [Discord Community](https://qra.ai/discord) - Community support

***

**Ready to learn?** [Start with Your First 5 Minutes →](/get-started/your-first-5-minutes)


# Introduction to Large Language Models

## 🎬 **Get Started in 3 Minutes**

{% embed url="<https://www.youtube.com/watch?v=z2KetjMOAXY>" %}
What is AgenticFlow AI? (2:52) - Essential viewing for understanding how no-code AI automation empowers businesses with customizable platforms for building AI agent teams that work around the clock.
{% endembed %}

### **Learning Path Overview**

```mermaid
graph LR
    A[📺 Platform Overview<br/>2:52 min] --> B[📚 Core Concepts<br/>4 min total]
    B --> C[🛠️ First Build<br/>15 min]
    C --> D[🚀 Deploy & Scale]
    
    B --> B1[User Inputs<br/>21s]
    B --> B2[Actions<br/>1:25] 
    B --> B3[Knowledge<br/>1:44]
    
    style A fill:#e3f2fd
    style B fill:#f3e5f5
    style C fill:#e8f5e8
    style D fill:#fff3e0
```

**Next:** [Core Concepts Video Series (4 min total)](/learn/video-series) - *Essential foundation: User Inputs, Actions, and Knowledge*

## 🚀 **The Power of AI, Made Simple**

AgenticFlow is a no-code AI automation platform that puts the power of artificial intelligence directly into your hands—no programming required. Whether you're a business professional, entrepreneur, or creative, you can now build sophisticated AI automations using our intuitive visual interface.

## 🎯 **Why AI Automation Matters**

In today's fast-paced world, repetitive tasks consume valuable time that could be spent on strategic thinking and creative problem-solving. AI automation transforms how work gets done by:

* **Eliminating Manual Work**: Automate data processing, content creation, and routine communications
* **Scaling Operations**: Handle thousands of tasks simultaneously without human intervention
* **Improving Accuracy**: Reduce human error with consistent, intelligent processing
* **Availability**: Your AI workflows can run on configured schedules
* **Cost Reduction**: Replace expensive manual processes with efficient automation

## 🧠 **Understanding Large Language Models**

At the heart of AgenticFlow are **Large Language Models (LLMs)**—powerful AI systems that understand and generate human-like text. These breakthrough technologies have revolutionized how computers process language, enabling:

### **What LLMs Can Do:**

* **Understand Context**: Read and comprehend complex documents, emails, and data
* **Generate Content**: Create articles, emails, reports, and marketing materials
* **Analyze Information**: Extract insights from large datasets and documents
* **Translate Languages**: Convert text between dozens of languages
* **Answer Questions**: Provide intelligent responses based on knowledge and data
* **Make Decisions**: Follow rules and logic to process information automatically

### **Real-World Impact**

Major companies like Google and Microsoft have integrated LLMs into their core products, with Google describing it as "the biggest leap forward in the past five years." These same powerful technologies are now accessible to everyone through AgenticFlow's no-code platform.

## 🛠 **How AgenticFlow Makes AI Accessible**

### **Visual Workflow Builder**

Instead of writing code, you create AI automations by:

* **Dragging and dropping** workflow nodes onto a visual canvas
* **Connecting components** with simple point-and-click actions
* **Configuring settings** through user-friendly forms and dialogs
* **Testing workflows** with real-time preview and debugging

### **Pre-Built AI Agents**

Choose from hundreds of ready-to-use AI agents that can:

* Generate and edit images, videos, and audio
* Process documents and extract data
* Manage social media and marketing campaigns
* Handle customer service and communications
* Analyze data and create reports

### **193+ Workflow Nodes**

Mix and match from our extensive library of workflow components:

* **AI Models**: OpenAI GPT, Claude, Gemini, and 50+ other models
* **Integrations**: Connect to 300+ popular tools and services
* **Logic Controls**: Loops, conditions, and decision-making
* **Data Processing**: Transform, filter, and manipulate information
* **Communications**: Send emails, SMS, and notifications

## 🎨 **Multi-Agent Workforce System**

Our flagship **Workforce** feature lets you orchestrate multiple AI agents working together:

* **Visual Agent Builder**: Create specialized AI agents with unique roles and capabilities
* **Multi-Agent Coordination**: Have agents collaborate on complex projects
* **Real-Time Monitoring**: Watch your AI workforce in action
* **Scalable Architecture**: Handle enterprise-level workloads

## 🌟 **Why Choose No-Code AI?**

### **Speed to Value**

* Launch AI automations in minutes, not months
* No technical expertise required
* Immediate results and ROI

### **Flexibility**

* Easily modify workflows as needs change
* Test ideas without development costs
* Scale from simple tasks to complex processes

### **Enterprise-Ready**

* Built for security and compliance
* Handles high-volume operations
* Integrates with existing business systems

## 🚀 **Getting Started**

Ready to transform your work with AI automation? AgenticFlow makes it simple:

1. **Sign Up**: Create your free account in seconds
2. **Choose Your Path**: Start with agents or workflows based on your needs
3. **Build Visually**: Use our drag-and-drop interface to create automations
4. **Deploy & Scale**: Launch your AI solutions and watch them work

No coding required. No technical barriers. Just powerful AI automation at your fingertips.

If you have any questions or need assistance, reach out to our [support team](mailto:support@agenticflow.ai) or [join our community forums](https://community.agenticflow.ai/) or [our Discord](https://qra.ai/discord) for further guidance.


# Key Concepts

**Understanding the fundamental concepts that make AgenticFlow a powerful no-code AI automation platform.**

Before diving into building your first agents and workflows, it's important to understand the core concepts that power AgenticFlow's no-code approach to AI automation.

***

## 🤖 **AI Agents**

**AI Agents** are the conversational intelligence layer of AgenticFlow. Think of them as smart assistants that can understand natural language, access knowledge bases, and perform tasks through connected tools.

### **What Makes an Agent?**

* **Conversational AI** - Powered by advanced language models like GPT-4, Claude, and Gemini
* **Knowledge Integration** - Access to your documents, data, and information
* **Tool Connectivity** - Can use 300+ integrations to perform actions
* **Memory & Context** - Remembers conversations and learns from interactions
* **Customizable Personality** - Tailored voice, tone, and expertise for your brand

### **Agent Use Cases**

* **Customer Support** - Self-service help desk with access to your knowledge base
* **Sales Assistant** - Qualify leads and provide product information
* **Internal Helper** - Answer employee questions about policies and procedures
* **Research Assistant** - Gather and analyze information from multiple sources

***

## ⚡ **Visual Workflows**

**Visual Workflows** are drag-and-drop automation sequences that process data, connect systems, and execute business logic step-by-step.

### **Workflow Architecture**

```
📥 Input → 🔧 Process → 🔄 Transform → ✅ Validate → 📤 Output
```

### **Key Components**

* **193+ Pre-built Nodes** - Ready-to-use components for every task
* **Visual Builder** - Drag-and-drop interface for building automation
* **Data Processing** - Transform, clean, and analyze information
* **System Integration** - Connect any API, database, or service
* **Error Handling** - Built-in error recovery and retry logic

### **Workflow Types**

* **Traditional Workflows** - Linear, sequential processing
* **Conditional Workflows** - Decision trees and branching logic
* **Loop Workflows** - Repetitive operations and bulk processing
* **API Workflows** - Data synchronization and system integration

***

## 👥 **Workforce: Multi-Agent Teams**

**Workforce** is AgenticFlow's flagship feature that orchestrates multiple AI agents working together as coordinated teams.

### **Team Architecture**

```
🎯 Coordinator Agent
├── 🤖 Specialist Agent A (Research)
├── 🤖 Specialist Agent B (Writing)  
├── 🤖 Specialist Agent C (Quality Review)
└── 🤖 Specialist Agent D (Publishing)
```

### **Why Multi-Agent Teams?**

* **Specialization** - Each agent optimized for specific tasks
* **Scalability** - Add or remove agents based on workload
* **Quality Control** - Multiple layers of review and validation
* **Complex Problem Solving** - Break down sophisticated challenges
* **Reliability** - Redundancy and error recovery

### **Team Patterns**

* **Sequential Processing** - Agents work in order, building on each other's output
* **Parallel Collaboration** - Multiple agents work simultaneously on different aspects
* **Hierarchical Structure** - Manager agents coordinate worker agents
* **Dynamic Coordination** - Agents collaborate flexibly based on context

***

## 🔗 **Integrations: 300+ No-Code Connections**

**Integrations** connect AgenticFlow to your existing tools, databases, and services without requiring any coding.

### **MCP (Model Context Protocol)**

AgenticFlow uses the emerging MCP standard to provide seamless integrations:

* **300+ Pre-built Integrations** - Popular business tools and services
* **No-Code Setup** - Visual configuration with OAuth authentication
* **Real-time Data** - Live connections to your systems
* **Bi-directional Sync** - Read and write data to external systems

### **Integration Categories**

* **CRM & Sales** - Salesforce, HubSpot, Pipedrive
* **Communication** - Slack, Discord, Microsoft Teams
* **Productivity** - Google Workspace, Microsoft 365, Notion
* **Marketing** - Mailchimp, Hootsuite, Buffer
* **Development** - GitHub, GitLab, Jira
* **Analytics** - Google Analytics, Mixpanel, Segment

***

## 📊 **Data & Knowledge Management**

**Knowledge Integration** powers your agents with access to your organization's information and data.

### **Knowledge Sources**

* **Documents** - PDFs, Word docs, spreadsheets, presentations
* **Websites** - Company knowledge bases, documentation, blogs
* **Databases** - Direct connections to your data systems
* **APIs** - Real-time data from external services
* **File Storage** - Google Drive, Dropbox, SharePoint

### **Smart Processing**

* **Automatic Indexing** - AI-powered document analysis and categorization
* **Semantic Search** - Find information based on meaning, not just keywords
* **Vector Embeddings** - Advanced similarity matching for relevant content
* **Real-time Updates** - Keep knowledge bases current with live data

***

## 🎯 **Core Platform Features**

### **Visual Builders**

* **Drag-and-Drop Interface** - Build complex automation without coding
* **Real-time Preview** - See results as you build
* **Component Library** - 193+ pre-built nodes and components
* **Template System** - Start with proven patterns and customize

### **AI Models**

* **50+ AI Models** - GPT-4, Claude, Gemini, and specialized models
* **Model Selection** - Choose the right AI for each task
* **Cost Optimization** - Balance performance with operational costs
* **Custom Fine-tuning** - Train models on your specific use cases

### **Enterprise Features**

* **Role-Based Access Control** - Granular permissions and security
* **Multi-tenant Architecture** - Separate workspaces for clients or departments
* **Audit Logging** - Complete activity tracking for compliance
* **SSO Integration** - Enterprise authentication and identity management

***

## 🚀 **Getting Started Framework**

### **The AgenticFlow Approach**

1. **Start with Purpose** - Define what you want to automate or improve
2. **Choose Your Path** - Agents for conversation, Workflows for processes, Workforce for complexity
3. **Build Incrementally** - Start simple, add sophistication gradually
4. **Connect Your Data** - Integrate with your existing tools and information
5. **Measure & Optimize** - Track performance and continuously improve

### **Success Patterns**

* **Begin with High-Impact, Low-Complexity** - Quick wins build momentum
* **Focus on User Experience** - Design for your end users, not just efficiency
* **Iterate Based on Feedback** - Continuous improvement from real usage
* **Scale Systematically** - Add features and complexity as you learn

***

## 🎭 **Platform Philosophy**

### **No-Code First**

AgenticFlow is built on the principle that powerful AI automation should be accessible to everyone, not just developers:

* **Visual Configuration** - Everything configurable through intuitive interfaces
* **Pre-built Components** - Extensive library of ready-to-use elements
* **Template System** - Learn from proven patterns and best practices
* **Community Sharing** - Benefit from the collective knowledge of users

### **AI-Native Design**

Every feature is designed with AI capabilities in mind:

* **Intelligent Defaults** - AI helps configure and optimize your automation
* **Natural Language Interfaces** - Describe what you want in plain English
* **Adaptive Behavior** - Systems that learn and improve from usage
* **Contextual Assistance** - Smart suggestions and guidance throughout

***

## 📚 **Learning Path**

### **For Beginners**

1. [**Your First 5 Minutes**](/get-started/your-first-5-minutes) - Immediate hands-on experience
2. [**Choose Your Path**](/get-started/choose-your-path) - Find the right starting point for your goals
3. [**Agent Quickstart**](/get-started/agents-quickstart) - Build your first AI agent
4. [**Workflow Quickstart**](/get-started/workflows-quickstart) - Create your first automation

### **For Advanced Users**

1. [**Workforce Multi-Agent Guide**](/workforce/05-workforce) - Orchestrate AI teams
2. [**MCP Integrations**](/integrations/07-integrations) - Explore integrations and tools

### **For Developers**

1. [**API Reference**](/developers/api) - Technical documentation
2. [**Developer Hub**](/developers/api) - Development resources

***

## 🎯 **Next Steps**

Now that you understand the key concepts, you're ready to start building:

### **Quick Start Options**

* **Just Get Started**: [Your First 5 Minutes](/get-started/your-first-5-minutes)
* **Guided Learning**: [Choose Your Path](/get-started/choose-your-path)

### **Deep Dive Resources**

* [**Use Cases & Examples**](/use-cases/10-use-cases) - Real-world implementations
* [**Learning Hub**](/learn/02-learn) - Quickstarts and tutorials

### **Get Help**

* [**Community Discord**](https://qra.ai/discord) - Connect with other users
* [**Support Email**](mailto:support@agenticflow.ai) - Direct assistance
* [**Feature Requests**](https://agenticflow.featurebase.app/) - Suggest improvements

***

**Understanding these key concepts gives you the foundation to effectively use AgenticFlow's powerful no-code AI automation capabilities. Ready to start building? Choose your path and begin creating intelligent automation that transforms how you work.**


# Agents

Agent in AgenticFlow AI

### Your AI Assistant

#### Overview

An **Agent** in AgenticFlow AI is your personal AI assistant powered by Workflows and large language models (LLMs). While standard GPT or prebuilt LLMs have their limitations in terms of knowledge and capabilities, AgenticFlow AI allows you to enhance your AI assistant with the most relevant and useful workflows designed by you and your team. This means your agent is not just limited to prebuilt templates but can be customized to suit your specific needs.

#### Key Features of Agents

* **Enhanced Capabilities**: Empower the LLM behind your agent with a variety of workflows to extend its functionality.
* **Customizable Workflows**: Use workflows designed by you and your team, in addition to ready-to-use templates.
* **Natural Language Interaction**: Chat with your agent in natural language for a seamless user experience.

#### Getting Started with Agent

1. **Create an Agent**:
   * Click on the **+ New Agent** button to create a new agent.
2. **Configure and Customize**:
   * Click on the newly created agent to configure its settings and customize its workflows.
3. **Start Interaction**:
   * Begin chatting with your agent using natural language to leverage its capabilities.

For more detailed information, visit our Agent Documentation.

#### Links

On the sidebar, you have access to:

* **Home**: Your home page on AgenticFlow AI.
* [**Workflows**](/learn/key-concepts/workflows): Access workflows and actions powered by LLMs.
* [**Data**](/learn/key-concepts/data): Manage sources of truth provided by you in various formats such as PDF, CSV, and audio.
* [**Templates**](https://github.com/PixelML/agenticflow-docs/blob/main/docs/02-learn/key-concepts/templates.md): Utilize a variety of pre-built workflows maintained by AgenticFlow AI.
* [**API Keys**](https://github.com/PixelML/agenticflow-docs/blob/main/docs/02-learn/key-concepts/api-keys.md): Enter your own API keys for integration with supported vendors.

#### Conclusion

Agents in AgenticFlow AI offer a powerful and customizable solution for automating and enhancing your business processes. By combining the capabilities of LLMs with bespoke workflows, your AI assistant can perform a wide range of tasks more effectively. Start building your agent today and experience the full potential of AI-driven automation with AgenticFlow AI.

If you have any questions or need assistance, reach out to our [support team](mailto:support@agenticflow.ai) or [join our community forums](https://community.agenticflow.ai/) or [our Discord](https://qra.ai/discord) for further guidance.


# Workflows

Introduction to Workflows in AgenticFlow AI

### Overview

Workflows in AgenticFlow AI empower your agents and automate specific business processes with precision and efficiency. Designed to be highly customizable and flexible, workflows enable you to create powerful automations that drive productivity and growth.

#### Key Features of Workflows

* **No Code or Low Code**: Build workflows with minimal coding, making automation accessible to all users.
* **Powerful Customization**: Incorporate advanced Python and JavaScript code steps for greater functionality.
* **Support for 100+ LLMs**: Utilize a wide range of large language models to enhance your workflows.
* **Safe and Secure**: Ensure the security and privacy of your data and processes.
* **Easy to Maintain**: Simplify the management and maintenance of your workflows.

To start building a workflow, click on the **+ Create Workflow** button located at the top right of the Workflows page. You can choose from ready-to-use templates or create a custom workflow from scratch.

### Getting Started

The Workflow Builder consists of three main tabs:

1. **Use**
2. **Build**
3. **Logs**

#### 1. Use

The **Use** tab provides an interface to run and test your workflows. Inputs defined in the workflow will be visible as a form, and the output will be presented in a viewer that supports Markdown, HTML, and media formats.

**Usage Options**

* **App**: Run workflows as standalone applications.
* **Run in Bulk**: Execute workflows in bulk using CSV imports.
* **Chat**: Interact with workflows through a chat interface.
* **Schedule**: Automate workflows to run at scheduled intervals.
* **API**: Integrate workflows into other systems via API.

#### 2. Build

The **Build** tab is where you create and customize your workflows. You can select from a library of transformations and add them as steps in the workflow. Define the inputs expected by the workflow, such as file inputs or text inputs.

Each step in the workflow can be run individually within the builder for testing and debugging purposes.

**Building a Workflow**

1. **Create a Workflow**: Click on **+ Create Workflow**.
2. **Add Steps**: Select and configure steps from the transformation library.
3. **Define Inputs**: Specify the input types required for the workflow.
4. **Test and Debug**: Run individual steps to ensure the workflow functions correctly.

#### 3. Logs

The **Logs** tab allows you to view the execution logs of your workflows. This is useful for monitoring performance, troubleshooting issues, and ensuring that your workflows run as expected.

### Building a Workflow

To build a workflow, click on **+ Create Workflow** located at the top right of the Workflows page. You can start with a blank workflow or use one of the available templates.

#### Sharing a Workflow

As the owner of a workflow, you have full control over how it is shared with colleagues or teammates. By default, workflows are only accessible to you. However, you can share them using two types of links:

* **Sharable Link**: Grants permission to use the workflow.
* **Template Link**: Allows others to use and modify the workflow.

#### API Integration

Integrate your workflows into your website or other systems using the provided API. Detailed information about API integration is available in the API documentation.

### Templates

Templates are categorized based on their most frequent use cases. Browse through the categories to find templates that match your needs:

* **Featured**
* **Operations**
* **Marketing**
* **Research**
* **Sales**
* **Other**

### Conclusion

Workflows in AgenticFlow AI provide a robust and flexible solution for automating business processes. With powerful customization options, support for numerous LLMs, and an easy-to-use interface, you can create, share, and maintain workflows that drive efficiency and growth in your organization. Start building your workflows today and unlock the full potential of AI-driven automation.

If you have any questions or need assistance, reach out to our [support team](mailto:support@agenticflow.ai) or [join our community forums](https://community.agenticflow.ai/) or [our Discord](https://qra.ai/discord) for further guidance.


# Data

## Data in AgenticFlow AI

### Overview

In AgenticFlow AI, you can upload a wide variety of data sources to be used by AI for further analysis and as sources of truth. The platform supports multiple data formats, including PDFs, CSVs, audio files, and websites, as well as a broad range of integrations such as Figma, Zendesk, and YouTube.

#### Key Features of Data Management

* **Versatile Data Formats**: Upload data in various formats to ensure comprehensive coverage of your information needs.
* **Wide Range of Integrations**: Connect with numerous third-party services to enhance your data repository.
* **Centralized Data Storage**: All uploaded data is stored centrally, making it easily accessible for your AI workflows and agents.

#### Uploading Data

To upload data, navigate to the **Library** in the left sidebar, then click the **+ Resource** button. You will be guided through the upload data flow, allowing you to seamlessly add new data sources to the platform. Any data uploaded as knowledge in your workflows or tools will also be stored and displayed under the Data page.

#### Data vs. Knowledge

* **Data**: Refers to the raw sources of truth that you upload to the platform. This can include documents, spreadsheets, audio files, and more.
* **Knowledge**: Refers to the processed data that the AI uses for analysis. For example, a PDF file is considered data, while the vectorized version of the PDF (i.e., vectorized data) is considered knowledge for a question-answering AI engine.

### Managing Data

AgenticFlow AI makes it easy to manage your data sources. Once uploaded, your data is stored securely and can be used across various workflows and agents. This centralized approach ensures that your AI models have access to the most accurate and up-to-date information.

#### Integration with Workflows and Agents

Your uploaded data can be integrated into workflows and agents, enabling them to leverage this information for more accurate and relevant outputs. This integration ensures that your AI-driven processes are grounded in reliable data sources.

#### Security and Privacy

AgenticFlow AI provides data storage and retrieval features for workflows and agents. Review the Security Overview and Privacy Policy before uploading sensitive or regulated data.

### Links

* [**Home**](https://agenticflow.ai/): Access your AgenticFlow AI home page.
* **Agent**: Manage your AI assistants powered by LLMs and tools.
* [Workflows](/learn/key-concepts/workflows): Explore analysis tools and flows powered by LLMs.
* [**Templates**](https://github.com/PixelML/agenticflow-docs/blob/main/docs/02-learn/key-concepts/templates.md): Utilize a variety of pre-built tools and workflows maintained by AgenticFlow AI.
* **API Keys**: Enter your own API keys for integration with supported vendors.

### Conclusion

Data is a crucial component of the AgenticFlow AI platform, providing the foundation for powerful AI-driven analysis and automation. By supporting a wide range of data formats and integrations, AgenticFlow AI ensures that you can effectively manage and utilize your data to drive business insights and efficiency. Start uploading your data today and unlock the full potential of AI in your workflows and agents with AgenticFlow AI.

If you have any questions or need assistance, reach out to our [support team](mailto:support@agenticflow.ai) or [join our community forums](https://community.agenticflow.ai/) or [our Discord](https://qra.ai/discord) for further guidance.


# AgenticFlow MCP

Give your AI the “hands” it needs to actually do things—no more copy‑and‑paste. AgenticFlow now natively supports 2,500 MCPs (Model Context Protocol adapters) so your agents can interface with virtual

{% embed url="<https://www.loom.com/share/6c669aa9ff134f308934753b39e8ef48?sid=a3af067e-12f7-4a04-8668-eac13f0a0452>" %}
AgenticFlow MCP: Tap into 2,500+ Protocols to Make Your AI Agents Truly Action‑Capable
{% endembed %}

### What Is an MCP?

A **Model Context Protocol** (MCP) is a standardized “adapter” that exposes APIs and services to your LLM. With MCP, your model can:

* ✉️ Read and send emails in Gmail
* 📅 Manage calendar events
* 📂 Create or update documents in Google Docs
* 🔧 Interact with any API or local system service

Until now, LLMs like ChatGPT, Claude or Cursor could reason and answer, but couldn’t *act*—forcing you to copy results and paste them across apps. MCP changes that.

***

### Why 2,500+ MCPs Matter

Not every tool speaks the same language. By supporting over two thousand MCP adapters out of the box, AgenticFlow turns your AI into a universal agent:

* **Remote services**: CRM, marketing, analytics, payment gateways, and more
* **Local services**: File systems, internal databases, command‑line utilities
* **Custom APIs**: Anything your business needs

All managed through one simple MCP Server URL—no lengthy integration work.

***

### Getting Started in 3 Easy Steps

1. **Configure Your MCP Server**
   * Visit **agenticflow\.ai/mcp**
   * Choose **Cloud** (no install) or **Self‑host** with Docker/Kubernetes.
2. **Connect Your Accounts**
   * Browse the directory of 2,500+ MCPs.
   * Click a connector (e.g. Google Docs), follow the OAuth flow, and copy the generated MCP Server URL.
3. **Wire It into AgenticFlow**
   * In your AgenticFlow Dashboard under **AI → MCP**, paste the URL and assign a friendly name.
   * Voilà—your AI agents now “see” and “touch” that service.

***

### Live Demo: Writing to Google Docs

1. **Select Your Agent**
   * Open your agent in the visual designer (e.g., “Iris”).
2. **Add the Google Docs MCP**
   * Click **Add Tool** → choose “Google Docs” from your connected MCPs.
3. **Authorize & Extend**
   * Grant any additional API keys (e.g., for image generation).
   * Send a prompt:

     > “Append a poem about AgenticFlow’s 2,500 MCPs to this Doc.”
4. **Watch It Work**
   * Your agent appends text and even inserts an AI‑generated image directly into the Doc—no manual steps required.

***

### Go Beyond One‑Off Tasks

* **Embed** your agents on your website, Shopify or any storefront.
* **Publish** to public or private team workspaces.
* **Scale** across WordPress, Magento, BigCommerce, Facebook, Instagram, WhatsApp (coming soon), and more.

***

### Share Your Ideas

What MCPs would supercharge your workflows? Head to our **Roadmap & Feedback** page and let us know. Your suggestions drive our next 2,500 + connectors!

***

**Ready for Agents That Don’t Just Talk—but Act?**\
Get started with AgenticFlow MCP today at **agenticflow\.ai/mcp**.


# Video Tutorials

Quick video tutorials to get you started with AgenticFlow in under 15 minutes total.

## 📺 Core Getting Started Videos

### [Using Templates (7:01)](https://youtube.com/watch?v=be3rzuZQxbA)

**Perfect for:** Complete beginners who want to start with pre-built solutions

Learn how to:

* Browse AgenticFlow's template library
* Select templates that match your use case
* Customize templates for your specific needs
* Deploy templates with one click

**Key takeaway:** Start with templates to see AgenticFlow in action before building from scratch.

### [Sharing Your Workflow (1:11)](https://youtube.com/watch?v=be3rzuZQxbA)

**Perfect for:** Users who want to collaborate or showcase their work

Learn how to:

* Make your workflows public or private
* Generate shareable links
* Control access permissions
* Embed workflows in other applications

**Key takeaway:** AgenticFlow makes it easy to share your AI automation with others.

### [Clone to Edit (1:35)](https://youtube.com/watch?v=be3rzuZQxbA)

**Perfect for:** Users who want to customize existing workflows

Learn how to:

* Clone existing workflows and agents
* Modify cloned content safely
* Create variations for different use cases
* Build upon community contributions

**Key takeaway:** Don't start from scratch - clone and customize existing solutions.

## 🎯 Recommended Learning Path

1. **Start with templates** (7 minutes) - See what's possible
2. **Clone and customize** (1.5 minutes) - Make it your own
3. **Share your creation** (1 minute) - Show others your work

**Total time investment:** Under 10 minutes to go from zero to deployed AI solution!

## 🔗 Related Resources

* [Your First 5 Minutes](/get-started/your-first-5-minutes) - Hands-on written guide
* [Choose Your Path](/get-started/choose-your-path) - Decide between Agents, Workflows, or Teams
* [Templates Library](/get-started/templates) - Browse available templates

## 💡 Pro Tips from the Videos

* **Templates are learning tools** - Use them to understand AgenticFlow patterns
* **Cloning is collaboration** - Build on others' work and contribute back
* **Sharing drives adoption** - Show stakeholders working solutions, not concepts
* **Start simple** - Pick basic templates first, then explore advanced features

## 🎬 Next Steps

After watching these videos, you'll be ready to:

* [Build your first AI Agent](/ai-agents/03-agents)
* [Create a visual workflow](/workflows/04-workflows)
* [Set up a multi-agent team](/workforce/05-workforce)

***

*📺 These videos are part of our comprehensive 96-video library covering every aspect of AgenticFlow.*


# Office Hours #1

New Features, MCP Workflow, PDF Knowledge & Multi-Agent Sneak Peek

{% embed url="<https://www.loom.com/share/d9d6535422184890b5518b55cb241a01?sid=8dbc0b51-7368-417f-bffc-e254ebbd0a1e>" %}
AgenticFlow Office Hour #1 – New Features, MCP Workflow, PDF Knowledge & Multi-Agent Sneak Peek
{% endembed %}

### Overview of Agentic Flow Features and Onboarding

**1. Introduction and Purpose** [0:38](https://loom.com/share/d9d6535422184890b5518b55cb241a01?t=38)

![generated-image-at-00:00:38](https://loom.com/i/3158161801e94fe3b4b0dc768b88ef08?workflows_screenshot=true)

* Welcome and introduction by Sean from PixelML.
* Purpose of the session: to share new features and onboarding processes for Agentic Flow.

**2. Agenda Overview** [1:12](https://loom.com/share/d9d6535422184890b5518b55cb241a01?t=72)

![generated-image-at-00:01:12](https://loom.com/i/794730b9e75b4d1e829e5f5715373832?workflows_screenshot=true)

* Three main topics to cover:
  * New feature updates.
  * LinkedIn Enrichment Agent walkthrough.
  * Introduction to the Monday Agent System.

**3. New Feature Updates** [2:16](https://loom.com/share/d9d6535422184890b5518b55cb241a01?t=136)

![generated-image-at-00:02:16](https://loom.com/i/a3db165aa4414fd09aa9d8dfebf85730?workflows_screenshot=true)

* Community-first approach to feature development.
* Announcement of completed MCP node in Workflow.
* Explanation of how to connect and use MCP in Agentic Flow.

**4. LinkedIn Enrichment Agent** [1:54](https://loom.com/share/d9d6535422184890b5518b55cb241a01?t=114)

![generated-image-at-00:01:54](https://loom.com/i/ab0c6683ac1548fc8d46c0d67cf74dc0?workflows_screenshot=true)

* Overview of the LinkedIn Enrichment Agent built from customer requests.
* Demonstration of how to operate within the Agentic Flow system.

**5. Monday Agent System** [2:09](https://loom.com/share/d9d6535422184890b5518b55cb241a01?t=129)

![generated-image-at-00:02:09](https://loom.com/i/230372aa293340dbb28482a65fdf662d?workflows_screenshot=true)

* Introduction to the new Monday Agent System being released.

**6. Using MCP in Workflow** [2:28](https://loom.com/share/d9d6535422184890b5518b55cb241a01?t=148)

![generated-image-at-00:02:28](https://loom.com/i/153e80f9a48143919a8082a95bf95c24?workflows_screenshot=true)

* Steps to connect MCP server and use it in workflows:
  * Search for relevant documents.
  * Install and configure MCP.

**7. Creating a New Agent** [5:12](https://loom.com/share/d9d6535422184890b5518b55cb241a01?t=312)

![generated-image-at-00:05:12](https://loom.com/i/5a1b9dd8c23247abac9af319f597e5a7?workflows_screenshot=true)

* Instructions on creating a new agent from scratch.
* Demonstration of adding skills and knowledge to the agent.

**8. Building a Workflow** [9:08](https://loom.com/share/d9d6535422184890b5518b55cb241a01?t=548)

![generated-image-at-00:09:08](https://loom.com/i/d81fe875efa14962910ba7b256f282ba?workflows_screenshot=true)

* Explanation of the Workflow UI and how to create a new workflow.
* Example of generating text and images using different providers.

**9. Testing and Running Workflows** [11:07](https://loom.com/share/d9d6535422184890b5518b55cb241a01?t=667)

![generated-image-at-00:11:07](https://loom.com/i/54e660a658cb489682db614850c9b201?workflows_screenshot=true)

* Instructions on how to run and test workflows.
* Explanation of how to connect actions and manage outputs.

**10. PDF Upload Support** [24:14](https://loom.com/share/d9d6535422184890b5518b55cb241a01?t=1454)

![generated-image-at-00:24:14](https://loom.com/i/cdd62e592c6f43f08726cd2febb9b14a?workflows_screenshot=true)

* Announcement of new feature supporting PDF uploads.
* Instructions on how to upload and train agents with PDF documents.

**11. Conclusion and Q\&A** [51:26](https://loom.com/share/d9d6535422184890b5518b55cb241a01?t=3086)

![generated-image-at-00:51:26](https://loom.com/i/6b64f4d3bad34dd5ac4050943d84a8f1?workflows_screenshot=true)

* Recap of the session and open floor for questions.
* Encouragement to explore the new features and provide feedback.

#### Link to Loom

<https://loom.com/share/d9d6535422184890b5518b55cb241a01>


# Agents Hub

Build intelligent, conversational AI assistants that understand context, use tools, and complete tasks - all through AgenticFlow's intuitive visual interface. **No coding required.**

## What are AI Agents?

AI Agents are interactive assistants that combine the power of large language models with real-world capabilities. Think of them as AI team members that can:

* **Converse Naturally** - Chat with users in their own words, understanding context and nuance
* **Access Knowledge** - Search through your documents, databases, and knowledge bases instantly
* **Use Tools** - Connect to 300+ integrations including CRMs, databases, APIs, and business systems
* **Take Action** - Execute workflows, send messages, create records, and automate tasks
* **Remember Everything** - Maintain conversation history and context across multiple interactions
* **Handle Multiple Formats** - Process text, images, audio, video, and documents

Unlike simple chatbots with scripted responses, AgenticFlow agents think, reason, and make decisions to solve problems.

<figure><img src="/files/TLhbuh8SiIuOfe1nKycv" alt=""><figcaption></figcaption></figure>

## When to Use Agents

### Perfect for Interactive Assistance

**Customer Service & Support**

* Answer customer questions across configured support hours
* Look up order status and account information
* Escalate complex issues to human agents
* Provide personalized recommendations

**Sales & Lead Qualification**

* Engage prospects in real-time conversations
* Qualify leads with intelligent questioning
* Schedule demos and meetings
* Provide product information

**Internal Knowledge Assistants**

* Answer employee questions from company knowledge bases
* Onboard new team members
* Provide policy and procedure guidance
* Research and summarize information

**Personal Assistants**

* Schedule appointments and manage calendars
* Send reminders and follow-ups
* Draft emails and documents
* Organize tasks and projects

### When to Use Other Tools

**Use** [**Workflows**](/workflows/04-workflows) **Instead When:**

* You need scheduled, automated processes (e.g., daily reports)
* Tasks run without human interaction
* You're processing batches of data
* The sequence of steps is fixed and doesn't require decisions

**Use** [**Workforce**](/workforce/05-workforce) **Instead When:**

* Multiple specialized agents need to collaborate
* Complex tasks require handoffs between different AI roles
* You're building an entire AI team (sales, support, research, etc.)
* Tasks need orchestration across many steps and agents

***

## Getting Started

### Quick Paths to Building Agents

**New to AgenticFlow?** Start here:

* [**Agents Quickstart**](/get-started/agents-quickstart) - Build your first agent in 10 minutes
* [**Agent Configuration**](/ai-agents/system-prompt) - Learn the 11-tab configuration system

**Ready to customize?** Explore advanced features:

* [**Knowledge Bases**](/data-and-knowledge/06-data-knowledge) - Connect your data
* [**MCP Tools**](/integrations/07-integrations) - Add integrations

***

## The 11 Agent Capabilities

AgenticFlow agents are built by configuring **11 powerful capability areas**. Each capability is independent - use only what you need, or combine them all for maximum power.

<figure><img src="/files/KCJzl91YHYng0qxMQeJs" alt="" width="563"><figcaption></figcaption></figure>

### 1. Identity & Personality

**What it controls:** Your agent's name, description, and behavior **Set up:**

* Choose a name and description that reflects the agent's purpose
* Write a system prompt that defines personality, tone, and expertise
* Add a welcome message to greet users
* Create suggested conversation starters

**Example:** A customer support agent might introduce itself as "friendly and professional," use a warm greeting, and suggest starters like "Check my order status" or "I need help with a return."

### 2. AI Model Selection

**What it controls:** Which AI model powers your agent and how it thinks

**Choose from 100+ models across 7 providers:**

* **OpenAI** (17 models): GPT-4.1, GPT-5 family, O1/O3 reasoning models, GPT OSS
* **Anthropic** (8 models): Claude 4.5, 4.0, 3.7, 3.5 families
* **Google Gemini** (5 models): Gemini 3 Pro, 2.5, 2.0, 1.5 families (vision/video/audio)
* **Groq** (14 models): Ultra-fast Llama, Kimi, Qwen, Mistral models
* **DeepSeek** (2 models): V4 Flash (default — chat, reasoning, coding) and V4 Pro (frontier specialized)
* **PixelML** (50+ models): Unified access to all latest models
* **AgenticFlow** (11 models): Budget-friendly curated selection

**Fine-tune:**

* **Temperature** (0-1): Control creativity vs. consistency (default: 0.1)
* **Max Tokens**: Control response length (1K-128K depending on model)
* **Context Window**: Conversation history (50K-2M tokens depending on model)

**Quick Recommendations:**

* **General Business**: GPT-4.1 ($2/M), Claude 4.5 Sonnet ($3/M)
* **High-Volume/Budget**: Gemini 2.5 Flash Lite ($0.075/M), GPT-4.1 Nano ($0.08/M)
* **Coding**: GPT-5.1 Codex ($1.25/M), DeepSeek V4 Flash ($0.14/M)
* **Multi-Modal**: Gemini 2.5 Flash Lite (vision+video+audio, $0.075/M)
* **Reasoning**: O1/O3 ($1.10/M), DeepSeek V4 Flash ($0.14/M)

📚 [**Complete Model Selection Guide →**](/ai-agents/model-selection)

### 3. Knowledge & RAG (Retrieval)

**What it controls:** Your agent's access to custom knowledge bases, documents, and data **Connect to:**

* Knowledge bases you've created
* Datasets and data tables
* Uploaded documents (PDFs, Word, text files)
* Web pages you've crawled

**Configuration options:**

* **Search Strategy**: Hybrid search, semantic search, or full-text search
* **Auto-Retrieval**: Automatically search when relevant, or let the agent decide
* **Top Results (Top-K)**: How many knowledge chunks to retrieve (1-10)
* **Relevance Threshold**: Minimum similarity score (0-1)
* **Query Rewrite**: Optimize user questions for better retrieval
* **Reranking**: Re-score results for maximum relevance

**Example:** A product support agent can instantly search through 1,000 product manuals to answer technical questions.

📚 [**Complete Knowledge Configuration Guide →**](/ai-agents/knowledge)

### 4. Workflow Tools (Actions)

**What it controls:** Workflows your agent can execute as actions during conversations **How it works:**

* Connect existing workflows from your project
* Agent automatically calls the workflow when needed
* Results are returned to the conversation

**Configuration options:**

* **Workflow Selection**: Choose which workflow to execute
* **Tool Description**: Define when and how the agent should use this workflow
* **Timeout**: 1-300 seconds per execution (default: 150s)
* **Input Config**: Pre-fill constant values, security constraints, or workspace context

**Example:** A sales agent can execute a "Create Lead" workflow that adds prospects to your CRM automatically during conversations.

📚 [**Complete Workflow Tools Configuration Guide →**](/ai-agents/workflows)

### 5. MCP Tools (300+ Integrations)

**What it controls:** External tools and services your agent can use via the Model Context Protocol **Available categories:**

* CRM systems (Salesforce, HubSpot)
* Databases (PostgreSQL, MySQL, MongoDB)
* Cloud storage (Google Drive, Dropbox, S3)
* Communication (Slack, Email, SMS)
* Search engines and APIs
* 300+ total integrations

**Configuration:**

* Select which tools from each MCP client the agent can use
* Set auto-run or request confirmation per tool
* Configure timeouts (1-300 seconds)
* Override authentication headers

**Example:** An assistant agent can search Google, check your calendar, send Slack messages, and update spreadsheets - all in one conversation.

📚 [**Complete MCP Tools Configuration Guide →**](/ai-agents/mcp-tools)

### 6. Plugin Tools (Direct Node Execution)

**What it controls:** Individual workflow nodes your agent can execute directly **How it works:**

* Select specific nodes from the 193+ available workflow nodes
* Agent executes the node with custom inputs
* Perfect for simple, single-step actions

**Popular plugins:**

* API calls to any REST endpoint
* Data transformation and formatting
* File operations
* Text processing and extraction

[**View all 193+ available nodes →**](/reference/nodes)

**Example:** An agent can call a "Send Email" node directly without building an entire workflow.

📚 [**Complete Plugin Tools Configuration Guide →**](/ai-agents/plugin)

### 7. Sub-Agents (Agent Delegation)

**What it controls:** Other agents your agent can delegate tasks to **How it works:**

* Create specialized agents for different tasks
* Main agent routes requests to the right specialist
* Sub-agents complete tasks and report back

**Use cases:**

* Technical support agent → Escalates to billing specialist agent
* Intake agent → Routes to sales, support, or account management
* General assistant → Delegates research to research specialist

**Example:** A main receptionist agent delegates appointment scheduling to a calendar agent and customer inquiries to a support agent.

📚 [**Complete Sub-Agents Configuration Guide →**](/ai-agents/sub-agents)

[**Learn more →**](/workforce/05-workforce) for full multi-agent orchestration

### 8. Code Execution (Python Sandbox)

**What it controls:** The agent's ability to write and run Python code **Capabilities:**

* Perform calculations and data analysis
* Process files and text
* Generate charts and visualizations
* Execute custom logic

**Security:**

* Runs in isolated sandbox environment
* Optional file system access (restricted to project Drive)

**Example:** A data analyst agent can load a CSV, perform statistical analysis, and generate a summary report with charts.

📚 [**Complete Code Execution Configuration Guide →**](/ai-agents/code-execution)

### 9. File Attachments (Multi-Modal Input)

**What it controls:** What types of files users can send to your agent **Supported formats:**

* Images (JPEG, PNG, GIF, WEBP)
* Documents (PDF, Word, text)
* Audio files
* Video files

**Configuration:**

* **Max files per message**: 1-10 (default: 5)
* **Max file size**: 1-50MB per file (default: 10MB)

**Example:** A support agent can analyze screenshots of errors, a design agent can critique uploaded images, or a transcription agent can process audio recordings.

📚 [**Complete Chat Features Configuration Guide →**](/ai-agents/chat-features)

### 10. Task Management

**What it controls:** Whether your agent can create, track, and manage tasks **Capabilities:**

* Create tasks during conversations
* Assign tasks to users or teams
* Track task status and completion
* Link conversations to tasks

**Use cases:**

* Support agents creating follow-up tickets
* Sales agents tracking action items
* Project assistants organizing work

**Example:** During a support conversation, the agent creates a task for the engineering team to investigate a bug report.

📚 [**Complete Task Management Configuration Guide →**](https://github.com/PixelML/agenticflow-docs/blob/main/docs/03-agents/configuration/tasks.md)

### 11. Structured Output (Schema Validation)

**What it controls:** Format agent responses as structured JSON data **How it works:**

* Define a JSON schema for the response format
* Agent always returns data matching your schema
* Perfect for feeding into other systems

**Use cases:**

* Extract structured data from unstructured text
* Generate forms and database records
* Return consistent API responses
* Integrate with business systems

**Example:** A lead qualification agent always returns responses in this format:

```json
{
  "lead_name": "John Smith",
  "company": "Acme Corp",
  "email": "john@acme.com",
  "qualified": true,
  "interest_level": "high",
  "next_steps": "Schedule demo"
}
```

***

## How Agents Work Behind the Scenes

Understanding how agents think and operate helps you build better AI assistants.

### Conversation Threads

Every agent interaction happens in a **thread** - a persistent conversation:

* **Automatic Creation**: Threads are created automatically when a user starts chatting
* **Title Generation**: Threads can auto-generate titles based on the conversation
* **History Preservation**: All messages are saved and available for context
* **Multiple Conversations**: Each user can have multiple separate threads with the same agent

### How Agents Think (ReAct Pattern)

Agents use a sophisticated reasoning process:

1. **Understand** the user's message and intent
2. **Reason** about what information or actions are needed
3. **Act** by using tools, searching knowledge, or executing workflows
4. **Observe** the results of those actions
5. **Respond** with a helpful answer

This cycle can repeat multiple times in a single response. You can control how many steps an agent can take with the **recursion limit** (10-100 steps, default: 25).

### Streaming Responses

Agents stream responses in real-time, just like ChatGPT:

* See responses appear word-by-word
* Track tool usage as it happens
* Cancel long-running responses if needed
* Get immediate feedback, not delayed replies

### Smart Context Management

Agents automatically manage conversation history:

* **Context Window**: The amount of conversation history the agent can "see"
* **Automatic Trimming**: Old messages are removed when the context gets too large
* **Token Counting**: System tracks exactly how much context is used

### Suggested Replies (Optional)

Enable this feature to have the agent suggest follow-up questions or actions after each response. This uses additional credits but creates a more interactive experience.

***

## Agent Templates & Marketplace

Start faster with pre-configured agent templates.

### [Browse All Templates](/ai-agents/templates)

**Popular Templates:**

* **Customer Support Agent** - Answer questions, look up orders, create tickets
* **Sales Assistant** - Qualify leads, schedule demos, provide product info
* **Research Assistant** - Search knowledge bases, summarize documents, cite sources
* **Code Helper** - Debug code, explain functions, write documentation
* **Content Creator** - Draft emails, write social posts, create marketing copy
* **Data Analyst** - Analyze datasets, create visualizations, generate reports
* **Personal Assistant** - Manage calendar, send reminders, organize tasks
* **Knowledge Base Q\&A** - Answer questions from company documentation

### Creating Templates

Turn your own agents into reusable templates:

1. Build and test your agent
2. Save as template (private, workspace, or public)
3. Add example conversations to help others understand usage
4. Share in the marketplace or keep private for your team

***

## Building Great Agents: Best Practices

Learn from what works. Follow these proven patterns for success.

### Writing Effective System Prompts

**Be Specific About the Role**

```
✅ Good: "You are a customer service agent for Acme Corp's software products.
You help users troubleshoot technical issues, process refunds, and escalate
complex problems to human agents."

❌ Vague: "You are a helpful assistant."
```

**Set Clear Boundaries**

```
✅ Good: "You can help with order status, returns, and general product questions.
For billing disputes or account changes, escalate to a human agent.
Never share customer data or make promises about features we don't have."

❌ Unclear: "Help users with whatever they need."
```

**Include Examples of Good Interactions** Show the agent how you want it to behave with 2-3 example conversations in your system prompt.

**Use Personality Consistently** Pick a tone (professional, friendly, technical, casual) and maintain it throughout the system prompt.

### Choosing the Right Tools

**Less is More** Only add tools the agent actually needs. Each tool:

* Increases response time (agent has to consider it)
* Uses more credits (larger prompts)
* Adds complexity (more things that can go wrong)

**Maximum 50 tools** per agent

**Use Clear Tool Descriptions** The agent decides which tool to use based on descriptions. Make them specific:

```
✅ Good: "Get customer order status by order ID. Returns shipping status,
tracking number, and estimated delivery."

❌ Vague: "Order lookup tool."
```

**Choose Execution Mode Carefully**

* **Auto-Run**: For safe, read-only operations (lookup order, search knowledge)
* **Request Confirmation**: For actions that change data (send email, create ticket, charge credit card)

### Setting Appropriate Limits

**Recursion Limit**: How many steps the agent can take

* **Low (10-15)**: Simple Q\&A agents, minimal tool use
* **Medium (20-30)**: Standard agents with moderate complexity (default: 25)
* **High (40-100)**: Research agents, complex multi-step tasks

**Timeouts**: How long tools can run

* **Short (10-30s)**: Quick API calls, database queries
* **Medium (60-120s)**: File processing, email sending
* **Long (180-300s)**: Complex workflows, data analysis

### Temperature Settings for Different Use Cases

* **0.0-0.2**: Deterministic, consistent responses (customer support, data extraction)
* **0.3-0.5**: Balanced creativity and consistency (general assistants)
* **0.6-0.8**: More creative responses (content creation, brainstorming)
* **0.9-1.0**: Maximum creativity (creative writing, idea generation)

***

## Deploying Your Agent

Once you've built and tested your agent, make it available to users.

### Sharing Options

**1. Web Chat Widget** Embed your agent directly into your website. Users chat without leaving your site.

**2. Public Chat URL** Share a direct link to your agent. Anyone with the link can start a conversation (if agent is public).

**3. Messaging Platform Integration** Publish your agent to:

* **Discord** - Automated server support and community engagement
* **Slack** - Internal knowledge assistant and workflow automation
* **Telegram** - Customer support and notifications
* **WhatsApp** - Direct customer communication

**Cost**: 100 credits per platform publish

**4. Webhooks & Triggers** Trigger agent conversations from external events:

* Form submissions on your website
* Incoming emails
* Scheduled tasks
* Third-party app events

### Testing Before Launch

**The Testing Checklist:**

1. **Basic Conversation** - Start a chat, ensure agent responds
2. **Conversation Starters** - Test every suggested prompt
3. **Knowledge Retrieval** - Ask questions that require searching your knowledge base
4. **Tool Execution** - Trigger each tool at least once
5. **Error Handling** - Try to break it (invalid inputs, nonsense questions)
6. **Edge Cases** - Test boundary conditions (very long messages, multiple file attachments)
7. **Multi-Turn Conversations** - Have a 10+ message conversation to test context
8. **Privacy** - Verify the agent doesn't share sensitive information

***

## Monitoring & Optimization

Track performance and continuously improve your agent.

### Key Metrics to Monitor

**Usage Metrics:**

* Conversations per day/week
* Messages per conversation
* Active users
* Peak usage times

**Quality Metrics:**

* Average response time
* Tool success rate
* Knowledge retrieval accuracy
* User satisfaction (if you collect feedback)

**Cost Metrics:**

* Credits consumed per conversation
* Cost per message
* Most expensive tools/models
* Token usage trends

### Optimization Strategies

**If responses are too slow:**

* Reduce number of tools
* Lower recursion limit
* Switch to a faster model (GPT-4o Mini, Claude Sonnet)
* Reduce knowledge base size
* Disable query rewrite and reranking

**If costs are too high:**

* Use smaller models for simple tasks (GPT-4o Mini instead of GPT-4)
* Reduce max\_tokens limit
* Disable suggested replies
* Use cheaper models for knowledge retrieval
* Optimize system prompt length

**If knowledge retrieval is poor:**

* Enable query rewrite
* Adjust top-k (try 5-7 instead of 3)
* Lower relevance threshold (try 0.5 instead of 0.7)
* Enable reranking
* Restructure knowledge base documents
* Try hybrid search instead of semantic-only: reranking is automatically use when hybrid search is on.

**If tool usage is unreliable:**

* Improve tool descriptions
* Reduce total number of tools
* Add examples to system prompt
* Use request confirmation for critical tools
* Increase tool timeouts

***

## Related Documentation

### Core Platform Features

* [**Workflows**](/workflows/04-workflows) - Sequential automation and batch processing
* [**Workforce**](/workforce/05-workforce) - Multi-agent orchestration and team collaboration
* [**Knowledge Bases**](/data-and-knowledge/06-data-knowledge) - Managing documents and data
* [**Integrations**](/integrations/07-integrations) - 300+ available tools via MCP

### Enterprise & Deployment

* [**Security Overview**](/policies/security-overview) - Security and data-handling overview
* [**Developer API**](/developers/api) - API integration and webhooks (for developers)

### Learning Resources

* [**Learning Hub**](/learn/02-learn) - Foundation concepts and learning resources
* [**Video Tutorials**](/learn/video-series) - Visual walkthroughs
* [**Use Cases by Industry**](/use-cases/10-use-cases) - Real-world examples and templates

### Support

* [**Troubleshooting Guide**](/support/troubleshooting) - Comprehensive problem-solving
* [**Community & Support**](/support/community) - Ask questions and get help

***

## Quick Reference

### Essential Settings at a Glance

| Setting               | Purpose                      | Recommended Default                                               |
| --------------------- | ---------------------------- | ----------------------------------------------------------------- |
| **Model**             | AI model selection           | GPT-4o Mini or Claude 3.5 Sonnet                                  |
| **Temperature**       | Creativity vs. consistency   | 0.1 (consistent) to 0.7 (creative)                                |
| **Recursion Limit**   | Max reasoning steps          | 25 steps                                                          |
| **Tool Timeout**      | Max tool execution time      | 150 seconds                                                       |
| **Top-K (Knowledge)** | Knowledge chunks to retrieve | 5 results                                                         |
| **Search Strategy**   | Knowledge search method      | Hybrid search                                                     |
| **Max Tokens**        | Response length limit        | Model default                                                     |
| **Execution Mode**    | Tool auto-run behavior       | Auto-run (safe tools), Request confirmation (data-changing tools) |

### Common Agent Types & Settings

**Customer Support Agent:**

* Model: GPT-4o Mini (fast, cost-efficient)
* Temperature: 0.2 (consistent, professional)
* Knowledge: Product docs, FAQs, policies
* Tools: CRM lookup, ticket creation
* Recursion limit: 20

**Sales Assistant:**

* Model: Claude 3.5 Sonnet (conversational)
* Temperature: 0.4 (balanced)
* Knowledge: Product catalog, pricing, case studies
* Tools: CRM, calendar, email
* Recursion limit: 30

**Research Assistant:**

* Model: GPT-4 (highest quality reasoning)
* Temperature: 0.3 (accurate)
* Knowledge: Large knowledge bases, documents
* Tools: Web search, scholar search
* Recursion limit: 50

**Data Analyst:**

* Model: GPT-4o (data handling)
* Temperature: 0.1 (precise)
* Knowledge: Data dictionaries, analysis guides
* Tools: Code execution, file system
* Recursion limit: 40

**Content Creator:**

* Model: Claude 3 Opus (creative writing)
* Temperature: 0.7 (creative)
* Knowledge: Brand guidelines, style guides
* Tools: None (pure generation)
* Recursion limit: 15

***

## Next Steps

### Just Starting?

1. [**Try a Template**](/ai-agents/templates) - Start with a pre-built agent

### Ready to Build?

1. [**Configure System Prompt**](/ai-agents/system-prompt) - Define personality and behavior
2. [**Select AI Model**](/ai-agents/model-selection) - Choose the right model
3. [**Connect Knowledge**](/ai-agents/knowledge) - Add your documents and data
4. [**Add Workflow Tools**](/ai-agents/workflows) - Connect workflows as actions
5. [**Add MCP Tools**](/ai-agents/mcp-tools) - Connect to external systems
6. [**Enable Drive Access**](/ai-agents/drive) - Access file storage
7. [**Set Up Triggers**](/ai-agents/trigger) - Configure how to invoke your agent
8. [**Configure Sharing**](/ai-agents/sharing) - Make it available to users
9. [**Manage Versions**](/ai-agents/versioning) - Release and rollback safely

### Need Help?

* [**Troubleshooting Guide**](/support/troubleshooting) - Solve common issues
* [**Community Support**](/support/community) - Ask questions
* [**Video Tutorials**](/learn/video-series) - Watch how it's done

***

**Ready to build your first AI agent?** [Start the Quickstart →](/get-started/agents-quickstart)


# AI Model Selection

## 🧠 **Choose Your AI Engine**

### **Provider Connection Requirements**

> **⚠️ Important**: To use models from any provider (except AgenticFlow), you must first add a connection for that provider in your project's **Connection Settings**.
>
> * **AgenticFlow Provider**: Uses your AgenticFlow credits directly - no connection setup required
> * **All Other Providers**: Require a valid connection configured in Connection Settings
> * **Automatic Selection**: The server automatically uses the first available connection for the selected model's provider

**How to add a provider connection:**

1. Navigate to your project's **Connection Settings**
2. Add a new connection for your desired provider (OpenAI, Anthropic, Google, etc.)
3. Configure the required API keys and credentials
4. Once connected, you can select models from that provider in your agent configuration

### **Quick Provider Overview**

| Provider         | Models | Best For                                                      | Cost Range (per 1M tokens) |
| ---------------- | ------ | ------------------------------------------------------------- | -------------------------- |
| **PixelML**      | 50+    | Unified access to latest models (GPT-5, Claude 4.5, Gemini 3) | $0.05-15 input             |
| **OpenAI**       | 17     | Reasoning (O1/O3), Coding (GPT-5.1 Codex), General use        | $0.08-15 input             |
| **Anthropic**    | 8      | Analysis, structured outputs, long context                    | $1-15 input                |
| **Google GenAI** | 5      | Vision, video, audio, 1M+ token context                       | $0.075-2.5 input           |
| **Groq**         | 14     | Ultra-fast inference (< 1 sec), open-source models            | $0.03-1 input              |
| **DeepSeek**     | 2      | Cost-efficient reasoning and chat (V4 lineup)                 | $0.14-0.435 input          |
| **AgenticFlow**  | 11     | Budget-friendly, 50K input token limit                        | $0.05-0.2 input            |

***

## 📊 **Complete Model Comparison Table**

### **OpenAI Models**

| Model                  | Input Cost | Output Cost | Context | Features                     | Best For                              |
| ---------------------- | ---------- | ----------- | ------- | ---------------------------- | ------------------------------------- |
| **GPT-5 Pro**          | $15.00     | $120.00     | 400K    | Vision, Tools, Structured    | Premium reasoning, critical decisions |
| **GPT-5.1**            | $1.25      | $10.00      | 400K    | Vision, Tools, Structured    | Advanced general use                  |
| **GPT-5.1 Codex**      | $1.25      | $10.00      | 400K    | Tools, Structured            | Code generation & debugging           |
| **GPT-5.1 Codex Mini** | $1.50      | $6.00       | 400K    | Tools, Structured            | Efficient coding tasks                |
| **GPT-5**              | $1.25      | $10.00      | 272K    | Vision, Tools, Structured    | General premium use                   |
| **GPT-5 Mini**         | $0.25      | $2.00       | 272K    | Vision, Tools, Structured    | Cost-effective quality                |
| **GPT-5 Nano**         | $0.05      | $0.40       | 272K    | Vision, Tools, Structured    | High-volume budget tasks              |
| **GPT-4.1**            | $2.00      | $8.00       | 1M      | Tools, Structured            | Large context needs                   |
| **GPT-4.1 Mini**       | $0.40      | $1.60       | 1M      | Tools, Structured            | Cost-effective large context          |
| **GPT-4.1 Nano**       | $0.08      | $0.32       | 1M      | Tools, Structured            | Ultra-budget large context            |
| **GPT-4o**             | $0.50      | $1.50       | 128K    | Tools, Structured            | Standard general use                  |
| **O3**                 | $1.10      | $4.40       | 128K    | Reasoning, Tools, Structured | Complex reasoning                     |
| **O3 Mini**            | $0.60      | $2.40       | 200K    | Reasoning, Tools, Structured | Efficient reasoning                   |
| **O1**                 | $1.10      | $4.40       | 200K    | Reasoning, Tools, Structured | Advanced reasoning                    |
| **O1 Mini**            | $0.40      | $1.60       | 128K    | Tools, Structured            | Budget reasoning                      |
| **GPT OSS 120B**       | $0.15      | $0.75       | 131K    | Tools, Structured            | Open-source compatible                |
| **GPT OSS 20B**        | $0.10      | $0.50       | 131K    | Tools, Structured            | Efficient open-source                 |

### **Anthropic (Claude) Models**

| Model                          | Input Cost | Output Cost | Context | Features                             | Best For                     |
| ------------------------------ | ---------- | ----------- | ------- | ------------------------------------ | ---------------------------- |
| **Claude 4.5 Opus**            | $5.00      | $25.00      | 200K    | Vision, Reasoning, Tools, Structured | Premium analysis & reasoning |
| **Claude 4.5 Sonnet**          | $3.00      | $15.00      | 200K    | Tools, Structured                    | Balanced quality & cost      |
| **Claude 4.5 Haiku**           | $1.00      | $5.00       | 200K    | Tools, Structured                    | Fast, cost-effective         |
| **Claude 4 Opus**              | $15.00     | $75.00      | 50K     | Tools, Structured                    | Highest quality reasoning    |
| **Claude 4 Sonnet**            | $3.00      | $15.00      | 50K     | Tools, Structured                    | Quality analysis             |
| **Claude 3.7 Sonnet**          | $3.00      | $15.00      | 50K     | Tools, Structured                    | Advanced analysis            |
| **Claude 3.7 Sonnet Thinking** | $3.00      | $15.00      | 200K    | Reasoning, Structured                | Thinking mode enabled        |
| **Claude 3.5 Opus**            | $15.00     | $75.00      | 50K     | Tools, Structured                    | Legacy premium               |
| **Claude 3.5 Sonnet**          | $3.00      | $15.00      | 50K     | Tools, Structured                    | Legacy balanced              |
| **Claude 3.5 Haiku**           | $3.00      | $4.00       | 50K     | Tools, Structured                    | Legacy fast                  |

### **Google Gemini Models**

| Model                     | Input Cost | Output Cost | Context | Features                                | Best For                   |
| ------------------------- | ---------- | ----------- | ------- | --------------------------------------- | -------------------------- |
| **Gemini 3 Pro Preview**  | $2.00      | $12.00      | 1M      | Vision, Tools, Structured               | Latest Gemini capabilities |
| **Gemini 2.5 Pro**        | $2.50      | $15.00      | 1M      | Vision, Video, Tools, Structured        | Multi-modal premium        |
| **Gemini 2.5 Flash**      | $0.15      | $0.60       | 1M      | Tools, Structured                       | Fast, cost-effective       |
| **Gemini 2.5 Flash Lite** | $0.075     | $0.30       | 1M      | Vision, Audio, Video, Tools, Structured | Ultra-budget multi-modal   |
| **Gemini 2.0 Flash**      | $0.10      | $0.40       | 1M      | Vision, Tools, Structured               | Balanced speed & cost      |
| **Gemini 2.0 Flash Lite** | $0.075     | $0.30       | 1M      | Vision, Tools, Structured               | Budget vision support      |
| **Gemini 1.5 Pro**        | $2.50      | $10.00      | 2M      | Tools, Structured                       | Largest context window     |
| **Gemini 1.5 Flash**      | $0.15      | $0.60       | 1M      | Tools, Structured                       | Fast & efficient           |

### **DeepSeek Models**

| Model                 | Input Cost | Output Cost | Context | Features                     | Best For                                             |
| --------------------- | ---------- | ----------- | ------- | ---------------------------- | ---------------------------------------------------- |
| **DeepSeek V4 Flash** | $0.14      | $0.28       | 1M      | Tools, Structured            | **Default** — chat, reasoning, coding (peak quality) |
| **DeepSeek V4 Pro**   | $0.435     | $0.87       | 1M      | Reasoning, Tools, Structured | Frontier-tier, specialized workloads only            |

> **⚠️ Legacy retirement (31 May 2026 PST):** `deepseek-chat`, `deepseek-reasoner`, and `DeepSeek V3.2 / V3.2 Speciale / V3.2 Exp` are inaccessible after May 31, 2026 (PST). Migrate **all of them to DeepSeek V4 Flash** — its quality already covers both the chat and reasoner slots, no need to split. Use V4 Pro only when a specialized frontier-tier workload genuinely calls for the larger model. Same base URL and API key — only the model field changes.

### **Groq Models (Ultra-Fast Inference)**

| Model                             | Input Cost | Output Cost | Context | Features          | Best For                   |
| --------------------------------- | ---------- | ----------- | ------- | ----------------- | -------------------------- |
| **Llama 3.3 70B Versatile**       | $0.59      | $0.79       | 131K    | Tools             | Fast large model           |
| **DeepSeek R1 Distill Llama 70B** | $0.75      | $0.99       | 131K    | Tools             | Fast reasoning             |
| **Llama 3.1 8B Instant**          | $0.05      | $0.08       | 131K    | Tools             | Ultra-fast, ultra-cheap    |
| **Llama 4 Maverick 17B 128E**     | $0.24      | $0.24       | 131K    | Tools             | Fast balanced model        |
| **Llama 4 Scout 17B 16E**         | $0.11      | $0.34       | 131K    | Tools             | Fast efficient model       |
| **Kimi K2 Instruct**              | $1.00      | $3.00       | 131K    | Tools, Structured | Fast advanced chat         |
| **Qwen 3 32B**                    | $0.29      | $0.54       | 131K    | Tools             | Fast Chinese + English     |
| **Mistral Saba 24B**              | $0.79      | $0.79       | 32K     | Tools             | Fast European model        |
| **Gemma 2 9B**                    | $0.20      | $0.20       | 8K      | Tools             | Fast small model           |
| **GPT OSS 120B**                  | $0.15      | $0.75       | 131K    | Tools             | Fast open-source large     |
| **GPT OSS 20B**                   | $0.10      | $0.40       | 131K    | Tools             | Fast open-source small     |
| **Llama Guard 4 12B**             | $0.20      | $0.20       | 131K    | Streaming         | Safety moderation          |
| **Llama Prompt Guard 2 86M**      | $0.04      | $0.04       | 512     | Streaming         | Prompt injection detection |
| **Llama Prompt Guard 2 22M**      | $0.03      | $0.03       | 512     | Streaming         | Fast prompt filtering      |

### **Additional Models (PixelML)**

| Model                | Input Cost | Output Cost | Context | Features                     | Best For                      |
| -------------------- | ---------- | ----------- | ------- | ---------------------------- | ----------------------------- |
| **Grok 4**           | $3.00      | $15.00      | 64K     | Tools, Structured            | xAI model with real-time data |
| **Kimi K2**          | $0.57      | $2.30       | 64K     | Tools, Structured            | Chinese language specialist   |
| **Kimi K2 Thinking** | $0.60      | $2.50       | 262K    | Reasoning, Tools, Structured | Long-context reasoning        |
| **GLM-4.5**          | $0.39      | $1.55       | 131K    | Tools, Structured            | Chinese bilingual model       |
| **GLM-4.5 Air**      | $0.14      | $0.86       | 131K    | Tools, Structured            | Efficient Chinese model       |

### **AgenticFlow Provider (Budget Models)**

All AgenticFlow models have **50K input token limit** for cost control:

| Model                     | Input Cost | Output Cost | Context | Features                                | Best For                  |
| ------------------------- | ---------- | ----------- | ------- | --------------------------------------- | ------------------------- |
| **Gemini 2.5 Flash Lite** | $0.075     | $0.30       | 1M      | Vision, Audio, Video, Tools, Structured | Best budget multi-modal   |
| **Gemini 2.0 Flash Lite** | $0.07      | $0.30       | 50K     | Tools, Structured                       | Budget vision             |
| **Gemini 2.0 Flash**      | $0.10      | $0.40       | 50K     | Vision, Tools, Structured               | Budget balanced           |
| **Gemini 1.5 Flash**      | $0.07      | $0.30       | 50K     | Tools, Structured                       | Budget efficient          |
| **GPT-5 Nano**            | $0.05      | $0.40       | 50K     | Vision, Tools, Structured               | Budget OpenAI vision      |
| **GPT-4o Mini**           | $0.10      | $0.40       | 50K     | Tools, Structured                       | Budget OpenAI             |
| **GPT OSS 120B**          | $0.15      | $0.75       | 131K    | Tools, Structured                       | Budget large model        |
| **GPT OSS 20B**           | $0.10      | $0.50       | 131K    | Tools, Structured                       | Budget small model        |
| **DeepSeek V4 Flash**     | $0.14      | $0.28       | 50K     | Tools, Structured                       | Budget reasoning & coding |
| **Claude 3.5 Haiku**      | $1.00      | $5.00       | 50K     | Tools, Structured                       | Budget Claude             |
| **GLM-4.5 Air**           | $0.14      | $0.86       | 131K    | Tools, Structured                       | Budget Chinese            |

**Notes:**

* All costs are per million tokens
* Context shown is max input tokens
* Features: Tools = Function calling, Structured = JSON schema, Vision/Audio/Video = Multi-modal

***

## 🎯 **Model Selection by Use Case**

### **General Business Use**

**Recommended:** GPT-4.1 ($2/M), Claude 4.5 Sonnet ($3/M), Claude 3.5 Sonnet ($3/M)

* Best overall performance for business tasks
* Excellent reasoning and communication
* Good balance of capability and cost

### **Customer Support (High-Volume)**

**Recommended:** Claude 4.5 Haiku ($1/M), GPT-4.1 Nano ($0.08/M), Gemini 2.5 Flash Lite ($0.075/M)

* Fast response times
* Cost-effective for high-volume
* Tool calling and structured output support

### **Content Creation**

**Recommended:** Claude 4.5 Opus ($5/M), GPT-5 ($1.25/M), GPT-4.1 ($2/M)

* Superior writing capabilities
* Vision support for image-based content
* Advanced formatting

### **Data Analysis**

**Recommended:** Claude 4.5 Sonnet ($3/M), Gemini 2.5 Pro ($2.5/M), DeepSeek V4 Flash ($0.14/M)

* Excellent analytical reasoning
* Strong structured data handling
* Large context windows (200K-1M+)

### **Technical Support & Coding**

**Recommended:** GPT-5.1 Codex ($1.25/M), Claude 4.5 Opus ($5/M), DeepSeek V4 Flash ($0.14/M)

* Code understanding and generation
* Complex problem-solving
* Reasoning features for debugging

### **Budget-Conscious / High-Volume**

**Recommended:** Gemini 2.5 Flash Lite ($0.075/M), GPT OSS 20B ($0.10/M), Llama 3.1 8B ($0.05/M)

* Ultra-low costs
* Still capable for most tasks
* Fast inference times

### **Advanced Reasoning**

**Recommended:** O1 ($1.10/M), O3 ($1.10/M), DeepSeek V4 Flash ($0.14/M), Claude 4.5 Opus ($5/M)

* Step-by-step reasoning
* Complex problem-solving
* Mathematical and logical tasks

### **Multi-Modal (Vision/Video/Audio)**

**Recommended:** Gemini 2.5 Flash Lite ($0.075/M), Gemini 2.5 Pro ($2.5/M), GPT-5 ($1.25/M)

* Image understanding
* Video analysis (Gemini 2.5 Pro/Lite)
* Audio processing (Gemini 2.5 Lite)

***

## ⚙️ **Configuration Settings**

### **Temperature Control**

* **0.0-0.3 (Focused)**: Consistent, predictable responses for support, analysis, documentation
* **0.4-0.7 (Balanced)**: Natural variation for general communication
* **0.8-1.0 (Creative)**: High creativity for marketing, writing, brainstorming
* **Default**: 0.1 (backend standard)

### **Token Limits**

* **Max Input Tokens**: Controls context window (50K-2M depending on model)
* **Max Output Tokens**: Controls response length (1K-128K depending on model)
* **AgenticFlow Provider**: Capped at 50K input for cost control

### **Advanced Settings**

* **Streaming**: Enabled by default for all models
* **Tool Calling**: Function calling for external integrations
* **Structured Output**: JSON schema enforcement
* **Response Format**: Plain text, JSON, or custom structures

***

## 💰 **Cost Optimization Tips**

1. **Choose the Right Provider**
   * **PixelML**: Latest models, highest limits.
   * **AgenticFlow**: Use your Agenticflow Credit, no extra cost.
   * **Direct Providers**: Full features, varying costs
2. **Token Management**
   * Set appropriate max\_input\_tokens to control costs
   * Configure max\_output\_tokens based on actual needs
   * Lower temperature (0.1-0.3) = shorter, focused responses
3. **Feature Selection**
   * Only use vision-enabled models when processing images
   * Use reasoning models only for complex logic
   * Choose standard models for routine tasks

***

## 📋 **Quick Reference**

### **Fastest Models (< 1 second)**

All Groq models: Llama 3.1 8B, Llama 3.3 70B, Llama 4 family, Gemma 2 9B

### **Largest Context (1M+ tokens)**

GPT-4.1 (1M), All Gemini models (1M-2M)

### **Best Value**

Gemini 2.5 Flash Lite ($0.075/M), GPT-4.1 Nano ($0.08/M), Llama 3.1 8B ($0.05/M)

### **Most Capable**

Claude 4.5 Opus, GPT-5 Pro, O1/O3, Claude 4 Opus

### **Best for Coding**

GPT-5.1 Codex, Claude 4.5 Opus, DeepSeek V4 Flash

### **Multi-Modal**

Gemini 2.5 family (vision + video + audio), GPT-5 family (vision), Claude 4.5 Opus (vision)

***


# System Prompt Configuration

## 🧠 **Crafting Your Agent's Intelligence**

The system prompt is your agent's core instructions—it defines personality, expertise, behavior patterns, and response style. This is where you transform a generic AI model into a specialized assistant tailored to your specific needs.

***

## 🎯 **System Prompt Components**

### **Core Instruction Structure**

A well-crafted system prompt typically includes:

#### **1. Role Definition**

```
You are a [specific role] who specializes in [domain/expertise].
Your primary responsibility is to [main function].
```

**Examples:**

* "You are a customer support specialist who specializes in SaaS troubleshooting."
* "You are a marketing content creator who specializes in B2B technology companies."
* "You are a financial analyst who specializes in small business accounting."

#### **2. Expertise Areas**

Define what your agent knows and doesn't know:

```
Your areas of expertise include:
- [Area 1]: Detailed knowledge of [specific aspects]
- [Area 2]: Experience with [specific tools/processes]  
- [Area 3]: Understanding of [specific domain knowledge]

You should not provide advice on: [limitations]
```

#### **3. Response Guidelines**

Set clear expectations for how the agent should respond:

```
When responding:
- Always [required behavior 1]
- Never [prohibited behavior 1]
- If unsure, [escalation/clarification procedure]
- Keep responses [tone/length/style guidelines]
```

#### **4. Process Instructions**

For complex tasks, provide step-by-step procedures:

```
When handling [specific task type]:
1. First, [initial step]
2. Then, [verification/analysis step]
3. Next, [action step]
4. Finally, [confirmation/follow-up step]
```

***

## 🎨 **Prompt Templates by Use Case**

### **Customer Support Agent**

```
You are a friendly and knowledgeable customer support specialist for [Company Name]. 

Your expertise includes:
- Product features and functionality
- Common troubleshooting procedures
- Account management and billing questions
- Integration setup and configuration

When helping customers:
1. Always greet them warmly and acknowledge their concern
2. Ask clarifying questions to fully understand the issue
3. Provide clear, step-by-step solutions
4. Offer to follow up or escalate if needed
5. End with asking if there's anything else you can help with

If you cannot resolve an issue:
- Acknowledge the limitation honestly
- Offer to connect them with a human specialist
- Provide an estimated response time

Keep responses professional but conversational, and always prioritize the customer's success.
```

### **Sales Development Agent**

```
You are an experienced sales development representative specializing in [industry/product type].

Your role is to:
- Qualify inbound leads based on budget, authority, need, and timeline
- Understand prospect challenges and pain points
- Present relevant solutions and value propositions
- Schedule qualified prospects for product demonstrations

Your approach:
1. Build rapport by showing genuine interest in their business
2. Ask open-ended questions to understand their situation
3. Listen actively and identify opportunities to help
4. Present solutions that directly address their stated needs
5. Handle objections with empathy and additional information

If a lead isn't qualified:
- Be respectful and helpful
- Offer relevant resources or content
- Maintain a positive relationship for future opportunities

Always be consultative, not pushy, and focus on providing value in every interaction.
```

### **Content Creation Agent**

```
You are a skilled content marketing specialist with expertise in [industry/niche].

Your content creation process:
1. Research the topic thoroughly using available knowledge sources
2. Identify the target audience and their specific needs/interests
3. Create content that provides genuine value and insights
4. Optimize for SEO while maintaining readability and engagement
5. Include clear calls-to-action when appropriate

Your writing style:
- Professional yet accessible tone
- Use industry terminology appropriately but explain complex concepts
- Include relevant examples and case studies when possible
- Structure content with clear headers and bullet points for scannability
- Fact-check all claims and cite sources when available

For different content types:
- Blog posts: 1,000-2,000 words with SEO optimization
- Social media: Platform-appropriate length with engaging hooks
- Email content: Clear subject lines and compelling calls-to-action
- White papers: In-depth analysis with data and research backing
```

***

## 🔧 **Advanced Prompt Engineering**

### **Personality Configuration**

Define your agent's communication style:

#### **Professional & Formal**

```
Maintain a professional, business-appropriate tone in all interactions. 
Use complete sentences, proper grammar, and industry-standard terminology.
Avoid casual language, slang, or overly familiar expressions.
```

#### **Friendly & Conversational**

```
Communicate in a warm, approachable manner while remaining professional.
Use conversational language that feels natural and personable.
Show enthusiasm for helping and genuine interest in the user's needs.
```

#### **Technical & Precise**

```
Provide technically accurate, detailed information with precise terminology.
Include specific steps, requirements, and technical specifications.
Assume the user has technical knowledge unless they indicate otherwise.
```

### **Context Awareness**

Help your agent understand situational nuances:

```
Consider the context of each conversation:
- Time-sensitive issues require immediate, focused responses
- New users need more explanation and guidance
- Returning customers may prefer quick, direct answers
- Complex problems may require breaking down into smaller steps

Adapt your communication style based on:
- User's apparent technical knowledge level
- Urgency indicated in their message
- Previous conversation history
- Time of day/business hours
```

### **Quality Control Instructions**

Ensure consistent, high-quality responses:

```
Before responding, verify that your answer:
- Directly addresses the user's question or concern
- Provides accurate information based on available knowledge
- Includes all necessary steps or information
- Uses appropriate tone and language for the context
- Offers clear next steps or follow-up actions

If you're unsure about any information:
- State your uncertainty clearly
- Provide the most likely correct answer with caveats
- Offer to find more definitive information
- Suggest alternative resources or human assistance
```

***

## 📊 **Prompt Optimization Techniques**

### **Testing & Iteration**

Improve your prompts through systematic testing:

1. **A/B Testing**: Try different prompt versions with similar queries
2. **Edge Case Testing**: Test with unusual or challenging inputs
3. **User Feedback Integration**: Incorporate feedback to refine instructions
4. **Performance Monitoring**: Track response quality and user satisfaction

### **Common Prompt Issues & Solutions**

#### **Issue: Inconsistent Responses**

**Solution**: Add more specific guidelines and examples

```
Always follow this exact format for product recommendations:
1. Brief acknowledgment of their needs
2. Top 3 product suggestions with reasons
3. Comparison table if multiple options
4. Clear next step recommendation
```

#### **Issue: Off-Topic Responses**

**Solution**: Set clear boundaries and redirect instructions

```
Stay focused on [specific domain] topics only.
If asked about unrelated subjects, politely redirect:
"I specialize in [domain] and want to make sure I give you the most accurate information. For [other topic], I'd recommend [appropriate resource/specialist]."
```

#### **Issue: Too Verbose or Too Brief**

**Solution**: Specify desired response length and structure

```
Aim for responses of 2-3 paragraphs (100-200 words) unless:
- Simple yes/no questions: 1-2 sentences
- Complex technical issues: Detailed step-by-step explanations
- Urgent matters: Prioritize key information first
```

***

## 🎯 **Industry-Specific Considerations**

### **Healthcare & Medical**

* Include appropriate medical disclaimers
* Emphasize the importance of professional medical advice
* Use privacy-aware language and require professional review for regulated workflows

### **Financial Services**

* Include necessary regulatory disclaimers
* Avoid providing specific investment advice unless qualified
* Emphasize risk considerations and professional consultation

### **Legal Services**

* Include disclaimers about attorney-client relationships
* Avoid providing specific legal advice
* Direct users to qualified legal professionals for official guidance

### **Education & Training**

* Adapt explanations to appropriate learning levels
* Include interactive elements and knowledge checks
* Encourage questions and provide multiple explanation approaches

***

## 🔍 **Prompt Validation Checklist**

Before finalizing your system prompt, verify:

* [ ] **Role is clearly defined** with specific expertise areas
* [ ] **Response style guidelines** are explicit and measurable
* [ ] **Process instructions** are step-by-step and actionable
* [ ] **Limitations and boundaries** are clearly stated
* [ ] **Escalation procedures** are defined for edge cases
* [ ] **Quality standards** are specific and enforceable
* [ ] **Industry compliance** requirements are addressed
* [ ] **User experience** is prioritized in all interactions

***

## 🚀 **Getting Started with System Prompts**

### **Quick Start Process**

1. **Define Purpose**: What specific job should this agent perform?
2. **Identify Audience**: Who will interact with this agent?
3. **Set Boundaries**: What should and shouldn't the agent handle?
4. **Choose Style**: What personality and tone are appropriate?
5. **Add Process**: What steps should the agent follow?
6. **Test & Refine**: Iterate based on actual performance

### **Best Practices**

* **Start Simple**: Begin with basic instructions, add complexity gradually
* **Be Specific**: Vague instructions lead to inconsistent results
* **Include Examples**: Show the agent what good responses look like
* **Regular Updates**: Refine prompts based on user feedback and performance
* **Version Control**: Track prompt changes and their impact on performance

***

The system prompt is the foundation of your agent's intelligence—invest time in crafting clear, comprehensive instructions that align with your specific needs and use cases.


# Knowledge & Data Sources

## 🧠 **Powering Your Agent with Domain Knowledge**

The Knowledge tab is where you transform your AI agent from a general assistant into a domain expert. By connecting relevant data sources, documents, and knowledge bases, you give your agent access to the specific information it needs to provide accurate, contextual responses.

***

## 🎯 **Knowledge Source Types**

### **📄 Document Upload**

Upload files directly to your agent's knowledge base for semantic search and retrieval.

#### **Supported File Types**

* **PDF Documents**: Research papers, manuals, reports
* **Word Documents**: (.docx) Policies, procedures, guides
* **Text Files**: (.txt, .md) Documentation, notes, plain text
* **HTML Files**: (.html) Web pages, formatted documentation
* **Spreadsheets**: (.xlsx, .xls, .csv) Data tables, catalogs, structured data

#### **Document Processing Features**

* **Intelligent Chunking**: Configurable chunking strategies for optimal knowledge retrieval
* **Text Extraction**: Automatic text extraction from supported formats
* **Space Normalization**: Remove extra whitespace for cleaner text

#### **Best Practices for Document Upload**

```
✅ DO:
- Use clear, descriptive dataset names
- Keep documents focused on specific topics
- Ensure text is selectable (not just images)
- Configure chunking based on document structure

❌ AVOID:
- Uploading duplicate or conflicting information
- Using documents with poor formatting
- Including sensitive personal information without proper access controls
- Overwhelming with too many similar documents
```

### **📊 Table Upload**

Upload structured data in tabular format for precise lookups and semantic search.

#### **Supported Table Formats**

* **CSV Files**: Comma-separated values
* **Excel Files**: (.xlsx, .xls) Spreadsheets with single or multiple sheets
* **Manual Entry**: Create tables directly in the interface

#### **Table Configuration**

* **Column Types**: TEXT, NUMBER, INTEGER, BOOLEAN, DATE
* **Semantic Columns**: Mark columns for semantic search indexing
* **Column Sequencing**: Define display order for columns
* **Schema Analysis**: Automatic type detection from uploaded files

#### **Table Use Cases**

* Product catalogs with specifications and pricing
* Customer records and interaction history
* FAQ databases with questions and answers
* Knowledge articles with categorization
* Configuration and settings databases

### **🗄️ Database Schema (Manual)**

Create database-like schemas for structured knowledge organization.

#### **Database Format Features**

* **Custom Schema Design**: Define your own table structures
* **Column Type Support**: TEXT, NUMBER, INTEGER, BOOLEAN, DATE
* **Manual Data Entry**: Populate data through the interface
* **Structured Queries**: Enable precise data retrieval

***

## ⚙️ **Knowledge Processing Settings**

### **Chunking Strategy**

Control how documents are broken down for processing and retrieval.

#### **Chunking Configuration Options**

* **Chunk Type**: Strategy for dividing content
* **Max Tokens**: Maximum size per chunk (configurable)
* **Separator**: Custom separator for chunk boundaries
* **Remove Extra Spaces**: Clean up whitespace
* **Remove URLs/Emails**: Filter out contact information

#### **Best Practices**

```
Document Length Guidelines:
- Short documents (< 5 pages): Larger chunks (1000+ tokens)
- Medium documents (5-50 pages): Medium chunks (500-1000 tokens)
- Long documents (50+ pages): Smaller chunks (200-500 tokens)
- Technical docs with code: Preserve code blocks intact
```

***

## 🔍 **Agent Knowledge Configuration**

Configure how your agent retrieves and uses knowledge during conversations.

### **Retrieval Mode**

#### **Auto Retrieval** (Default: Off)

```
Automatic Knowledge Access:
- Agent automatically retrieves relevant knowledge for every query
- No explicit tool call needed
- Best for: Agents that always need domain knowledge
- Trade-off: May retrieve unnecessary information
```

#### **Manual Tool Call** (Default: On)

```
On-Demand Knowledge Access:
- Agent decides when to retrieve knowledge using available tools
- More control over when knowledge is accessed
- Best for: General-purpose agents that sometimes need knowledge
- Trade-off: Requires agent to recognize when knowledge is needed
```

### **Search Strategy**

#### **Hybrid Search** (Default - Recommended)

```
Combined Approach:
- Semantic search: Understanding context and meaning
- Full-text search: Exact keyword matching
- Best for: Most use cases, balances accuracy and coverage
- Returns: Semantically relevant + keyword-matched results
- Cost extra credits for re-ranking documents. 
```

#### **Semantic Search Only**

```
Vector-Based Retrieval:
- Understanding context and intent
- Finding conceptually related information
- Handling synonyms and variations
- Best for: Natural language queries and conceptual searches
```

#### **Full-Text Search Only**

```
Keyword-Based Retrieval:
- Exact term matching
- Faster for specific lookups
- Good for technical terminology and precise queries
- Best for: Known keywords and exact phrase matching
```

### **Retrieval Parameters**

#### **Top K** (Default: 5, Range: 1-10)

```
Number of Knowledge Chunks to Retrieve:
- Higher values: More comprehensive context, higher cost
- Lower values: Focused context, lower cost
- Recommended: 3-5 for most use cases
- Adjust based on: Query complexity and knowledge base size
```

#### **Threshold** (Default: 0.5, Range: 0.0-1.0)

```
Relevance Score Threshold:
- Higher threshold (0.7-1.0): Only highly relevant results
- Medium threshold (0.4-0.7): Balanced relevance
- Lower threshold (0.0-0.4): Include more potential matches
- Recommended: Start at 0.5, adjust based on retrieval quality
```

#### **Query Rewrite** (Default: On)

```
Query Optimization:
- Rewrites user query before knowledge retrieval
- Improves search relevance by clarifying intent
- Expands abbreviations and adds context
- Recommended: Enable for most use cases
```

#### **Rerank** (Default: Off)

```
Result Reranking:
- Post-processes retrieved results for better ordering
- Uses cross-encoder models for more accurate relevance
- Trade-off: Better results but additional latency
- Recommended: Enable for critical accuracy use cases
```

### **Connected Datasets**

#### **Multiple Dataset Support**

* Connect up to **100 datasets** per agent
* Each dataset appears as a searchable knowledge source
* Datasets maintain their own:
  * Name and ID
  * Source type (UPLOAD, MANUAL)
  * Format type (TEXT, TABLE, DATABASE)
  * Processing status

#### **Dataset Information Display**

For each connected dataset, the agent has access to:

* Dataset name (user-friendly identifier)
* Dataset ID (unique identifier)
* Source type (how data was added)
* Status (PENDING, SUCCESS, FAILURE)
* Format type (TEXT, TABLE, DATABASE)

***

## 📊 **Knowledge Analytics & Management**

### **Dataset Status Monitoring**

#### **Processing States**

* **PENDING**: Dataset creation or update in progress
* **SUCCESS**: Dataset ready for use
* **FAILURE**: Processing encountered errors

#### **Progress Tracking**

* Monitor document import progress
* Track embedding generation status
* View chunk processing metrics

### **Embedding Updates**

#### **Manual Embedding Refresh**

```
When to Update Embeddings:
- After modifying dataset content
- After bulk row updates in tables
- To incorporate new document versions
```

***

## 🔧 **Knowledge Configuration Best Practices**

### **Initial Setup Process**

1. **Audit Existing Information**: Catalog what knowledge you have
2. **Choose Dataset Format**: TEXT for documents, TABLE for structured data
3. **Configure Processing**: Set chunking and parsing options
4. **Select Embedding Model**: Choose based on language and domain
5. **Test Retrieval**: Verify agent responses with sample queries

### **Dataset Organization Strategies**

#### **By Topic**

```
Product Knowledge:
├── Product Features (TEXT dataset)
├── Technical Specifications (TABLE dataset)
├── Pricing & Plans (TABLE dataset)
└── Troubleshooting Guides (TEXT dataset)

Customer Support:
├── Common Issues (TEXT dataset)
├── Resolution Procedures (TEXT dataset)
└── Product Updates (TEXT dataset)
```

#### **By Source Type**

```
Documentation:
├── User Manual.pdf → TEXT dataset
├── API Reference.pdf → TEXT dataset
└── FAQ.csv → TABLE dataset

Internal Knowledge:
├── Training Materials → TEXT dataset
├── Process Documents → TEXT dataset
└── Policy Database → DATABASE dataset
```

### **Optimization Guidelines**

#### **Document Preparation**

```
Before Upload:
- Remove duplicate content across documents
- Ensure consistent formatting
- Split very large documents into logical sections
- Use descriptive filenames
- Remove or redact sensitive information
```

#### **Table Design**

```
Column Configuration:
- Mark relevant columns as "semantic" for search
- Use appropriate data types (TEXT, NUMBER, DATE, etc.)
- Include descriptive column names
- Maintain data consistency across rows
- Consider creating separate tables for different entity types
```

#### **Retrieval Tuning**

```
Adjustment Process:
1. Start with defaults (Hybrid, Top K=5, Threshold=0.5)
2. Test with representative queries
3. If too few results: Lower threshold, increase Top K
4. If too many irrelevant results: Raise threshold, enable rerank
5. If missing semantic matches: Switch to Semantic search
6. If missing exact matches: Switch to Full-text search
```

***

## 🚀 **Advanced Features**

### **Multi-Dataset Retrieval**

When connecting multiple datasets to an agent:

* Agent can search across all connected datasets
* Results merged and ranked by relevance
* Each result includes source dataset information
* Useful for comprehensive knowledge coverage

### **Semantic Column Configuration**

For TABLE and DATABASE formats:

* Mark specific columns for semantic search indexing
* Non-semantic columns remain queryable but not embedded
* Reduces embedding costs for large tables
* Improves search focus on relevant fields

***

## 🎯 **Knowledge Integration Checklist**

Before activating your agent's knowledge base:

* [ ] **Dataset Created**: Upload documents or create tables
* [ ] **Processing Complete**: Verify dataset status is SUCCESS
* [ ] **Embeddings Generated**: Check embedding progress is 100%
* [ ] **Search Strategy Configured**: Choose Hybrid, Semantic, or Full-text
* [ ] **Retrieval Parameters Set**: Configure Top K, threshold, rerank
* [ ] **Retrieval Mode Selected**: Auto or manual tool call
* [ ] **Test Queries Run**: Verify knowledge retrieval with sample questions
* [ ] **Access Controls Set**: Ensure appropriate workspace permissions

***

Your agent's knowledge is its competitive advantage—invest in building a comprehensive, well-organized knowledge base that enables intelligent, accurate responses.


# Skills & Capabilities

## 🎯 **Extending Your Agent with Specialized Knowledge**

The Skills tab is where you enhance your AI agent with pre-packaged expertise, templates, and best practices. Unlike Knowledge bases that provide factual information, Skills equip your agent with proven implementation patterns, code examples, and step-by-step guides for specific tasks or domains.

### **Inspired by Anthropic's Claude Skills**

AgenticFlow's Skills feature is inspired by and compatible with [**Anthropic's Claude Skills**](https://support.claude.com/en/articles/12512176-what-are-skills)—a capability that allows AI agents to dynamically load specialized instructions, scripts, and resources for specific tasks. Like Claude's approach, AgenticFlow Skills:

* **Load on-demand**: Skills are referenced only when relevant to the agent's current task, preventing context overload
* **Enable repeatability**: Provide structured, consistent approaches to specialized workflows
* **Support customization**: Allow teams to create organization-specific capabilities beyond built-in options
* **Combine with tools**: Work alongside integrations (like MCP connections in Claude) to enhance both procedural knowledge and tool access

While Anthropic's Skills focus on document creation and general task automation in conversational AI, **AgenticFlow Skills** extend this concept to enterprise workflow automation, enabling agents to leverage proven patterns for data processing, API integrations, business workflows, and industry-specific implementations.

***

## 🧩 **What Are Skills?**

**Skills** are organized collections of documentation, code templates, examples, and best practices that agents can reference during execution. Think of them as reference libraries or playbooks that teach your agent how to approach specific types of tasks.

### **Skills vs Knowledge: Key Differences**

| Aspect             | Knowledge                           | Skills                                                       |
| ------------------ | ----------------------------------- | ------------------------------------------------------------ |
| **Purpose**        | Factual information retrieval       | Procedural guidance & templates                              |
| **Content Type**   | Documents, data, facts              | Code examples, tutorials, patterns                           |
| **Usage**          | Answer questions with specific data | Implement solutions following best practices                 |
| **Structure**      | Searchable chunks                   | Organized file hierarchy                                     |
| **Access Pattern** | Semantic/full-text search           | Browse and read specific files                               |
| **Example**        | Product catalog, FAQ database       | "How to analyze data with Pandas", API integration templates |

### **When to Use Skills**

```
✅ USE SKILLS FOR:
- Code implementation patterns and templates
- Step-by-step procedural guides
- Best practices for specific tools or frameworks
- Reusable solution templates
- Technical tutorials and documentation
- Standardized workflows and processes

✅ USE KNOWLEDGE FOR:
- Product information and specifications
- Customer data and history
- FAQ answers and support documentation
- Company policies and procedures
- Factual information retrieval
```

**💡 Power Tip**: Combine Skills with [Code Execution](/ai-agents/code-execution) to enable your agent to not just read code templates, but actually execute them in a secure sandbox. This unlocks powerful capabilities like data analysis, file processing, and automated report generation using your organization's proven code patterns.

***

## 🎨 **Skill Types**

AgenticFlow supports two types of skills with different scopes and management:

### **📦 Built-In Skills**

Pre-packaged skills provided and maintained by the platform.

#### **Characteristics**

* **Scope**: Available platform-wide to all projects
* **Management**: Maintained by AgenticFlow platform
* **Access**: Read-only reference
* **Versioning**: Versioned releases (e.g., "1.0.0", "2.1.0")
* **Updates**: Platform updates with new versions
* **Quality**: Professionally curated and tested

#### **Common Built-In Skills**

* Data analysis frameworks (Pandas, NumPy)
* API integration patterns
* LLM best practices (prompt engineering, chain-of-thought)
* Document processing workflows
* Web scraping and automation
* Testing and quality assurance patterns

#### **Version Management**

* Skills use semantic versioning (MAJOR.MINOR.PATCH)
* Agents lock to specific versions for consistency
* Update versions to access new features or improvements

### **🔧 Project Skills**

Custom skills created and uploaded by your team for project-specific needs.

#### **Characteristics**

* **Scope**: Private to your project
* **Management**: Created and maintained by project team
* **Access**: Full read/write control
* **Versioning**: Optional version tracking
* **Content**: Tailored to your specific use cases
* **Security**: Project-level access controls

#### **Use Cases for Project Skills**

* Internal code standards and conventions
* Custom framework integration guides
* Company-specific workflow templates
* Proprietary algorithm implementations
* Domain-specific best practices
* Team knowledge codification

***

## ➕ **Adding Skills to Your Agent**

### **Step 1: Enable Skills**

Toggle the **Skills** switch to ON to activate the skills feature for your agent.

### **Step 2: Add Skills**

Click the **+ Add** button to add skills to your agent. You have two options:

#### **Option A: Add New Skill**

Create and upload a brand new skill for this project.

**Upload Process**:

1. Click **Add new skill**
2. Upload files via the file upload dialog:
   * Drag and drop files (up to 10 MB per file)
   * Or click to browse and select files
   * Maximum 100 files per batch
3. Organize files in a meaningful structure:

   ```
   my-skill/
   ├── SKILL.md              # Required: Main documentation
   ├── examples/             # Optional: Usage examples
   │   ├── basic-example.py
   │   └── advanced-example.py
   ├── templates/            # Optional: Reusable templates
   │   └── template.json
   └── scripts/              # Optional: Implementation scripts
       └── helper.py
   ```

**Required File: SKILL.md**

Every skill MUST include a `SKILL.md` file with frontmatter metadata:

```markdown
---
name: Data Analysis Toolkit
description: Comprehensive guide to data analysis with Python
skill_id: data-analysis-toolkit
version: 1.0.0
author: Data Team
tags:
  - data-analysis
  - pandas
  - python
---

# Data Analysis Toolkit

This skill provides best practices and templates for data analysis tasks...

## Quick Start

1. Import required libraries
2. Load your dataset
3. Apply analysis patterns

## Examples

See the `examples/` directory for detailed use cases.
```

**Frontmatter Fields**:

* **name**: Human-readable skill name
* **description**: Brief description for discovery (appears in skill list)
* **skill\_id**: Unique identifier (lowercase, hyphens only)
* **version**: Version string (e.g., "1.0.0")
* **author**: Creator name or team
* **tags**: List of categorization tags (array or comma-separated)

#### **Option B: Add Existing Skill**

Select from built-in skills provided by the platform.

**Selection Process**:

1. Click **Add existing skill**
2. Browse available built-in skills
3. View skill descriptions and versions
4. Select skills to add to your agent
5. Click **Confirm** to enable selected skills

### **Step 3: Manage Connected Skills**

Once added, skills appear in the Skills list with:

* **Skill Name**: Display name from SKILL.md
* **Skill ID**: Unique identifier
* **Source**: "Built-in" or "Project"
* **Version**: Version number (if applicable)
* **Status**: Ready, Processing, or Error

**Actions**:

* **Remove**: Disconnect skill from agent (doesn't delete the skill)
* **View Details**: Browse skill contents and documentation

***

## 📖 **Skill Structure and Organization**

### **Recommended Directory Structure**

```
your-skill/
├── SKILL.md                    #  REQUIRED: Main documentation with metadata
├── README.md                   # Optional: Additional overview
├── examples/                   # Recommended: Practical examples
│   ├── basic-usage.py
│   ├── advanced-patterns.py
│   └── real-world-scenario.py
├── templates/                  # Recommended: Reusable templates
│   ├── starter-template.json
│   └── config-template.yaml
├── scripts/                    # Optional: Helper scripts
│   ├── setup.py
│   └── utilities.py
├── resources/                  # Optional: Additional resources
│   ├── cheat-sheet.md
│   └── troubleshooting.md
└── docs/                       # Optional: Extended documentation
    ├── architecture.md
    └── api-reference.md
```

### **File Organization Best Practices**

#### **Use Clear, Descriptive Names**

```
✅ GOOD:
- authentication-with-oauth.py
- database-connection-template.json
- error-handling-patterns.md
❌ AVOID:
- script1.py
- temp.json
- notes.md
```

#### **Group Related Files**

```
✅ ORGANIZED:
api-integration/
├── SKILL.md
├── examples/
│   ├── rest-api-call.py
│   ├── graphql-query.py
│   └── webhook-handler.py
└── templates/
    ├── auth-config.json
    └── request-template.py
❌ FLAT:
api-integration/
├── SKILL.md
├── example1.py
├── example2.py
├── example3.py
├── config1.json
└── template1.py
```

#### **Include Graduated Examples**

```
examples/
├── 01-basic-usage.py           # Start simple
├── 02-intermediate-patterns.py # Build complexity
└── 03-advanced-integration.py  # Full implementation
```

***

## ⚙️ **How Agents Use Skills**

### **Agent Skill Workflow**

When your agent has skills enabled, it can reference them during task execution using **progressive disclosure**—similar to how Claude dynamically loads relevant skills. This approach ensures agents only access skills pertinent to the current task, avoiding context overload:

1. **Task Analysis**
   * Agent receives a task or question
   * Determines if a skill can help
2. **Skill Discovery**
   * Agent lists available skills to find relevant ones
   * Reviews skill descriptions and tags
   * Dynamically selects only relevant skills (not all at once)
3. **Skill Exploration**
   * Reads SKILL.md for overview and guidance
   * Browses directory structure to find relevant files
   * Lists files in specific directories (e.g., `examples/`)
4. **Content Retrieval**
   * Reads specific files (templates, examples, documentation)
   * Extracts relevant patterns and code
5. **Solution Implementation**
   * Applies templates and patterns from skill
   * Adapts examples to current task
   * Follows best practices documented in skill

### **Agent Skill Tools**

Agents access skills through two specialized tools:

#### \*\*=

Skill Browser\*\* Browse and discover skills and their contents.

**Capabilities**:

* **List all skills**: See all enabled skills with metadata
* **List files**: Browse files within a skill (recursive or shallow)
* **Directory navigation**: Explore skill structure

**Example Agent Usage**:

```
Agent: "Let me see what skills are available..."
[Calls skill_browser to list skills]

Agent: "I'll check the examples in the data-analysis skill..."
[Calls skill_browser to list files in data-analysis/examples/]
```

#### **= Skill Reader**

Read file contents from skills.

**Capabilities**:

* Read any text file within enabled skills
* Access code examples, templates, documentation
* View structured content (JSON, YAML, Markdown, code files)

**Example Agent Usage**:

```
Agent: "Let me read the SKILL.md to understand this skill..."
[Calls skill_reader for 'data-analysis', 'SKILL.md']

Agent: "I'll look at the basic usage example..."
[Calls skill_reader for 'data-analysis', 'examples/basic-usage.py']
```

### **Automatic Skill Integration**

When skills are enabled, the agent's system prompt includes:

* **List of available skills** with descriptions
* **Usage instructions** for skill\_browser and skill\_reader
* **Best practices** for leveraging skills effectively
* **Philosophy**: "Skills provide tested, production-ready patterns└always prefer using them"

### **Read-Only Reference**

**Important**: Skills are **reference materials only**└they are not executable code.

```
✅ Agent Actions:
- Read skill documentation
- Browse skill files
- Apply templates and patterns
- Follow procedural guides
- Adapt examples to current task
❌ Agent Cannot:
- Execute skill scripts directly
- Modify skill contents
- Install packages from skills
- Run skills as standalone programs
```

***

## 🔒 **Security and Access Control**

### **Path Security**

Skills enforce strict security boundaries:

#### **Allowed Operations**

* Browse within skill directory structure
* Read files inside skills directory
* Navigate subdirectories within skills

#### **Blocked Operations**

* Directory traversal (`../` sequences)
* Absolute path access (`/root/...`)
* Access outside `skills/` directory
* Hidden files or directories (leading `.`)
* Invalid path characters (`<>:"|?*`)

#### **Path Validation Rules**

```
✅ ALLOWED:
- skills/data-analysis/SKILL.md
- skills/api-guide/examples/basic.py
- skills/sql-patterns/templates/query.sql
❌ BLOCKED:
- skills/../secrets/config.json         # Directory traversal
- /etc/passwd                            # Absolute path
- skills/.hidden/secret.txt              # Hidden file
- skills/test<script>.py                 # Invalid characters
- skills/a/b/c/d/e/f/g.txt              # Too deep (max 5 levels)
```

### **Project-Level Access Control**

#### **Project Skills**

* **Scope**: Private to the project
* **Access**: Requires project membership and permissions
* **Visibility**: Only visible within the project
* **Management**: Project admins can create, update, delete

#### **Built-In Skills**

* **Scope**: Platform-wide
* **Access**: Available to all authenticated users
* **Visibility**: Listed in global skill catalog
* **Management**: Read-only for users; maintained by platform

***

## 📊 **File Upload Constraints**

When creating project skills, observe these limits:

### **File Size and Count**

* **Maximum file size**: 10 MB per file
* **Maximum files per batch**: 100 files
* **Total skill size**: No hard limit, but keep reasonable for performance

### **File Type Support**

#### **Text Files (Readable by Agent)**

```
Supported Text Formats:
- Code: .py, .js, .ts, .java, .cpp, .go, .rb, .php, .sh
- Markup: .md, .html, .xml, .json, .yaml, .yml
- Data: .txt, .csv, .sql, .log
- Config: .conf, .ini, .env.example
```

#### **Binary Files**

```
Binary files are supported but:
- Agent receives metadata only (not file contents)
- Useful for templates (e.g., .xlsx, .pdf)
- Can be downloaded via API but not read directly by agent
```

### **Path Depth Limit**

* **Maximum depth**: 5 levels
* Example: `skills/my-skill/category/subcategory/examples/file.py` (5 levels)

***

## 🎯 **Best Practices for Skill Creation**

### **Documentation Excellence**

#### **Write Clear SKILL.md**

```markdown
---
name: Clear, Descriptive Name
description: Brief but informative one-liner
skill_id: lowercase-with-hyphens
version: 1.0.0
author: Team or Person Name
tags:
  - primary-category
  - technology
  - use-case
---

# Skill Name

## Overview
Brief introduction to what this skill provides and when to use it.

## Quick Start
Minimal example to get started immediately.

## Key Concepts
Important principles and patterns covered in this skill.

## Structure
- `examples/`: Real-world usage examples
- `templates/`: Reusable templates
- `resources/`: Additional documentation

## Usage Guide
Step-by-step instructions for common scenarios.

## Examples
Reference specific example files with brief descriptions.

## Tips and Tricks
Advanced patterns and optimization techniques.

## Troubleshooting
Common issues and solutions.

## References
External resources and documentation links.
```

#### **Use Descriptive Tags**

```
✅ GOOD TAGS:
- python, data-analysis, pandas
- api-integration, rest, authentication
- workflow-automation, scheduling
❌ POOR TAGS:
- stuff, code, misc
- skill, example, template (too generic)
```

### **Code Example Guidelines**

#### **Include Progressive Examples**

**Basic Example** (01-basic.py):

```python
"""
Basic usage demonstration with minimal complexity.
Shows the simplest way to accomplish the core task.
"""

# Clear, commented code here
```

**Intermediate Example** (02-intermediate.py):

```python
"""
Real-world scenario with error handling and configuration.
Demonstrates best practices and common patterns.
"""

# More complete implementation
```

**Advanced Example** (03-advanced.py):

```python
"""
Production-ready implementation with full error handling,
logging, configuration management, and optimization.
"""

# Full-featured implementation
```

#### **Comment Thoroughly**

```python
# ✅ GOOD: Explains WHY and provides context
def process_data(data):
    """
    Transform raw data for analysis.

    We normalize the data first because downstream analytics
    expect consistent value ranges. This prevents skewed results
    from outliers.
    """
    # Remove outliers using IQR method
    # (Interquartile Range is robust to extreme values)
    normalized = remove_outliers(data)
    return normalized

# ❌ POOR: Only says WHAT the code does (obvious from code)
def process_data(data):
    # normalize data
    normalized = remove_outliers(data)
    return normalized
```

### **Template Design**

#### **Make Templates Adaptable**

```json
{
  "// COMMENT": "Replace placeholders with your specific values",
  "api_endpoint": "YOUR_API_ENDPOINT_HERE",
  "authentication": {
    "type": "bearer_token",
    "token": "YOUR_TOKEN_HERE"
  },
  "config": {
    "timeout": 30,
    "retry_attempts": 3,
    "// NOTE": "Adjust timeout based on your API latency"
  }
}
```

#### **Include Usage Instructions**

```python
"""
TEMPLATE: Database Connection Manager

USAGE:
1. Copy this file to your project
2. Replace DATABASE_CONFIG with your credentials
3. Update connection_string with your database URL
4. Modify retry_logic if needed for your use case

SECURITY:
- Never commit credentials to version control
- Use environment variables for sensitive data
- Implement connection pooling for production
"""

class DatabaseManager:
    # Template implementation here
```

### **Organization Strategies**

#### **By Task Complexity**

```
data-processing-skill/
├── SKILL.md
├── simple-tasks/
│   ├── csv-reader.py
│   └── basic-cleaning.py
├── intermediate-tasks/
│   ├── data-transformation.py
│   └── aggregation-patterns.py
└── advanced-tasks/
    ├── distributed-processing.py
    └── optimization-techniques.py
```

#### **By Use Case**

```
api-integration-skill/
├── SKILL.md
├── authentication/
│   ├── oauth-flow.py
│   ├── api-key-auth.py
│   └── jwt-token.py
├── data-fetching/
│   ├── rest-api.py
│   ├── graphql.py
│   └── pagination.py
└── error-handling/
    ├── retry-logic.py
    └── rate-limiting.py
```

#### **By Workflow Stage**

```
ml-pipeline-skill/
├── SKILL.md
├── 01-data-preparation/
│   ├── data-loading.py
│   └── feature-engineering.py
├── 02-model-training/
│   ├── training-loop.py
│   └── hyperparameter-tuning.py
└── 03-deployment/
    ├── model-serving.py
    └── monitoring.py
```

***

## 🚀 **Skill Versioning**

### **Project Skills (Optional Versioning)**

Project skills can optionally include version information:

```yaml
---
name: Custom Data Pipeline
version: 2.1.0  # Optional for project skills
---
```

**Version Update Workflow**:

1. Update skill files with improvements
2. Increment version number in SKILL.md
3. Document changes in version history
4. Re-upload modified skill (or use API to update)

### **Built-In Skills (Required Versioning)**

Built-in skills always have versions:

```yaml
---
name: OpenAI Best Practices
version: 1.5.0  # Required for built-in skills
---
```

**Semantic Versioning**:

* **MAJOR** (1.0.0 2.0.0): Breaking changes, incompatible updates
* **MINOR** (1.0.0 1.1.0): New features, backward compatible
* **PATCH** (1.0.0 1.0.1): Bug fixes, minor improvements

**Agent Version Locking**:

* Agents lock to specific versions of built-in skills
* Update agent configuration to use newer versions
* Prevents unexpected changes from automatic updates

***

## 📈 **Monitoring and Management**

### **Skill Status**

Each skill displays its current status:

| Status         | Meaning                                          |
| -------------- | ------------------------------------------------ |
| **Ready**      | Skill processed successfully, available to agent |
| **Processing** | Skill being uploaded or updated                  |
| **Error**      | Skill processing failed (check error message)    |

### **Troubleshooting Skills**

#### **Skill Not Appearing**

**Cause**: Skill not enabled for agent

**Solution**:

1. Check that Skills toggle is ON
2. Verify skill is in the enabled skills list
3. Confirm skill status is "Ready"

#### **Agent Can't Find Files**

**Cause**: Incorrect file paths or structure

**Solution**:

1. Verify SKILL.md exists at skill root
2. Check file paths are relative to skill root
3. Ensure no directory traversal in paths
4. Confirm files uploaded successfully

#### **Processing Failed**

**Cause**: Invalid file format or metadata

**Solution**:

1. Check SKILL.md has valid frontmatter (YAML format)
2. Verify all required metadata fields present
3. Ensure file sizes under 10 MB
4. Check for invalid characters in filenames

### **Skill Updates**

To update a project skill:

1. **Modify Files Locally**: Make changes to skill content
2. **Re-upload**: Upload modified files via API or UI
3. **Update Version**: Increment version number in SKILL.md (optional but recommended)
4. **Test**: Verify agent can access updated content
5. **Document Changes**: Note what changed in skill documentation

***

## 🎓 **Common Use Cases**

### **Use Case 1: Code Standards Enforcement**

**Scenario**: Ensure agents follow company coding standards

**Skill Structure**:

```
coding-standards/
├── SKILL.md                      # Overview and philosophy
├── python-style-guide.md         # Language-specific standards
├── git-workflow.md               # Version control best practices
├── testing-requirements.md       # Testing standards
└── examples/
    ├── good-example.py           # Compliant code
    └── anti-patterns.py          # What to avoid
```

**Agent Benefit**: Automatically applies consistent code style and patterns

### **Use Case 2: API Integration Templates**

**Scenario**: Standardize integration with third-party APIs

**Skill Structure**:

```
api-integrations/
├── SKILL.md                      # Integration overview
├── authentication/
│   └── oauth-setup.py            # Auth flow template
├── templates/
│   ├── request-handler.py        # Reusable request template
│   └── error-handling.py         # Standard error handling
└── examples/
    ├── stripe-integration.py     # Full Stripe example
    └── sendgrid-integration.py   # Full SendGrid example
```

**Agent Benefit**: Rapid, consistent API integration following proven patterns

### **Use Case 3: Data Processing Playbooks**

**Scenario**: Standardize data analysis workflows

**Skill Structure**:

```
data-playbook/
├── SKILL.md                      # Data processing overview
├── cleaning/
│   ├── outlier-detection.py
│   ├── missing-data-handling.py
│   └── normalization.py
├── analysis/
│   ├── statistical-tests.py
│   └── visualization-templates.py
└── reporting/
    ├── report-generation.py
    └── summary-statistics.py
```

**Agent Benefit**: Consistent, high-quality data analysis following best practices

### **Use Case 4: Testing and QA Patterns**

**Scenario**: Maintain testing standards across development

**Skill Structure**:

```
testing-patterns/
├── SKILL.md                      # Testing philosophy
├── unit-tests/
│   ├── test-structure.py         # Unit test template
│   └── mocking-examples.py       # Mocking patterns
├── integration-tests/
│   └── api-testing.py            # Integration test examples
└── resources/
    ├── test-coverage-guide.md
    └── ci-cd-integration.md
```

**Agent Benefit**: Comprehensive test coverage following industry standards

***

## 🎯 **Skills Configuration Checklist**

Before activating skills for your agent:

* [ ] **Skills Enabled**: Toggle switched to ON
* [ ] **Relevant Skills Added**: Selected or uploaded appropriate skills
* [ ] **SKILL.md Present**: Each skill has valid SKILL.md with metadata
* [ ] **Status Verified**: All skills show "Ready" status
* [ ] **File Structure Clear**: Skills organized logically
* [ ] **Examples Included**: Practical examples available for agent reference
* [ ] **Documentation Complete**: SKILL.md provides clear guidance
* [ ] **Test Agent Access**: Verify agent can list and read skills
* [ ] **Version Tracking**: Version numbers documented (if using versioning)
* [ ] **Code Execution**: Consider enabling [Code Execution](/ai-agents/code-execution) if skills contain executable code templates

***

## 💡 **Tips for Effective Skills**

### **Start Simple**

Begin with one or two focused skills rather than comprehensive libraries. Build incrementally based on agent needs.

### **Agent-Centric Design**

Write skill documentation for AI agents, not just humans:

* Use clear, explicit language
* Provide complete examples
* Include step-by-step procedures
* Anticipate common variations

### **Maintain and Iterate**

Skills evolve with your use cases:

* Add new examples as patterns emerge
* Remove outdated content
* Update based on agent performance
* Gather feedback from agent usage logs

### **Leverage Built-In Skills**

Before creating custom skills, check if built-in skills cover your needs. Built-in skills are professionally maintained and tested.

### **Combine with Knowledge**

Skills and Knowledge work together:

* **Knowledge**: "What are our product features?" (factual data)
* **Skills**: "How to implement feature X?" (procedural guidance)

### **Combine with Code Execution**

Skills become even more powerful when paired with **Code Execution**:

* **Skills provide**: Code templates, implementation patterns, best practices
* **Code Execution enables**: Running and adapting those templates in a live sandbox
* **Result**: Agents can read skill code, adapt it to specific tasks, and execute it

**Example**: A "data-analysis-toolkit" skill contains Python scripts for analyzing CSV data. When Code Execution is enabled, your agent can:

1. Read the analysis template from the skill
2. Adapt it to your specific CSV file and requirements
3. Execute the adapted code in the sandbox
4. Generate charts, reports, and insights automatically

See [**Code Execution documentation**](/ai-agents/code-execution#combining-code-execution-with-skills) for detailed guidance on using Skills with Code Execution.

***

Skills transform your agent from a general assistant into a specialized expert└invest in building a comprehensive skills library that enables consistent, high-quality implementations across your use cases.


# Workflow Tools Configuration

## 🔄 **Turn Workflows Into Agent Tools**

The Workflows tab is where your AI agent gains the superpower to execute complex, multi-step automations on demand. By configuring workflows as tools, your agent can intelligently decide when and how to trigger sophisticated business processes based on conversation context, user requests, or specific conditions—transforming your agent from a simple chatbot into a powerful automation orchestrator.

***

## 🎯 **What Are Workflow Tools?**

Workflow tools allow your AI agent to execute pre-built visual workflows (with 193+ available nodes) as callable functions. When configured as tools:

* **Agent Decides When**: The AI determines when a workflow should run based on user intent
* **Dynamic Input**: Agent extracts parameters from conversation and passes them to the workflow
* **Real-Time Execution**: Workflow runs and returns results back to the agent
* **Conversational Feedback**: Agent interprets workflow output and responds naturally to the user
* **Error Handling**: Agent can gracefully handle workflow failures and provide alternatives

***

## 🏗️ **How Workflow Tools Work**

When you add a workflow as a tool to your agent, the system creates a specialized function that:

1. **Exposes Workflow Parameters**: The workflow's input schema becomes the tool's parameter schema
2. **Generates Tool Description**: Uses the workflow's description to help the agent understand when to use it
3. **Handles Execution**: Runs the workflow in the background when the agent calls the tool
4. **Returns Results**: Provides workflow output, status, and any errors back to the agent
5. **Enables Conversation**: Agent interprets results and communicates naturally with the user

### **Execution Flow Example**

```
User: "Please process my order for 100 units of Product X"
↓
Agent Analysis: Identifies order processing intent
↓
Tool Selection: Chooses "Order Processing" workflow tool
↓
Parameter Extraction:
  - product = "Product X"
  - quantity = 100
  - customer_id = (from conversation context)
↓
Workflow Execution:
  1. Validate inventory availability
  2. Check customer credit limit
  3. Generate order confirmation
  4. Send to fulfillment team
  5. Update CRM records
↓
Tool Response:
  - output: {"order_id": "12345", "status": "confirmed"}
  - status: "success"
  - error: null
↓
Agent Response: "Your order has been processed successfully!
Confirmation #12345 has been sent to your email."
```

***

## ⚙️ **Configuring Workflow Tools**

To configure a workflow as an agent tool, you need to provide the following configuration settings. These settings control how the agent interacts with and executes your workflow:

***

## 🎛️ **Tool Configuration Settings**

### **1. Workflow Selection**

**Workflow ID** (Required)

* Choose which workflow this tool will execute
* Only workflows in your workspace are available
* Workflow must have a defined input schema

```
Example:
Workflow: "Customer Onboarding Workflow"
ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

***

### **2. Tool Description**

**Description** (Optional, but Highly Recommended)

* Overrides the workflow's default description
* Helps the agent understand **when** and **how** to use this tool
* Should clearly explain the tool's purpose, required context, and expected outcomes

```
Default Behavior:
If not provided, agent uses the workflow's description field

Best Practice Example:
Description: "Use this tool to onboard new enterprise customers.
Required information: company name, contact email, industry, and
estimated user count. Call this tool when a new enterprise customer
signs up or requests onboarding assistance."

Poor Example:
Description: "Onboards customers" (Too vague)
```

**Writing Effective Tool Descriptions:**

```
Good Tool Descriptions Include:
✅ Purpose: What does this tool do?
✅ When to Use: Under what circumstances should agent call it?
✅ Required Inputs: What parameters are needed?
✅ Expected Output: What will the tool return?
✅ Context Clues: Keywords or phrases that indicate this tool is needed

Example Templates:

1. Process Automation:
"Use this tool to process [ACTION] when the user requests [INTENT].
Required: [PARAM1], [PARAM2]. Returns: [OUTPUT_DESCRIPTION]"

2. Data Retrieval:
"Call this tool to fetch [DATA_TYPE] from [SOURCE]. Requires [FILTERS].
Returns structured data including [FIELDS]"

3. Business Logic:
"Execute this tool to [BUSINESS_PROCESS]. Use when user mentions
[KEYWORDS]. Input: [PARAMS]. Output: [RESULT] with status indicator"
```

***

### **3. Timeout Configuration**

**Timeout** (Required, Default: `150` seconds)

* Maximum time (in seconds) the agent will wait for workflow completion
* Range: 1-300 seconds (5 minutes maximum)
* If exceeded, agent receives timeout error and can respond accordingly

```
Timeout Guidelines:

Quick Operations (1-30 seconds):
- Database queries
- API lookups
- Simple calculations
- File reads

Standard Operations (30-90 seconds):
- Multi-step processes
- External API integrations
- Document generation
- Email sending

Complex Operations (90-300 seconds):
- Large data processing
- Multiple external service calls
- Report generation with aggregation
- Batch operations

Example Configuration:
Quick Lookup Workflow: timeout = 30
Order Processing: timeout = 90
Monthly Report Generation: timeout = 300
```

**Handling Timeouts:**

```
When Timeout Occurs:
- Agent receives error status from tool
- Can inform user of delay and suggest alternatives
- Can retry with different parameters if appropriate
- Should log timeout for monitoring and optimization

Agent Response Example:
"I started processing your request, but it's taking longer than
expected. I've queued it for completion and you'll receive an
email notification when it's done. Can I help you with anything
else in the meantime?"
```

***

### **4. Input Configuration (Pre-filled Parameters)**

**Input Config** (Optional)

* Pre-configure specific workflow input parameters
* Remove parameters from agent's decision-making
* Useful for setting constant values, security constraints, or workspace context

```
Purpose:
✅ Set constant values (workspace_id, api_keys, etc.)
✅ Apply security constraints (user_role, permissions)
✅ Provide context not available to agent (configuration settings)
✅ Simplify agent's parameter decisions
```

#### **How Input Config Works**

When you specify `input_config`, those parameters:

1. **Are automatically filled** with your specified values
2. **Are removed from the tool's schema** (agent doesn't see them)
3. **Cannot be overridden** by the agent

```
Example 1: Workspace Context
Workflow Input Schema:
{
  "workspace_id": "string (required)",
  "customer_email": "string (required)",
  "action": "string (required)"
}

Input Config:
{
  "workspace_id": "{{ workspace_id }}"  # Automatically populated
}

Agent Only Sees:
{
  "customer_email": "string (required)",
  "action": "string (required)"
}

Result:
- Agent extracts customer_email and action from conversation
- workspace_id is automatically injected from context
- Agent doesn't need to know or decide workspace_id
```

```
Example 2: Security Constraints
Workflow Input Schema:
{
  "user_id": "string (required)",
  "action": "string (required)",
  "max_amount": "number (required)",
  "requires_approval": "boolean (required)"
}

Input Config:
{
  "max_amount": 1000,
  "requires_approval": true
}

Agent Only Sees:
{
  "user_id": "string (required)",
  "action": "string (required)"
}

Result:
- Agent cannot exceed $1000 limit (hardcoded)
- Approval is always required (security enforcement)
- Agent only decides user_id and action
```

```
Example 3: Configuration Values
Workflow Input Schema:
{
  "email_template": "string (required)",
  "recipient": "string (required)",
  "sender_name": "string (required)",
  "reply_to": "string (required)"
}

Input Config:
{
  "sender_name": "Customer Support Team",
  "reply_to": "support@company.com"
}

Agent Only Sees:
{
  "email_template": "string (required)",
  "recipient": "string (required)"
}

Result:
- Consistent sender identity across all emails
- Standardized reply-to address
- Agent chooses template and recipient only
```

**Advanced Input Config Patterns:**

```
Pattern 1: Dynamic Templates with Static Constraints
{
  "template_type": "{{user_tier}}_welcome",  # Dynamic from context
  "max_discount": 0.15,                       # Static limit
  "currency": "USD"                           # Static config
}

Pattern 2: Role-Based Parameter Injection
{
  "user_role": "{{current_user_role}}",      # From auth context
  "access_level": "read_only",                # Security constraint
  "audit_enabled": true                       # Compliance requirement
}

Pattern 3: Environment Configuration
{
  "api_endpoint": "{{env.api_base_url}}",    # Environment variable
  "rate_limit": 100,                          # Quota management
  "retry_attempts": 3                         # Reliability setting
}
```

**When to Use Input Config:**

```
Best Practices:

Use Input Config For:
✅ Security-sensitive values (API keys, credentials)
✅ Workspace or tenant identifiers
✅ Compliance requirements (audit flags, data retention)
✅ Rate limits and quotas
✅ Standard business rules
✅ Configuration that shouldn't change per-request
✅ Values the agent shouldn't decide

Don't Use Input Config For:
❌ User-provided data (names, emails, preferences)
❌ Request-specific parameters (search queries, filters)
❌ Dynamic business logic decisions
❌ Values that vary based on conversation context
```

***

## 📊 **Workflow Tool Response Format**

When a workflow tool executes, it returns a structured response to the agent:

### **Success Response**

```json
{
  "output": "{\"order_id\": \"12345\", \"total\": 1500.00}",
  "status": "success",
  "error": null
}
```

### **Error Response (Detailed)**

```json
{
  "output": null,
  "status": "error",
  "error": {
    "message": "Insufficient inventory for requested quantity",
    "code": "INVENTORY_ERROR",
    "failed_node": "Check Inventory Node",
    "workflow_id": "abc-123-def",
    "workflow_name": "Order Processing",
    "node_error": {
      "node_name": "inventory_check",
      "error_message": "Available: 50, Requested: 100",
      "error_code": "INSUFFICIENT_STOCK",
      "error_details": {"available": 50, "requested": 100}
    }
  }
}
```

### **Error Response (Anonymous Users)**

```json
{
  "output": null,
  "status": "error",
  "error": "An error occurred while running the workflow."
}
```

**How Agents Handle Responses:**

```
Success:
- Agent parses output JSON
- Extracts relevant data
- Formulates natural language response
- May suggest next steps

Example:
Output: {"order_id": "12345", "total": 1500}
Agent: "Your order #12345 has been placed successfully!
Total: $1,500. You'll receive confirmation shortly."

Error:
- Agent receives error details
- Explains what went wrong in user-friendly terms
- Suggests alternatives or solutions
- May retry with different parameters

Example:
Error: "Insufficient inventory"
Agent: "I'm sorry, we only have 50 units available, but you
requested 100. Would you like to order 50 units now, or would
you prefer to wait until we restock?"
```

***

## 📊 **Workflow Types & Use Cases**

### **🎨 Data Processing Workflows as Tools**

Configure data-focused workflows as agent tools for automated information handling:

```
Use Cases:
├── Customer Data Enrichment
│   ├── Agent: Receives customer email or ID
│   ├── Workflow: Fetches CRM data, social profiles, purchase history
│   └── Returns: Enriched customer profile
│
├── Report Generation on Demand
│   ├── Agent: User requests "monthly sales report"
│   ├── Workflow: Queries database, generates charts, formats PDF
│   └── Returns: Download link and summary statistics
│
├── Data Validation & Cleanup
│   ├── Agent: User uploads CSV file
│   ├── Workflow: Validates format, deduplicates, enriches missing fields
│   └── Returns: Cleaned data file and validation report
│
└── Real-Time Data Aggregation
    ├── Agent: User asks "what's our current revenue?"
    ├── Workflow: Queries multiple sources, calculates totals
    └── Returns: Real-time financial metrics
```

**Configuration Example:**

```
Workflow Tool: "Customer Data Lookup"
Description: "Use this tool to fetch detailed customer information
when the user provides a customer ID, email, or company name.
Returns: customer profile, purchase history, support tickets, and
account status."

Run Behavior: auto_run (safe read-only operation)
Timeout: 45 seconds
Input Config:
{
  "data_sources": ["crm", "support", "billing"],
  "include_pii": false  # Compliance constraint
}
```

### **⚙️ Business Process Workflows as Tools**

Turn complex business processes into agent-callable tools:

```
Use Cases:
├── Order Processing
│   ├── Agent: "Process order for 100 units"
│   ├── Workflow: Inventory check → Credit verification → Order creation → Notification
│   ├── Run Behavior: request_confirmation (financial transaction)
│   └── Returns: Order ID, confirmation, estimated delivery
│
├── Customer Onboarding
│   ├── Agent: "Onboard new enterprise customer"
│   ├── Workflow: Account creation → Setup tasks → Welcome emails → Team assignment
│   ├── Run Behavior: auto_run (internal process)
│   └── Returns: Account details, next steps checklist
│
├── Support Ticket Escalation
│   ├── Agent: Detects high-priority issue
│   ├── Workflow: Classify urgency → Assign specialist → Notify stakeholders
│   ├── Run Behavior: auto_run (time-sensitive)
│   └── Returns: Ticket ID, assigned agent, response timeline
│
└── Document Approval Workflow
    ├── Agent: "Submit contract for approval"
    ├── Workflow: Upload document → Route to approvers → Track status
    ├── Run Behavior: request_confirmation (legal process)
    └── Returns: Approval tracking link, estimated completion
```

### **🤖 Integration Workflows as Tools**

Connect external systems and services through workflow tools:

```
Use Cases:
├── Multi-System Data Sync
│   ├── Agent: "Sync customer data across systems"
│   ├── Workflow: CRM → Marketing Platform → Support System → Analytics
│   ├── Tools Used: Salesforce, HubSpot, Zendesk, Google Sheets
│   └── Returns: Sync status, records updated, any conflicts
│
├── Email Campaign Trigger
│   ├── Agent: "Send welcome email to new users"
│   ├── Workflow: Template selection → Personalization → Send via API
│   ├── Tools Used: Email service provider (SendGrid, Mailchimp)
│   └── Returns: Campaign ID, recipients count, delivery status
│
├── Payment Processing
│   ├── Agent: "Process refund for order #12345"
│   ├── Workflow: Verify order → Process refund → Update records → Send receipt
│   ├── Tools Used: Stripe/PayPal API, database, email service
│   ├── Run Behavior: request_confirmation (financial)
│   └── Returns: Refund ID, amount, status, receipt URL
│
└── Calendar & Meeting Management
    ├── Agent: "Schedule demo with lead"
    ├── Workflow: Check availability → Create meeting → Send invites → Add to CRM
    ├── Tools Used: Google Calendar, Zoom, Salesforce
    └── Returns: Meeting link, calendar event, CRM activity logged
```

***

## 🚀 **Workflow Tool Best Practices**

### **Design Principles**

#### **1. Clear Tool Descriptions**

```
✅ Good Description:
"Use this tool to process customer refunds. Required: order_id,
amount, reason. Validates order exists, checks refund eligibility,
processes refund via payment gateway, sends confirmation email.
Returns refund_id and status. Call when user requests refund or
reports payment issue requiring resolution."

❌ Poor Description:
"Handles refunds"
```

#### **2. Appropriate Run Behavior Selection**

```
Auto Run For:
✅ Data lookups and queries
✅ Report generation
✅ Status checks
✅ Read-only operations
✅ Internal process automation

Request Confirmation For:
⚠️ Financial transactions
⚠️ Data modifications or deletions
⚠️ External communications
⚠️ Account changes
⚠️ Irreversible operations
```

#### **3. Optimal Timeout Configuration**

```
Guidelines:
- Quick operations: 15-30 seconds
- Standard workflows: 60-90 seconds
- Complex processes: 120-300 seconds
- Monitor actual execution times and adjust
- Consider adding buffer for external API delays
```

#### **4. Strategic Input Config Usage**

```
Pre-fill When:
✅ Value is constant (workspace_id, environment settings)
✅ Security constraint must be enforced (max_amount, permissions)
✅ Compliance requirement (audit_enabled, data_retention)
✅ Configuration simplification for agent

Let Agent Decide When:
✅ User-specific data (names, emails, preferences)
✅ Request-specific parameters (quantities, dates)
✅ Dynamic context (search queries, filters)
```

***

## ⚙️ **Testing & Validation**

### **Testing Workflow Tools**

#### **Pre-Deployment Testing Checklist**

```
- [ ] Tool description clearly explains when to use the tool
- [ ] Agent correctly identifies when to call the tool
- [ ] Required parameters are properly extracted from conversation
- [ ] Input config correctly pre-fills constant values
- [ ] Timeout is appropriate for workflow complexity
- [ ] Run behavior matches risk level (auto vs confirmation)
- [ ] Success responses are properly interpreted by agent
- [ ] Error responses provide actionable feedback
- [ ] Edge cases are handled gracefully
- [ ] Performance meets user expectations
```

#### **Testing Scenarios**

```
1. Happy Path Test:
   - User provides all required information
   - Workflow executes successfully
   - Agent responds with appropriate confirmation

2. Missing Parameters Test:
   - User provides incomplete information
   - Agent asks clarifying questions
   - Once complete, executes workflow

3. Error Handling Test:
   - Workflow encounters an error (e.g., insufficient inventory)
   - Agent receives error details
   - Agent explains issue and suggests alternatives

4. Timeout Test:
   - Workflow takes longer than expected
   - Agent handles timeout gracefully
   - User is informed and provided options

5. Confirmation Flow Test (if run_behavior = request_confirmation):
   - Agent explains what will happen
   - User approves, denies, or modifies
   - Agent responds appropriately to each choice
```

***

## 🔄 **Workflow Execution Flow**

When an agent calls a workflow tool, the system follows this execution sequence:

### **Execution Steps**

1. **Parameter Collection**: Agent extracts required parameters from conversation context and user input
2. **Input Template Application**: Any pre-configured `input_config` values are merged with agent-provided parameters
3. **Parameter Substitution**: Template variables (like `{{workspace_id}}`) are replaced with actual values
4. **Workflow Run Creation**: System creates a workflow run record marked as "triggered\_by: agent"
5. **Workflow Execution**: Workflow engine processes all nodes in the workflow
6. **Event Callbacks**: Each workflow step fires events that are processed and stored
7. **Response Generation**: Workflow completes and returns output, status, and any errors
8. **Agent Response**: Agent interprets the result and formulates a natural language response

### **Data Flow Example**

```
Agent Call:
run_workflow_order_processing(
  product_sku="PROD-X",
  quantity=100,
  customer_id="CUST-123"
)

Input Template Applied:
{
  "workspace_id": "abc-workspace-123",  # From input_config
  "product_sku": "PROD-X",              # From agent
  "quantity": 100,                      # From agent
  "customer_id": "CUST-123",            # From agent
  "max_discount": 0.10,                 # From input_config
  "requires_approval": false            # From input_config
}

Workflow Executes:
→ Node 1: Validate inventory (50 units available)
→ Node 2: ERROR - Insufficient stock

Error Response:
{
  "output": null,
  "status": "error",
  "error": {
    "message": "Insufficient inventory for requested quantity",
    "code": "INVENTORY_ERROR",
    "failed_node": "Validate Inventory",
    "node_error": {
      "node_name": "inventory_check",
      "error_message": "Available: 50, Requested: 100",
      "available": 50,
      "requested": 100
    }
  }
}

Agent Interprets & Responds:
"I checked our inventory and we currently have 50 units of Product X
available, but you requested 100 units. Would you like to order the
50 units we have in stock, or wait until we restock?"
```

***

## 🎯 **Common Patterns & Examples**

### **Pattern 1: Read-Only Data Query**

```
Workflow Tool: "customer_lookup"
Description: "Fetch customer details by ID, email, or company name"

Configuration:
- run_behavior: "auto_run" (safe read operation)
- timeout: 30 seconds
- input_config:
  {
    "workspace_id": "{{workspace_id}}",
    "include_sensitive_data": false
  }

Agent Usage:
User: "What's the status of customer ABC Corp?"
Agent extracts: company_name="ABC Corp"
Agent calls: customer_lookup(company_name="ABC Corp")
Returns: Customer profile with account status, recent orders
Agent responds: "ABC Corp is an active customer since 2022..."
```

### **Pattern 2: Confirmation-Required Action**

```
Workflow Tool: "process_refund"
Description: "Process customer refund for an order"

Configuration:
- run_behavior: "request_confirmation" (financial operation)
- timeout: 90 seconds
- input_config:
  {
    "workspace_id": "{{workspace_id}}",
    "max_refund_amount": 5000,
    "notify_accounting": true
  }

Agent Usage:
User: "I need a refund for order #12345"
Agent analyzes: order_id="12345", validates order exists
Agent proposes:
  "I can process a refund for order #12345 ($1,200).
   This will:
   - Credit the original payment method
   - Send confirmation email
   - Update order status to 'refunded'
   Would you like me to proceed?"
User: "Yes"
Agent calls: process_refund(order_id="12345")
Returns: Refund confirmation with transaction ID
```

### **Pattern 3: Multi-Step Process Automation**

```
Workflow Tool: "onboard_customer"
Description: "Complete customer onboarding process"

Configuration:
- run_behavior: "auto_run" (internal process)
- timeout: 120 seconds
- input_config:
  {
    "workspace_id": "{{workspace_id}}",
    "onboarding_template": "enterprise",
    "assign_success_manager": true
  }

Agent Usage:
User: "New customer: Acme Inc, email: contact@acme.com, 500 seats"
Agent extracts:
  company_name="Acme Inc"
  email="contact@acme.com"
  seat_count=500
Agent calls: onboard_customer(...)
Workflow executes:
  → Create account
  → Provision licenses
  → Send welcome email
  → Assign success manager
  → Schedule kickoff call
Returns: Account details, next steps
Agent responds: "Welcome aboard! I've created your account..."
```

***

## 🔐 **Security & Error Handling**

### **Security Considerations**

#### **Error Information Disclosure**

The workflow tool automatically adjusts error detail based on user authentication:

```
Authenticated Users (Detailed Errors):
- Full error message and error code
- Failed node name and workflow information
- Node-specific error details
- Helpful for debugging and troubleshooting

Anonymous Users (Generic Errors):
- Generic error message only
- No internal system details exposed
- Prevents information leakage
- Maintains security boundaries

Configuration:
show_detailed_errors = true   # For authenticated users
show_detailed_errors = false  # For anonymous users
```

#### **Input Validation & Constraints**

```
Security Best Practices:

1. Use input_config to enforce limits:
   {
     "max_amount": 5000,           # Financial limits
     "allowed_actions": ["read"],  # Permission constraints
     "rate_limit": 100             # Quota management
   }

2. Validate workflow input schema:
   - Required parameters are enforced
   - Type validation prevents injection
   - Range checks prevent abuse

3. Workspace isolation:
   - workspace_id automatically injected
   - Users cannot access other workspaces
   - Data segregation enforced
```

### **Error Handling Patterns**

#### **Transient Errors**

```
Scenario: External API timeout or temporary failure

Workflow Behavior:
- Returns error status with details
- Agent can suggest retry

Agent Response:
"I encountered a temporary issue connecting to the payment
system. Would you like me to try again, or would you prefer
to complete this transaction later?"
```

#### **Validation Errors**

```
Scenario: User provides invalid input (e.g., negative quantity)

Workflow Behavior:
- Validation node catches error early
- Returns specific validation failure

Agent Response:
"I notice you entered a negative quantity. Please provide
a positive number of units you'd like to order."
```

#### **Business Logic Errors**

```
Scenario: Business rule violation (e.g., insufficient funds)

Workflow Behavior:
- Business logic node evaluates condition
- Returns actionable error with context

Agent Response:
"Your account has a credit limit of $10,000 and this order
would exceed that limit. Would you like to:
1. Place a smaller order within your limit
2. Contact our sales team to increase your credit limit"
```

***

## 🎯 **Workflow Tool Configuration Checklist**

Before deploying workflow tools with your agent:

### **Configuration**

* [ ] **Workflow Selected**: Appropriate workflow chosen for the task
* [ ] **Tool Description**: Clear, detailed description of when and how to use the tool
* [ ] **Run Behavior**: Correct behavior set (auto\_run vs request\_confirmation)
* [ ] **Timeout**: Appropriate timeout based on workflow complexity
* [ ] **Input Config**: Security constraints and constant values properly configured

### **Testing**

* [ ] **Happy Path**: Workflow executes successfully with valid inputs
* [ ] **Parameter Extraction**: Agent correctly extracts required parameters
* [ ] **Error Handling**: Agent gracefully handles workflow errors
* [ ] **Timeout Handling**: Agent responds appropriately to timeout scenarios
* [ ] **Confirmation Flow**: Request confirmation behavior works as expected (if applicable)

### **Security**

* [ ] **Financial Operations**: Use request\_confirmation for all financial transactions
* [ ] **Data Modifications**: Appropriate safeguards for destructive operations
* [ ] **Input Validation**: Workflow validates all inputs properly
* [ ] **Permission Checks**: Proper authorization enforced within workflow
* [ ] **Error Disclosure**: Sensitive information not leaked in error messages

### **Performance**

* [ ] **Response Time**: Workflow completes within acceptable timeframe
* [ ] **Resource Usage**: Workflow doesn't consume excessive resources
* [ ] **Concurrency**: Multiple simultaneous calls handled properly
* [ ] **Monitoring**: Performance metrics tracked and alerted

***

## 📚 **Additional Resources**

### **Related Documentation**

* [**Workflows Overview**](/workflows/04-workflows): Learn about building workflows
* [**Workflow Node Reference**](/reference/nodes): Browse available nodes
* [**Agent Configuration Overview**](/ai-agents/03-agents): Complete agent setup guide
* [**MCP Tools Configuration**](/ai-agents/mcp-tools): Add external tool integrations
* [**Sub-Agents**](/ai-agents/sub-agents): Coordinate multiple AI agents

### **Key Concepts**

* **Workflow Input Schema**: Defines parameters the workflow accepts
* **Tool Description**: Guides agent on when to use the tool
* **Run Behavior**: Controls automatic execution vs confirmation requirement
* **Input Config**: Pre-fills constant values and enforces constraints
* **Timeout**: Maximum execution time before timeout error

***

## 💡 **Quick Reference**

### **Configuration Schema**

```json
{
  "workflow_id": "UUID (required)",
  "description": "string (optional, recommended)",
  "run_behavior": "auto_run | request_confirmation (default: auto_run)",
  "timeout": "number (1-300 seconds, default: 150)",
  "input_config": {
    "param_name": "static_value or {{template_variable}}"
  }
}
```

### **Common Configuration Examples**

**Data Query Tool:**

```json
{
  "workflow_id": "customer-lookup-workflow-id",
  "description": "Fetch customer data by ID, email, or company name",
  "run_behavior": "auto_run",
  "timeout": 30,
  "input_config": {
    "workspace_id": "{{workspace_id}}",
    "include_pii": false
  }
}
```

**Financial Transaction Tool:**

```json
{
  "workflow_id": "refund-processing-workflow-id",
  "description": "Process customer refund for completed orders",
  "run_behavior": "request_confirmation",
  "timeout": 90,
  "input_config": {
    "workspace_id": "{{workspace_id}}",
    "max_refund_amount": 5000,
    "notify_accounting": true
  }
}
```

**Process Automation Tool:**

```json
{
  "workflow_id": "customer-onboarding-workflow-id",
  "description": "Complete new customer onboarding process",
  "run_behavior": "auto_run",
  "timeout": 120,
  "input_config": {
    "workspace_id": "{{workspace_id}}",
    "onboarding_template": "enterprise"
  }
}
```

***

**Transform your AI agent into a powerful automation orchestrator by connecting conversations directly to workflow execution.**


# MCP Tools Configuration

## 🌐 **What is MCP?**

**MCP (Model Context Protocol)** is like a universal connector that lets your AI agent access external tools and data—think of it as giving your agent superpowers to interact with the real world.

### **What MCP Does for Your Agent**

Instead of just chatting, your agent can now:

* 📁 **Read and write files** in your project folders
* 🗄️ **Query databases** to fetch business data
* 📧 **Send emails** through Gmail or Outlook
* 💬 **Post messages** to Slack or Teams
* 🎫 **Create tickets** in Jira or Zendesk
* 🔍 **Search code** in GitHub repositories
* 📊 **Fetch analytics** from your business tools
* 🛒 **Access CRM data** from Salesforce or HubSpot
* ⚡ **And 300+ more integrations**

### **Why Use MCP?**

**Before MCP:**

* Agents could only chat and answer questions
* No access to your files, databases, or business tools
* Limited to what's in their training data

**With MCP:**

* Agents take real actions in your systems
* Access live data from your business applications
* Automate workflows across multiple tools
* Work with your actual project files and data

***

## 🔧 **How MCP Works (Simple Explanation)**

Think of MCP like adding apps to your smartphone:

1. **MCP Servers** = App Store apps (Gmail, Slack, GitHub, etc.)
2. **MCP Connections** = Installing and logging into apps
3. **MCP Tools** = Features within each app (send email, post message, search code)
4. **Your Agent** = The user who can now use these apps

**Example Workflow:**

1. You set up a connection to Gmail (like logging into Gmail on your phone)
2. Your agent can now access Gmail tools (send email, read inbox, etc.)
3. When a user asks "Send this to my team", the agent uses the Gmail tool
4. The email gets sent—just like you would do manually

***

## 🚀 **Setting Up MCP Tools (2-Step Process)**

### **Step 1: Create MCP Connections** (One-Time Setup)

Before your agent can use MCP tools, you need to set up connections to the services you want to use.

#### **Where to Set Up Connections**

1. Go to your **Project Settings**
2. Click on **Connections** or **Integrations**
3. Click **"Add Connection"**
4. Select **"MCP Client"**

#### **What You'll Configure**

**1. Name Your Connection**

* Give it a clear, descriptive name
* Example: "GitHub Code Access", "Gmail for Support", "Analytics Database"

**2. Enter Server URL**

* This is the address of the MCP server
* Your provider or IT team will give you this URL
* Example: `https://mcp.github.com/v1`

**3. Choose Transport Type**

* **Streamable HTTP**: Modern standard, recommended for all new connections
* **SSE (Server-Sent Events)**: Legacy method, being deprecated
* If unsure, use **Streamable HTTP**

**4. Set Up Authentication**

You have two options:

**Option A: No Authentication**

* For internal tools or public services
* Just click "Save" and you're done

**Option B: OAuth (Secure Login)**

* For services like Gmail, GitHub, Slack
* Click **"Initialize OAuth"**
* You'll be redirected to login (like "Sign in with Google")
* Approve the permissions
* AgenticFlow saves your login securely
* Tokens refresh automatically—no need to re-login

**5. Test Connection**

* Click **"Test Connection"**
* You'll see a list of available tools
* Green checkmark = Connection works!
* Red error = Check your URL or authentication

#### **Example: Setting Up Gmail**

```
Name: Gmail for Customer Support
URL: https://mcp.gmail.com/v1
Transport: Streamable HTTP
Authentication: OAuth
  → Click "Initialize OAuth"
  → Login with your Google account
  → Approve email permissions
  → Done! ✓
```

### **Step 2: Add MCP Tools to Your Agent**

Now that connections are set up, configure which ones your agent can use.

#### **In Agent Builder → Tab 5: MCP Tools**

**1. Click "Add MCP Client"**

* Select from your configured connections
* You'll see all available tools from that service

**2. Configure Tool Behavior**

**Run Behavior:** How the agent uses tools

* **Auto Run** (Recommended for most cases)
  * Agent automatically uses tools when needed
  * Best for: File reading, data queries, searches
  * Example: "Show me the latest sales data" → Agent queries database automatically
* **Request Confirmation** (For sensitive actions)
  * Agent asks user before using tool
  * Best for: Sending emails, creating tickets, deleting files
  * Example: "Send email to client" → Agent asks "Should I send this email?" → User confirms

**Timeout:** How long to wait for tool response

* Default: 150 seconds (2.5 minutes)
* Increase for slow operations (large file processing, complex queries)
* Decrease for quick operations (simple API calls)

**3. Select Specific Tools (Optional)**

By default, your agent can use **all tools** from the connection. You can customize:

**Allow All Tools:**

* Leave tool selection empty
* Agent can use any tool from this connection
* Good when you trust all capabilities

**Choose Specific Tools:**

* Toggle which tools the agent can use
* Example: For GitHub, allow "search code" and "read file" but not "delete repository"
* Prevents accidental destructive actions

**4. Add Usage Instructions (Optional)**

Tell your agent when and how to use these tools:

**Example for File System:**

```
Use these tools when users ask to read, write, or organize files in their project.
Always check if a file exists before trying to read it.
Ask for confirmation before deleting any files.
```

**Example for CRM:**

```
Search customer records when users ask about account details or contact information.
Always create new leads when a potential customer is mentioned.
Update contact details when users provide new information.
```

**Example for Email:**

```
Send emails only when explicitly requested.
Always show the draft to the user before sending.
Use professional tone in all email communications.
```

***

## 🎯 **Common MCP Tool Setups**

### **Setup 1: Customer Support Agent**

**Goal:** Agent handles support tickets and emails

**MCP Connections Needed:**

1. **Gmail** - Send and read customer emails
2. **Zendesk** - Create and update support tickets
3. **Knowledge Base** - Search help documentation

**Agent Configuration:**

```
MCP Client: Gmail
  Run Behavior: Request Confirmation
  Timeout: 60 seconds
  Tools: Send email, read inbox, search messages
  Instructions: "Always show email drafts before sending"

MCP Client: Zendesk
  Run Behavior: Auto Run
  Timeout: 90 seconds
  Tools: Create ticket, update ticket, search tickets
  Instructions: "Create tickets for all customer issues"

MCP Client: Knowledge Base
  Run Behavior: Auto Run
  Timeout: 30 seconds
  Tools: Search articles, get article content
  Instructions: "Search help docs before escalating to human"
```

### **Setup 2: Development Assistant Agent**

**Goal:** Agent helps with coding and project management

**MCP Connections Needed:**

1. **GitHub** - Access code repositories
2. **Jira** - Manage development tasks
3. **File System** - Read/write project files

**Agent Configuration:**

```
MCP Client: GitHub
  Run Behavior: Auto Run
  Timeout: 120 seconds
  Tools: Search code, read file, list repositories
  Instructions: "Help find code examples and explain implementations"

MCP Client: Jira
  Run Behavior: Request Confirmation
  Timeout: 60 seconds
  Tools: Create issue, update issue, search issues
  Instructions: "Create tickets for bugs, ask before updating existing tickets"

MCP Client: Project Files
  Run Behavior: Auto Run
  Timeout: 45 seconds
  Tools: Read file, list directory (delete disabled)
  Instructions: "Read project files when analyzing code structure"
```

### **Setup 3: Sales & Analytics Agent**

**Goal:** Agent provides business insights and manages leads

**MCP Connections Needed:**

1. **Salesforce** - CRM data and lead management
2. **Analytics Database** - Business metrics
3. **Slack** - Team notifications

**Agent Configuration:**

```
MCP Client: Salesforce CRM
  Run Behavior: Request Confirmation
  Timeout: 90 seconds
  Tools: Search contacts, create lead, view opportunities
  Instructions: "Look up customer details, create leads for new prospects"

MCP Client: Analytics Database
  Run Behavior: Auto Run
  Timeout: 120 seconds
  Tools: Execute query, list tables
  Instructions: "Query sales metrics, user statistics, and performance data"

MCP Client: Slack Notifications
  Run Behavior: Auto Run
  Timeout: 30 seconds
  Tools: Post message, send to channel
  Instructions: "Notify #sales channel for high-value leads"
```

***

## 🛡️ **Security & Permissions**

### **Authentication Security**

**OAuth (Recommended):**

* Most secure method for cloud services
* You login once, AgenticFlow handles the rest
* Tokens stored encrypted
* Auto-refreshes—no re-authentication needed
* Can revoke access anytime from service settings

**No Authentication:**

* Only use for internal/private tools
* Good for tools on your private network
* Not recommended for internet-facing services

### **Tool Permissions Best Practices**

**Grant Only What's Needed:**

* ✅ **DO**: Enable "read file" for code review agents
* ❌ **DON'T**: Enable "delete file" unless absolutely necessary

**Use Request Confirmation for:**

* Sending emails or messages
* Creating/updating database records
* Deleting any data
* Making purchases or financial transactions
* Publishing content publicly

**Use Auto Run for:**

* Reading files or data
* Searching and querying
* Fetching information
* Generating reports
* Non-destructive operations

### **Monitoring & Safety**

**What AgenticFlow Tracks:**

* Every tool your agent uses
* When tools are called and by which user
* Success or failure of each tool call
* Time taken for each operation

**Review Agent Logs:**

* Check which tools are being used most
* Identify failed tool calls
* Monitor for unexpected behavior
* Audit sensitive operations

***

## 🔍 **Troubleshooting Common Issues**

### **Issue: "Authentication Failed"**

**What it means:** Agent can't connect to the MCP server

**How to fix:**

1. Go to **Connection Settings** → Find the MCP connection
2. Check if status shows "Not Authenticated"
3. For OAuth: Click **"Re-authorize"** and login again
4. For No Auth: Verify the server URL is correct
5. Click **"Test Connection"** to verify

### **Issue: "Tool Not Found"**

**What it means:** Agent tries to use a tool that's not available

**How to fix:**

1. Go to **Agent Builder** → **Tab 5: MCP Tools**
2. Verify the MCP client is added to your agent
3. Check the tool name is spelled correctly
4. In tool selection, make sure the tool is **enabled** (toggled on)
5. Test the connection to see available tools

### **Issue: "Timeout Error"**

**What it means:** Tool took too long to respond

**How to fix:**

1. Go to **Agent Builder** → **Tab 5: MCP Tools**
2. Find the MCP client configuration
3. Increase the **Timeout** value (try 200-300 seconds)
4. If still failing, contact your MCP server administrator
5. Consider if the operation is too complex (query too large, file too big)

### **Issue: "Permission Denied"**

**What it means:** Agent doesn't have permission for this tool

**How to fix:**

1. Check if tool is enabled in agent configuration
2. For OAuth: Re-authorize with correct permissions/scopes
3. Verify your user account has permission in the external service
4. Check if IP whitelisting is needed for your MCP server

### **Issue: "Agent Doesn't Use Tools"**

**What it means:** Agent answers questions but doesn't use MCP tools

**How to fix:**

1. **Add instructions** in MCP tool description
2. **Update system prompt** to mention when to use tools
3. **Test directly**: Ask "Can you read the file X?" (be explicit)
4. **Check model selection**: Some models are better at tool use (Claude, GPT-4)
5. **Verify tools are enabled** in agent configuration

***

## 📊 **Monitoring Tool Usage**

### **View Agent Activity**

**In Agent Dashboard:**

* See which tools were called in each conversation
* View success/failure rates
* Check average response times
* Monitor token usage

**In Connection Settings:**

* See when OAuth tokens expire
* Check connection health status
* View last successful connection
* Test tools on-demand

### **Understanding Tool Performance**

**Good Performance:**

* Tool calls succeed > 95% of time
* Response time < 5 seconds for most operations
* OAuth tokens refresh automatically
* No authentication errors

**Needs Attention:**

* Success rate < 90%
* Frequent timeout errors
* Repeated authentication failures
* Users complaining about slow responses

**Optimization Tips:**

* Increase timeout for slow operations
* Use caching when possible
* Limit number of tools per agent (5-10 is ideal)
* Remove unused MCP connections
* Monitor during peak usage times

***

## ✅ **Best Practices Checklist**

### **Before Deployment**

* [ ] **Test each MCP connection** - Click "Test Connection" and verify tools appear
* [ ] **Authenticate OAuth services** - Complete login flow and verify "Authorized" status
* [ ] **Configure timeouts appropriately** - 30s for fast operations, 120s+ for slow
* [ ] **Set run behavior** - Auto Run for safe operations, Request Confirmation for sensitive
* [ ] **Add usage instructions** - Tell agent when and how to use each tool
* [ ] **Test in chat** - Ask agent to use each tool and verify it works
* [ ] **Review permissions** - Disable dangerous tools (delete, publish, etc.)
* [ ] **Document setup** - Note which connections are used and why

### **After Deployment**

* [ ] **Monitor agent logs** - Check tool usage weekly
* [ ] **Review tool performance** - Look for errors or slow operations
* [ ] **Update OAuth tokens** - Re-authorize if seeing auth errors
* [ ] **Gather user feedback** - Ask if tools are working as expected
* [ ] **Optimize configuration** - Remove unused tools, adjust timeouts
* [ ] **Security audit** - Review permissions quarterly
* [ ] **Update instructions** - Refine based on actual usage patterns

***

## 🎓 **Tips for Success**

### **Start Simple**

* Begin with 1-2 MCP connections
* Test thoroughly before adding more
* Add tools gradually based on actual needs
* Don't overwhelm your agent with too many options

### **Name Things Clearly**

* Use descriptive connection names: "Gmail for Support" not "Connection 1"
* Write clear usage instructions
* Document what each tool does
* Make it easy for future you to understand

### **Test Before Going Live**

* Use Chat Playground to test each tool
* Try edge cases (empty results, errors, timeouts)
* Verify confirmations work as expected
* Check that errors are handled gracefully

### **Guide Your Agent**

* Add instructions for when to use tools
* Include examples in system prompt
* Mention tools in agent knowledge base
* Be specific about use cases

### **Monitor and Improve**

* Check logs regularly
* Look for patterns in tool usage
* Identify and fix common errors
* Adjust based on user feedback

***

## 🔗 **Related Documentation**

* [**Agent Configuration Overview**](/ai-agents/03-agents) - Understanding all 11 configuration tabs
* [**Model Selection**](/ai-agents/model-selection) - Choosing the right AI model for tool use
* [**Workflow Tools**](/ai-agents/workflows) - Configure workflows as agent tools
* [**Knowledge Base**](/ai-agents/knowledge) - Combining MCP tools with knowledge

***

## 📚 **Learn More About MCP**

**What is MCP?**

* Visit [modelcontextprotocol.io](https://modelcontextprotocol.io) for the official guide
* Universal standard for AI tool integrations
* Created by Anthropic, adopted industry-wide
* Open-source and extensible

**Finding MCP Servers:**

* Browse official server directory
* Search npm for `@modelcontextprotocol/*` packages
* Check your service provider's documentation
* Many popular tools have official MCP servers

**Custom Integrations:**

* Contact AgenticFlow support for custom MCP server setup
* Work with your IT team to deploy internal MCP servers
* Request new integrations from the AgenticFlow team

***

**Need Help?**

* **In-App Support**: Click the help icon in Agent Builder
* **Community**: Ask in AgenticFlow community forums
* **Support Team**: Contact <support@agenticflow.ai>

Your agent's MCP tools transform it from a chatbot into a powerful automation assistant—configure thoughtfully, test thoroughly, and watch your agent handle real work! 🚀


# Plugin Tools Configuration

## 🔌 **What are Plugin Tools?**

Plugin tools enable your AI agent to execute individual workflow nodes as tools during conversations. Unlike workflow tools that run entire multi-step workflows, plugin tools give your agent access to specific node capabilities like:

* **LLM nodes**: Call other AI models for specialized tasks
* **API nodes**: Make HTTP requests to external services
* **Data transformation nodes**: Convert formats, extract structured data
* **Integration nodes**: Execute actions in connected services (Telegram, Google Sheets, etc.)
* **Utility nodes**: Perform calculations, string operations, and more

**Key Differences from Workflow Tools:**

* **Workflow Tools**: Execute complete multi-step workflows with complex logic
* **Plugin Tools**: Execute single workflow nodes for specific, atomic operations
* **Use Plugin Tools When**: You need fine-grained control over individual operations
* **Use Workflow Tools When**: You need to execute complex, multi-step processes

***

## ⚙️ **Plugin Tool Configuration**

Each plugin tool requires the following configuration:

### **Required Fields**

| Field              | Description                   | Example                              |
| ------------------ | ----------------------------- | ------------------------------------ |
| **Plugin ID**      | The workflow node type to use | `echo`, `llm`, `openai_ask_chat_gpt` |
| **Plugin Version** | Version of the node           | `1.0.0` (standard for all nodes)     |

### **Optional Fields**

| Field            | Description                                      | When to Use                                                                                                                                                               |
| ---------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Connection**   | Connection ID for nodes requiring authentication | Some nodes require a connection to external services. Check the specific node's documentation in the [Node Library](/reference/nodes) to see if a connection is required. |
| **Input Config** | Pre-configure specific input fields              | When you want to fix certain parameters and hide them from the agent                                                                                                      |

***

## 🔧 **Input Configuration (Advanced)**

The `input_config` feature allows you to pre-configure specific input fields for a plugin tool. This is useful when:

1. **You want to fix certain parameters**: Set a specific model, temperature, or other settings
2. **Simplify the agent's decision-making**: Remove fields the agent doesn't need to decide
3. **Enforce consistency**: Ensure certain values are always used
4. **Hide complexity**: Pre-configure technical details from the agent

### **How It Works**

When you configure an input field:

1. The field is **removed from the tool's schema** presented to the agent
2. The agent **cannot override** this value
3. The pre-configured value is **automatically merged** during execution
4. The field becomes **invisible** to the AI model

### **Configuration Format**

Each input field configuration consists of:

```json
{
  "field_name": {
    "value": "the_actual_value",
    "description": "Optional: why this value is set"
  }
}
```

### **Example 1: Pre-configure LLM Model**

Configure an LLM plugin with a fixed model and temperature:

```json
{
  "plugin_id": "llm",
  "plugin_version": "1.0.0",
  "input_config": {
    "model": {
      "value": "google-gemini-2.0-flash-lite",
      "description": "Fixed model for cost control"
    },
    "temperature": {
      "value": 0.7,
      "description": "Balanced creativity"
    }
  }
}
```

**Result**: The agent can use the LLM tool but only needs to provide the `prompt`. The model and temperature are automatically set to your configured values.

### **Example 2: Pre-configure Message Template**

Configure an echo plugin with a pre-configured greeting:

```json
{
  "plugin_id": "echo",
  "plugin_version": "1.0.0",
  "input_config": {
    "data": {
      "value": "Hello, World!",
      "description": "Pre-configured greeting message"
    }
  }
}
```

### **Example 3: Pre-configure ChatGPT with Fixed Prompt**

Configure OpenAI ChatGPT with a fixed system behavior:

```json
{
  "plugin_id": "openai_ask_chat_gpt",
  "plugin_version": "1.0.0",
  "connection": "openai_connection_id",
  "input_config": {
    "prompt": {
      "value": "Repeat the following value: {{user_input}}"
    },
    "model": {
      "value": "google-gemini-2.0-flash-lite"
    },
    "temperature": {
      "value": 0.7
    }
  }
}
```

**Note**: You can use template variables like `{{user_input}}` in pre-configured values if the node supports templating.

***

## 📋 **Common Plugin Tool Configurations**

### **1. Add LLM Plugin Tool**

Give your agent access to another AI model for specialized tasks:

**Configuration:**

```json
{
  "plugin_id": "llm",
  "plugin_version": "1.0.0",
  "input_config": {
    "model": {
      "value": "google-gemini-2.0-flash-lite"
    }
  }
}
```

**Use Cases:**

* Use a reasoning model for complex logic
* Use a vision model for image analysis
* Use a fast model for simple tasks

***

### **2. Add API Call Plugin Tool**

Allow your agent to make HTTP requests:

**Configuration:**

```json
{
  "plugin_id": "api_call",
  "plugin_version": "1.0.0"
}
```

**Use Cases:**

* Fetch data from external APIs
* Send data to third-party services
* Integrate with custom backends

***

### **3. Add String to JSON Plugin Tool**

Parse JSON strings into structured data:

**Configuration:**

```json
{
  "plugin_id": "string_to_json",
  "plugin_version": "1.0.0"
}
```

**Use Cases:**

* Parse API responses
* Convert string data to structured format
* Handle JSON in conversations

***

### **4. Add Telegram Send Message Plugin**

Send Telegram messages:

**Configuration:**

```json
{
  "plugin_id": "telegram_send_message",
  "plugin_version": "1.0.0",
  "connection": "telegram_connection_id"
}
```

**Use Cases:**

* Send notifications to Telegram
* Alert users via Telegram
* Automated messaging

***

### **5. Add OpenAI ChatGPT Plugin**

Use OpenAI's ChatGPT as a specialized tool:

**Configuration:**

```json
{
  "plugin_id": "openai_ask_chat_gpt",
  "plugin_version": "1.0.0",
  "connection": "openai_connection_id",
  "input_config": {
    "model": {
      "value": "gpt-4o"
    },
    "temperature": {
      "value": 0.7
    }
  }
}
```

**Use Cases:**

* Use GPT-4o for specific reasoning tasks
* Delegate complex analysis to a specialized model
* Use vision capabilities for image understanding

***

## 🔍 **Available Plugins**

You can configure **any of the 193+ workflow nodes** as a plugin tool for your agent. Each node becomes available as a tool that your agent can execute during conversations.

### **Browse Available Nodes**

To find the right plugin for your use case:

1. [**Node Library**](/reference/nodes) - Complete reference of all 193+ workflow nodes organized by category
2. [**Node Reference**](/reference/nodes) - Browse node documentation

### **What You'll Find in Node Documentation**

Each node's documentation page includes:

* **Description**: What the node does and its capabilities
* **Input Parameters**: Required and optional fields you can configure
* **Connection Requirements**: Whether the node needs a connection to external services
* **Output Schema**: What data the node returns
* **Examples**: Usage examples and common configurations

### **Finding the Plugin ID**

The **Plugin ID** is the node's technical name shown in the node documentation. For example:

* `echo` - Echo node
* `llm` - LLM node
* `openai_ask_chat_gpt` - OpenAI ChatGPT node
* `telegram_send_message` - Telegram Send Message node
* `api_call` - API Call node

**Tip**: Use the search function in the Node Library to quickly find nodes by keyword or functionality.

***

## ⚠️ **Important Considerations**

### **Connection Requirements**

Some plugins require a **connection** to external services. To check if a specific node requires a connection:

1. **Check Node Documentation**: Navigate to the [Node Library](/reference/nodes) and find the specific node
2. **Review Requirements**: The node documentation will specify if a connection is required
3. **Configure Connection**: If required:
   * Navigate to: Project Settings → Connections
   * Add Connection: For the required service (OpenAI, Telegram, etc.)
   * Get Connection ID: Copy the connection ID from the connection settings
   * Configure Plugin: Set the `connection` field to the connection ID

**Note**: Each node's documentation page in the Node Library specifies its connection requirements. Always refer to the specific node documentation for accurate connection information.

### **Cost Considerations**

Plugin tools consume credits when executed:

* **LLM plugins**: Cost varies by model (see [Model Selection](/ai-agents/model-selection))
* **API plugins**: May incur external API costs
* **Media plugins**: Generation/processing costs apply

**Best Practice**: Use `input_config` to set cost-effective models for budget control.

### **Security Best Practices**

1. **Pre-configure sensitive parameters** using `input_config`:
   * API endpoints that should remain fixed
   * Rate limits
   * Safety parameters
   * Model selection for consistent behavior
2. **Use connections securely**:
   * Store API keys and credentials in connection settings
   * Never expose credentials in input\_config values
   * Reference connections by ID only
3. **Monitor plugin usage**:
   * Review conversation logs regularly
   * Track which plugins are being executed
   * Monitor credit consumption
   * Check for unexpected behavior

***

## 💡 **Best Practices**

### **1. Start Simple**

Begin with basic utility plugins like `echo` or `string_to_json` to understand the behavior before adding complex integrations.

### **2. Use Input Config Strategically**

Pre-configure fields that should remain constant:

* Model selection for consistent behavior
* Temperature for predictable outputs
* API endpoints that shouldn't change

### **3. Combine with System Prompt**

Guide your agent on when to use specific plugins:

```
System Prompt Example:
"You have access to the following tools:
- Use the 'llm' plugin for complex reasoning tasks
- Use the 'api_call' plugin to fetch external data
- Use the 'string_to_json' plugin when parsing JSON responses

Always explain which tool you're using and why."
```

### **4. Check Node Documentation**

Before configuring a plugin:

* Review the node's documentation in the [Node Library](/reference/nodes)
* Check connection requirements
* Understand required vs. optional input fields
* Review examples and use cases

### **5. Monitor Plugin Usage**

Review conversation logs to see:

* Which plugins are being used
* How often they're executed
* Success/failure rates
* Credit consumption

### **6. Layer Multiple Plugins**

Create specialized workflows by combining plugins:

* Fetch data with `api_call`
* Parse with `string_to_json`
* Analyze with `llm`
* Notify with `telegram_send_message`

***

## 🔄 **Updating Plugin Configuration**

You can modify plugin tool configuration at any time:

### **Add New Plugins**

Simply add new plugin configurations to the `plugins` array.

### **Modify Existing Plugins**

Update the configuration fields:

* Update `input_config` values
* Change connection IDs
* Modify plugin version if needed

### **Remove Plugins**

Remove plugin configurations from the `plugins` array to disable them.

**Note**: Changes take effect immediately for new conversations. Existing conversations may need to be refreshed.

***

## 📖 **Related Documentation**

* [**Workflow Tools Configuration**](/ai-agents/workflows) - Configure complete workflows as tools
* [**MCP Tools Configuration**](/ai-agents/mcp-tools) - Configure MCP protocol integrations
* [**Node Library**](/reference/nodes) - Complete reference of all 193+ nodes
* [**System Prompt Configuration**](/ai-agents/system-prompt) - Guide your agent's tool usage
* [**Model Selection**](/ai-agents/model-selection) - Choose the right AI model for your agent

***

## 🆘 **Troubleshooting**

### **Plugin Tool Not Appearing**

**Possible Causes:**

1. Invalid `plugin_id` - Verify the node type exists
2. Missing connection for nodes that require it
3. Configuration validation errors

**Solution**: Check the browser console for validation errors.

### **Plugin Execution Fails**

**Possible Causes:**

1. Missing required input fields
2. Invalid connection credentials
3. Node-specific errors (rate limits, API failures)

**Solution**: Review the execution logs and verify all required inputs are provided or pre-configured.

### **Agent Not Using Plugin**

**Possible Causes:**

1. System prompt doesn't guide plugin usage
2. Plugin not relevant to conversation context
3. Agent chose alternative approach

**Solution**: Update system prompt with clear guidance on when to use specific plugins.

### **Input Config Not Working**

**Possible Causes:**

1. Field name doesn't match node schema
2. Invalid value type for the field
3. Field is required but not configured

**Solution**: Verify field names match the node's input schema exactly.

***

**For detailed node-specific configuration, see:** [Node Library Reference](/reference/nodes)


# Code Execution

## 🐍 **Python Code Execution Sandbox**

Code Execution enables your AI agent to write and run Python code in a secure, isolated sandbox environment. This powerful capability allows agents to perform complex data analysis, mathematical computations, file processing, and system operations that go beyond simple text generation.

### **Prerequisites**

Before enabling code execution:

1. **PixelML Connection Required**: You must add a PixelML connection in your workspace connections
2. **Credit-Based Usage**: Code execution consumes credits based on session runtime
3. **Usage Tracking**: Charges are calculated per second of active code session time

**To set up**:

* Navigate to **Workspace Settings → Connections**
* Add a new **PixelML** connection with your API key
* Credits are automatically deducted during code execution sessions

***

## 🔧 **What Is Code Execution?**

Code Execution provides your AI agent with four specialized tools:

* **Execute Python Code**: Run Python scripts in a persistent sandbox environment
* **Upload Files to Sandbox**: Transfer files from Drive storage to the code execution environment
* **Download Files from Sandbox**: Save generated files back to Drive storage
* **Execute Shell Commands**: Run system commands for package installation and file operations

### **Combining Code Execution with Skills**

When you enable **both Code Execution and Skills** for your agent, you unlock a powerful capability: your agent can **read code examples and templates from Skills, then execute them in the sandbox**.

This combination is inspired by [**Anthropic's Claude Skills with Code Execution**](https://support.claude.com/en/articles/12512176-what-are-skills)—where skills provide procedural knowledge and code templates, while code execution enables the agent to run and adapt those templates for your specific tasks.

**How It Works:**

1. **Agent discovers relevant skill** using the skill browser tool
2. **Agent reads code templates or examples** from the skill using skill reader
3. **Agent adapts the code** to your specific requirements
4. **Agent executes the adapted code** in the sandbox using code execution
5. **Agent delivers results** or saves outputs to Drive

**Example Workflow:**

```
User: "Analyze the sales data in /data/q4_sales.csv using the data analysis patterns"

Agent Process:
1. Lists available skills → Finds "data-analysis-toolkit" skill
2. Reads skill file: "data-analysis-toolkit/examples/sales-analysis.py"
3. Adapts the template code to use "q4_sales.csv" and requested metrics
4. Uploads CSV file to sandbox
5. Executes adapted code in sandbox
6. Downloads generated charts and reports to Drive
7. Presents analysis to user
```

**Benefits of This Combination:**

* ✅ **Standardized implementations**: Agent follows proven patterns from Skills
* ✅ **Repeatable workflows**: Same skill templates work across different datasets
* ✅ **Best practices built-in**: Skills encode expert knowledge and error handling
* ✅ **Faster execution**: Agent doesn't need to write code from scratch
* ✅ **Organization consistency**: All agents use the same approved code patterns

**To Enable This Capability:**

1. Navigate to **Tab 5: Skills & Capabilities** and add relevant skills (see [Skills documentation](/ai-agents/skill))
2. Navigate to **Tab 6: Code Execution** and toggle ON
3. Ensure PixelML connection is configured in workspace settings
4. Your agent can now read Skills and execute code from them

***

## 💡 **Key Capabilities**

### **Data Analysis & Processing**

```python
# Analyze CSV data
import pandas as pd
import matplotlib.pyplot as plt

# Load and analyze data
df = pd.read_csv('sales_data.csv')
summary = df.describe()
df.groupby('region')['revenue'].sum().plot(kind='bar')
plt.savefig('revenue_by_region.png')
```

### **Mathematical Computations**

```python
# Complex calculations
import numpy as np
from scipy import stats

# Statistical analysis
data = [23, 45, 67, 89, 12, 34, 56, 78]
mean = np.mean(data)
std_dev = np.std(data)
confidence_interval = stats.t.interval(0.95, len(data)-1,
                                       loc=mean,
                                       scale=stats.sem(data))
```

### **Image Processing**

```python
# Image manipulation
from PIL import Image

# Resize and optimize images
img = Image.open('photo.jpg')
img_resized = img.resize((800, 600))
img_resized.save('photo_optimized.jpg', quality=85, optimize=True)
```

### **File Format Conversions**

```python
# Convert between formats
import json
import csv

# JSON to CSV conversion
with open('data.json', 'r') as f:
    data = json.load(f)

with open('output.csv', 'w', newline='') as f:
    writer = csv.DictWriter(f, fieldnames=data[0].keys())
    writer.writeheader()
    writer.writerows(data)
```

### **Web Data Fetching**

```python
# Download data from the internet
import urllib.request

# Fetch data directly in sandbox
url = 'https://api.example.com/data.json'
urllib.request.urlretrieve(url, 'downloaded_data.json')
```

***

## 🏗️ **How Code Execution Works**

### **Session Lifecycle Architecture**

Each agent turn (response to a user message) gets its own isolated sandbox session:

```
User sends message
    ↓
Agent starts processing
    ↓
Code Session Created (when first code tool is needed)
    ↓
Code Execution 1 (variables stored)
    ↓
Code Execution 2 (can access previous variables)
    ↓
Code Execution 3 (state persists within this turn)
    ↓
Agent completes response → Session Terminated
    ↓
Next user message → New Session Created
```

**Key Characteristics:**

* **Turn-Based Sessions**: Each agent response gets a fresh sandbox session
* **Intra-Turn Persistence**: Variables, imports, and files persist during a single agent turn
* **Session Isolation**: Each turn gets its own independent sandbox environment
* **Automatic Cleanup**: Sessions are terminated when the agent completes its response
* **State Reset**: The next agent turn starts with a completely fresh environment
* **On-Demand Creation**: Sessions are only created when the agent needs to execute code

**Important**: Unlike a persistent conversation-wide session, you **cannot** reference variables or files from previous agent responses. Each turn is completely isolated.

### **Example: Multi-Step Analysis Within a Single Turn**

```python
# All within ONE agent response (same session):

# Step 1: Load data
import pandas as pd
df = pd.read_csv('sales_data.csv')

# Step 2: Process data (df is still available in same turn)
monthly_sales = df.groupby('month')['revenue'].sum()

# Step 3: Generate visualization (both variables still accessible)
import matplotlib.pyplot as plt
monthly_sales.plot(kind='line')
plt.savefig('sales_trend.png')
```

**Important Note**: All three steps must happen in the **same agent response**. If the agent completes its response after Step 1, the next turn will have a fresh session where `df` is no longer available.

***

## 📁 **File Transfer System**

### **Upload Files to Sandbox**

Transfer files from Drive storage to the sandbox for processing:

```python
# Agent uses the upload tool
_code_upload_to_session([
    {"source": "/data/files/sales_2024.csv", "dest": "sales.csv"},
    {"source": "/data/images/logo.png", "dest": "logo.png"}
])
```

**Supported File Types:**

* **Text Files**: `.txt`, `.md`, `.py`, `.js`, `.json`, `.csv`, `.xml`, `.html`, `.css`, `.yaml`, `.sql`, etc.
* **Images**: `.jpg`, `.jpeg`, `.png`, `.gif`, `.bmp`, `.webp`, `.svg`
* **Documents**: `.pdf`
* **Media**: `.mp4`, `.mp3`, `.wav`, `.flac`, `.ogg`, `.avi`, `.mov`

### **Download Files from Sandbox**

Save generated files back to Drive storage:

```python
# Agent uses the download tool
_code_download_from_session([
    {"source": "analysis_report.pdf", "dest": "/data/reports/analysis_report.pdf"},
    {"source": "chart.png", "dest": "/data/images/chart.png", "replace": True}
])
```

**Important Notes:**

* Files in the sandbox are **temporary** and deleted when the agent turn ends
* Always download important results to Drive for persistence across turns
* Set `"replace": True` to overwrite existing files in Drive
* Default behavior prevents accidental overwrites
* Files uploaded in one turn will NOT be available in the next turn's session

***

## ⚡ **Shell Command Execution**

### **Package Installation**

Install Python packages as needed:

```bash
pip install pandas numpy matplotlib seaborn scikit-learn
```

**Important**: Packages are lost when the session ends. Since each agent turn starts a fresh session, packages must be reinstalled if needed in subsequent turns.

### **System Operations**

Perform file and system operations:

```bash
# File operations
ls -la                           # List files
mkdir output                     # Create directory
cat data.txt                     # View file contents
find . -name "*.csv"             # Find files

# Download from internet
curl -o dataset.csv https://example.com/data.csv
wget https://example.com/large_file.zip

# Archive operations
zip -r archive.zip data/
tar -czf backup.tar.gz files/
```

***

## 🔐 **Security & Isolation**

### **Sandbox Isolation Features**

```
Security Boundaries:
✅ Isolated execution environment per agent turn
✅ No access to host system
✅ Separate file system per session
✅ Network restrictions on outbound connections
✅ Resource limits (CPU, memory, execution time)
✅ Automatic session cleanup after each turn
✅ Zero state carry-over between sessions
```

### **File Type Restrictions**

Only safe file types are allowed for upload/download:

```
Allowed File Extensions:
- Text & Code: 30+ extensions
- Images: 7 formats
- Documents: PDF only
- Media: Video and audio formats

Blocked for Security:
- Executables (.exe, .dll, .so)
- Scripts (.sh, .bat) - except in sandbox
- Archives (.zip, .tar) - except within sandbox
- System files (.sys, .ini, .conf) - except within sandbox
```

### **Resource Quotas**

```
Execution Limits:
- Timeout: 30 seconds per code execution
- Memory: Limited per session
- Storage: Temporary file storage only (deleted after turn)
- Network: Controlled internet access
- Billing: Credit consumption based on session runtime
```

### **Cost & Credit Management**

```
Billing Model:
- Credits charged per second of active code session time
- Session starts when first code tool is called in a turn
- Session ends when agent completes its response
- Only active execution time is billed (not idle time)
- Usage tracked in real-time in workspace dashboard

Cost Optimization Tips:
✅ Complete operations efficiently within single turns
✅ Minimize unnecessary package installations
✅ Use efficient algorithms and vectorized operations
✅ Cache results in Drive to avoid recomputation
✅ Monitor usage patterns and optimize workflows
```

**Requirement**: A valid PixelML connection must be configured in **Workspace Settings → Connections** before code execution can be used.

***

## 📊 **Common Use Cases**

### **1. Data Analysis Agent**

```
Workflow:
1. User uploads CSV file to Drive
2. Agent uploads file to sandbox
3. Agent analyzes data with pandas
4. Agent generates visualizations with matplotlib
5. Agent downloads charts back to Drive
6. Agent presents findings to user
```

**Example Conversation:**

```
User: "Analyze the sales data in /data/files/q4_sales.csv"

Agent:
1. Uploads file to sandbox
2. Executes: pd.read_csv('q4_sales.csv').describe()
3. Identifies trends and insights
4. Creates visualization
5. Downloads chart to Drive
6. Presents analysis with visual
```

### **2. Image Processing Agent**

```
Capabilities:
- Batch resize images
- Convert formats (PNG to JPG, etc.)
- Add watermarks
- Optimize file sizes
- Generate thumbnails
- Extract EXIF data
```

### **3. Report Generation Agent**

```
Workflow:
1. Fetch data from multiple sources
2. Process and analyze in sandbox
3. Generate charts and visualizations
4. Create PDF report with reportlab
5. Download final report to Drive
```

### **4. Data Transformation Agent**

```
Transformations:
- CSV to JSON conversion
- Excel to database format
- Log file parsing
- Text extraction from PDFs
- Format standardization
- Data cleaning and validation
```

### **5. Scientific Computing Agent**

```
Capabilities:
- Statistical analysis with scipy
- Machine learning with scikit-learn
- Numerical computations with numpy
- Symbolic math with sympy
- Optimization problems
- Simulation modeling
```

### **6. Skills + Code Execution Agent**

**Scenario**: Agent with both Skills and Code Execution enabled

```
Workflow:
1. User requests a task that matches a skill pattern
2. Agent browses available skills using skill_browser
3. Agent reads relevant code template from skill using skill_reader
4. Agent adapts template code to user's specific data/requirements
5. Agent executes adapted code in sandbox
6. Agent processes results and presents findings
```

**Example Conversation:**

```
User: "Process the customer feedback CSV and generate a sentiment analysis report"

Agent:
1. Finds "sentiment-analysis" skill via skill_browser
2. Reads "sentiment-analysis/examples/csv-analysis.py" via skill_reader
3. Adapts template to user's specific CSV structure
4. Uploads customer_feedback.csv to sandbox
5. Installs required packages (pip install textblob pandas)
6. Executes adapted sentiment analysis code
7. Generates visualization and summary report
8. Downloads results to Drive: /data/reports/sentiment_report.pdf
9. Presents findings: "Analysis complete! 73% positive, 18% neutral, 9% negative"
```

**Key Advantages:**

* **Consistency**: Same proven code pattern used every time
* **Speed**: No need to design analysis from scratch
* **Quality**: Skills contain tested, optimized implementations
* **Governance**: Organization controls which code patterns are available
* **Learning**: New team members see best practices in action

***

## 🎯 **Best Practices**

### **Session Management**

```
DO:
✅ Complete all related operations within a single agent response
✅ Install required packages at the start of the turn
✅ Download important results to Drive within the same turn
✅ Use meaningful variable names for complex analyses
✅ Chain multiple code executions efficiently in one turn

DON'T:
❌ Assume variables from previous turns are available
❌ Expect packages installed in previous turns to persist
❌ Store critical data only in sandbox
❌ Run extremely long computations (>30 seconds)
❌ Rely on session state across different agent turns
❌ Expect files to persist between turns without downloading to Drive
```

### **File Management**

```
Best Practices:
1. Upload only necessary files to sandbox
2. Use clear, descriptive filenames
3. Organize files in directories when needed
4. Download results promptly after generation
5. Clean up large temporary files to save space
```

### **Error Handling**

```python
# Robust code with error handling
try:
    import pandas as pd
    df = pd.read_csv('data.csv')
    result = df.groupby('category')['value'].sum()
    print(result)
except FileNotFoundError:
    print("Error: data.csv not found. Please upload the file first.")
except Exception as e:
    print(f"Error during analysis: {e}")
```

### **Performance Optimization**

```
Optimization Tips:
1. Use vectorized operations (numpy/pandas) instead of loops
2. Filter data early to reduce processing time
3. Use appropriate data types (int32 vs int64)
4. Cache intermediate results in variables
5. Limit plot complexity for faster rendering
```

### **Skills + Code Execution Best Practices**

When using Skills with Code Execution enabled:

```
DO:
✅ Create skill templates with clear parameter placeholders
✅ Include comprehensive error handling in skill code
✅ Document expected file structures in SKILL.md
✅ Provide both basic and advanced examples in skills
✅ Test skill code templates before deploying to agents
✅ Version skill code as requirements evolve
✅ Include package requirements in skill documentation
✅ Design skills for single-turn execution when possible

DON'T:
❌ Assume skill code will work without adaptation
❌ Create overly complex skills requiring multi-turn execution
❌ Hard-code file paths in skill templates
❌ Forget to document required Python packages in skills
❌ Mix multiple unrelated code patterns in one skill
❌ Ignore session lifecycle when designing skill workflows
❌ Create skills that depend on persistent state across turns
```

**Skill Template Design Tips:**

```python
# GOOD: Parameterized skill template with clear placeholders
"""
SKILL TEMPLATE: CSV Analysis
Replace YOUR_FILE_NAME with your actual CSV file path
Replace COLUMN_NAME with the column you want to analyze
"""

import pandas as pd
import matplotlib.pyplot as plt

# Load data (adapt file path)
df = pd.read_csv('YOUR_FILE_NAME')

# Analyze (adapt column name)
summary = df['COLUMN_NAME'].describe()
print(summary)

# Visualize
df['COLUMN_NAME'].hist(bins=20)
plt.savefig('analysis_result.png')
```

***

## 🚨 **Common Issues & Solutions**

### **Package Not Found**

```
Problem: ModuleNotFoundError: No module named 'pandas'
Solution: Run shell command: pip install pandas
Note: Reinstall packages at the start of each new conversation
```

### **File Not Found**

```
Problem: FileNotFoundError: [Errno 2] No such file or directory: 'data.csv'
Solution: Use _code_upload_to_session to transfer file from Drive first
```

### **Session State Lost**

```
Problem: Variable 'df' not found in subsequent execution
Cause: Previous agent turn completed (session was terminated)
Solution: Each agent turn is isolated - reload data and reinstall packages
Tip: Save intermediate results to Drive if multi-turn processing is needed
```

### **Timeout Errors**

```
Problem: Code execution exceeded 30-second timeout
Solution:
- Break computation into smaller chunks
- Optimize algorithm efficiency
- Reduce data size being processed
- Consider pre-processing data in workflow nodes
```

### **File Download Conflicts**

```
Problem: Error: File already exists in Drive
Solution: Set "replace": True in download request, or use different filename
```

***

## 📈 **Advanced Patterns**

### **Iterative Data Processing**

```python
# Process data in chunks for large datasets
chunk_size = 10000
chunks = []

for chunk in pd.read_csv('large_file.csv', chunksize=chunk_size):
    processed = chunk.groupby('category')['value'].sum()
    chunks.append(processed)

final_result = pd.concat(chunks).groupby(level=0).sum()
```

### **Multi-Format Output**

```python
# Generate results in multiple formats
import json

# Create results dictionary
results = {
    'total_sales': 150000,
    'top_products': ['Product A', 'Product B'],
    'trend': 'increasing'
}

# Save as JSON
with open('results.json', 'w') as f:
    json.dump(results, f, indent=2)

# Save as text report
with open('results.txt', 'w') as f:
    f.write(f"Total Sales: ${results['total_sales']:,}\n")
    f.write(f"Top Products: {', '.join(results['top_products'])}\n")
    f.write(f"Trend: {results['trend']}\n")

# Save as CSV
import csv
with open('results.csv', 'w', newline='') as f:
    writer = csv.writer(f)
    writer.writerow(['Metric', 'Value'])
    for key, value in results.items():
        writer.writerow([key, str(value)])
```

### **Combining Internet Data with Drive Files**

```python
# Download data from web, combine with Drive data
import urllib.request
import pandas as pd

# Fetch external data
urllib.request.urlretrieve('https://api.example.com/data.csv', 'external_data.csv')

# Load external and Drive data
external_df = pd.read_csv('external_data.csv')
local_df = pd.read_csv('local_data.csv')  # Uploaded from Drive

# Combine and analyze
combined = pd.concat([external_df, local_df])
analysis = combined.groupby('region')['sales'].sum()
```

***

## 🎓 **Learning Resources**

### **Essential Python Libraries**

```
Data Analysis:
- pandas: Data manipulation and analysis
- numpy: Numerical computing
- scipy: Scientific computing

Visualization:
- matplotlib: Static plots and charts
- seaborn: Statistical data visualization
- plotly: Interactive visualizations

File Processing:
- PIL/Pillow: Image processing
- PyPDF2: PDF manipulation
- openpyxl: Excel file handling

Machine Learning:
- scikit-learn: ML algorithms
- statsmodels: Statistical modeling
- xgboost: Gradient boosting
```

### **Code Execution Examples**

```python
# Statistical Analysis Example
import pandas as pd
import numpy as np
from scipy import stats

data = pd.read_csv('experiment_results.csv')
group_a = data[data['group'] == 'A']['score']
group_b = data[data['group'] == 'B']['score']

# Perform t-test
t_stat, p_value = stats.ttest_ind(group_a, group_b)
print(f"T-statistic: {t_stat:.3f}")
print(f"P-value: {p_value:.3f}")
print(f"Significant: {'Yes' if p_value < 0.05 else 'No'}")
```

***

## ✅ **Code Execution Checklist**

Before deploying your agent with code execution:

### **Core Setup**

* [ ] **PixelML Connection**: PixelML connection added to workspace
* [ ] **Credit Budget**: Understand credit consumption and set appropriate limits
* [ ] **Use Case Identified**: Clear need for computational capabilities
* [ ] **File Types Verified**: Only supported file types will be processed
* [ ] **Package Requirements**: Know which packages agent will need

### **Execution Design**

* [ ] **Turn-Based Design**: Agent completes operations within single turns
* [ ] **Error Handling**: Agent handles common execution errors gracefully
* [ ] **Session Limitations**: Agent understands turn-based session lifecycle
* [ ] **File Transfer**: Upload/download workflows tested and optimized
* [ ] **Performance Tested**: Code executes within timeout limits

### **Security & Compliance**

* [ ] **Security Reviewed**: No sensitive data exposure in code
* [ ] **Output Management**: Results are properly saved to Drive within turn
* [ ] **User Communication**: Agent explains what code is doing
* [ ] **Cost Monitoring**: Usage tracking and cost optimization enabled

### **Skills Integration (if using Skills + Code Execution)**

* [ ] **Skills Enabled**: Tab 5 Skills toggle is ON
* [ ] **Relevant Skills Added**: Code-focused skills uploaded or selected
* [ ] **Skill Templates Tested**: Code examples in skills execute successfully
* [ ] **Documentation Complete**: Skills include package requirements and usage notes
* [ ] **Placeholders Clear**: Template code has obvious parameter placeholders
* [ ] **Error Handling**: Skill code includes comprehensive error handling
* [ ] **Single-Turn Compatible**: Skill workflows designed for one-turn execution
* [ ] **Agent Instructions**: System prompt guides agent to leverage skills when appropriate

***

Code execution transforms your agent from a conversational assistant into a powerful computational engine capable of data analysis, file processing, and complex problem-solving.


# Drive Storage Tools

## 📦 **Persistent Cloud Storage for Agents**

Drive Storage Tools provide agents with persistent, cloud-based file system capabilities that survive across all agent sessions and turns. Unlike temporary code execution sandboxes, Drive storage maintains files indefinitely until explicitly deleted.

### **Key Features**

* **Persistent Storage**: Files remain available across all agent sessions
* **Workspace Isolation**: Each agent has private, isolated storage within its project
* **Working Directory Scoping**: Optionally restrict operations to specific subfolders
* **Cloud-Based**: All files are stored in secure cloud storage
* **Full CRUD Operations**: Create, read, update, delete, rename, and organize files
* **URL Upload**: Download files from internet URLs directly to Drive storage
* **Binary File Support**: Handle images, PDFs, and other binary formats with download URLs

***

## ⚙️ **Configuration Options**

### **Enable Drive Storage**

Toggle to activate Drive storage tools for your agent:

* **Enabled**: Agent can create, read, modify, and organize files in Drive storage
* **Disabled**: Agent has no access to persistent file storage

### **Working Directory (Optional)**

Restrict all file operations to a specific subfolder:

**Example Configuration:**

```
Working Directory: "agent-workspace"
```

**Behavior:**

* Agent can only access files within `agent-workspace/`
* Paths are automatically scoped (e.g., `data.csv` becomes `agent-workspace/data.csv`)
* Prevents agents from accessing files outside their designated folder
* Empty path operates on the working directory itself

**Use Cases:**

* Multi-agent systems where each agent needs isolated storage
* Security isolation to prevent cross-contamination
* Organized project structure with dedicated agent folders

### **Individual Tool Permissions**

Control which specific file operations the agent can perform:

| Tool                | Description                                   | Default   |
| ------------------- | --------------------------------------------- | --------- |
| **View**            | Read file contents or list directory contents |  Enabled |
| **Create**          | Create new files or overwrite existing files  |  Enabled |
| **String Replace**  | Replace exact string matches in files         |  Enabled |
| **Insert**          | Insert content at specific line numbers       |  Enabled |
| **Delete**          | Delete files or directories                   |  Enabled |
| **Rename**          | Rename or move files/directories              |  Enabled |
| **Upload from URL** | Download files from URLs to Drive storage     |  Enabled |

**Permission Settings:**

* **Allowed**: Tool is available to the agent
* **Not Allowed**: Tool is hidden and cannot be used

**Security Considerations:**

* Disable `Delete` for read-only agents
* Disable `Create` and `String Replace` for analysis-only agents
* Disable `Upload from URL` if external downloads are not needed

***

## 🔧 **Available Drive Tools**

### **1. View (\_drive\_view)**

**Purpose:** Read file contents or list directory contents

**Parameters:**

* `file_path` (string, required): Path to file or directory
* `start_line` (integer, optional): First line to display (1-indexed, for text files)
* `end_line` (integer, optional): Last line to display (inclusive, for text files)

**Behavior:**

* **Text Files**: Returns content with line numbers (max 500 lines per view)
* **Binary Files**: Returns download URL (images, PDFs, archives, etc.)
* **Directories**: Lists all files and subdirectories, one per line
* **Empty Directories**: Returns "(empty directory)"

**Examples:**

```python
# List root directory
_drive_view(file_path="")

# Read entire text file
_drive_view(file_path="notes.txt")

# View specific line range
_drive_view(file_path="data.csv", start_line=1, end_line=100)

# Get download URL for binary file
_drive_view(file_path="report.pdf")

# List subdirectory
_drive_view(file_path="documents")
```

***

### **2. Create (\_drive\_create)**

**Purpose:** Create new files or overwrite existing files

**Parameters:**

* `file_path` (string, required): Path where file should be created
* `content` (string, required): Content to write to the file
* `replace` (boolean, optional, default: False): Allow overwriting existing files

**Behavior:**

* Automatically creates parent directories if they don't exist
* Fails if file exists and `replace=False` (prevents accidental overwrites)
* Supports any text-based content (JSON, CSV, TXT, code files, etc.)

**Examples:**

```python
# Create simple text file
_drive_create(file_path="notes.txt", content="Meeting notes here")

# Create JSON configuration
_drive_create(
    file_path="config.json",
    content='{"api_key": "value", "timeout": 30}'
)

# Create file in nested directory (auto-creates "data" folder)
_drive_create(file_path="data/results.csv", content="Name,Score\nAlice,95\nBob,87")

# Overwrite existing file
_drive_create(file_path="notes.txt", content="Updated notes", replace=True)
```

***

### **3. String Replace (\_drive\_str\_replace)**

**Purpose:** Replace an exact string match in a file

**Parameters:**

* `file_path` (string, required): Path to the file to edit
* `old_str` (string, required): Exact string to find (must appear exactly once)
* `new_str` (string, required): Replacement string

**Behavior:**

* Searches for exact match of `old_str`
* **Fails if `old_str` appears 0 times** (not found)
* **Fails if `old_str` appears 2+ times** (ambiguous match)
* Use `\n` for newlines in multi-line replacements
* Only replaces first occurrence (enforced uniqueness)

**Examples:**

```python
# Simple text replacement
_drive_str_replace(
    file_path="config.json",
    old_str='"timeout": 30',
    new_str='"timeout": 60'
)

# Multi-line replacement
_drive_str_replace(
    file_path="readme.md",
    old_str="## Old Section\nOld content here",
    new_str="## New Section\nUpdated content here"
)

# Replace variable in code
_drive_str_replace(
    file_path="script.py",
    old_str='API_KEY = "old_key"',
    new_str='API_KEY = "new_key"'
)
```

***

### **4. Insert (\_drive\_insert)**

**Purpose:** Insert content at a specific line number

**Parameters:**

* `file_path` (string, required): Path to the file to edit
* `line` (integer, required): Line number where content should be inserted (1-indexed)
* `content` (string, required): Text to insert

**Behavior:**

* Line numbers are 1-indexed (line 1 is the first line)
* Content is inserted **before** the specified line
* Use `line=1` to insert at the beginning
* Automatically adds newline if inserting in the middle of the file

**Examples:**

```python
# Insert at beginning of file
_drive_insert(file_path="script.py", line=1, content="#!/usr/bin/env python3\n")

# Insert after line 5
_drive_insert(
    file_path="data.txt",
    line=6,
    content="New line inserted here\n"
)

# Add section header
_drive_insert(
    file_path="readme.md",
    line=10,
    content="## New Section\nDescription here\n"
)
```

***

### **5. Delete (\_drive\_delete)**

**Purpose:** Delete files or directories

**Parameters:**

* `file_path` (string, required): Path to file or directory to delete

**Behavior:**

* **Files**: Deleted immediately
* **Directories**: Recursively deletes all contents
* **Permanent for agent**: Agent cannot recover deleted items

**Examples:**

```python
# Delete single file
_drive_delete(file_path="old_notes.txt")

# Delete entire directory and all contents
_drive_delete(file_path="old_data")

# Delete nested file
_drive_delete(file_path="archive/2023/report.pdf")
```

***

### **6. Rename (\_drive\_rename)**

**Purpose:** Rename files/directories or move them to different locations

**Parameters:**

* `old_path` (string, required): Current path of the file or directory
* `new_path` (string, required): New path (can be in a different directory)

**Behavior:**

* Can rename in place: `notes.txt` → `readme.txt`
* Can move to different directory: `notes.txt` → `docs/notes.txt`
* Can move and rename: `old/file.txt` → `new/renamed.txt`
* Automatically creates parent directories if needed

**Examples:**

```python
# Simple rename
_drive_rename(old_path="notes.txt", new_path="readme.txt")

# Move to different directory
_drive_rename(old_path="report.pdf", new_path="archive/report.pdf")

# Move and rename
_drive_rename(old_path="temp/data.csv", new_path="processed/clean_data.csv")

# Rename directory
_drive_rename(old_path="old_folder", new_path="new_folder")
```

***

### **7. Upload from URL (\_drive\_upload\_from\_url)**

**Purpose:** Download files from internet URLs and save to Drive storage

**Parameters:**

* `url` (string, required): HTTP/HTTPS URL to download from
* `file_path` (string, required): Where to save the downloaded file in Drive
* `replace` (boolean, optional, default: False): Allow overwriting existing files

**Behavior:**

* Supports HTTP and HTTPS URLs only
* **SSRF Prevention**: Blocks private IP addresses and localhost
* Maximum download timeout: 60 seconds
* Preserves original MIME type from download
* Fails if file exists and `replace=False`

**Examples:**

```python
# Download CSV dataset
_drive_upload_from_url(
    url="https://example.com/data.csv",
    file_path="datasets/raw_data.csv"
)

# Download image
_drive_upload_from_url(
    url="https://example.com/logo.png",
    file_path="images/logo.png"
)

# Download and overwrite
_drive_upload_from_url(
    url="https://api.example.com/latest.json",
    file_path="cache/api_response.json",
    replace=True
)

# Download PDF report
_drive_upload_from_url(
    url="https://example.com/report.pdf",
    file_path="reports/monthly.pdf"
)
```

***

## 📋 **Typical Agent Workflows**

### **Workflow 1: Data Processing Pipeline**

```
1. Download dataset from URL
   _drive_upload_from_url(url="https://...", file_path="data/raw.csv")

2. View dataset to understand structure
   _drive_view(file_path="data/raw.csv", start_line=1, end_line=10)

3. Process data (using code execution tools)
   _code_upload_to_session(uri="pmlfs://project_id/data/raw.csv")
   _code_execute_python(code="import pandas as pd; df = pd.read_csv('raw.csv')...")

4. Save processed results back to Drive
   _code_download_from_session(sandbox_path="processed.csv", uri="pmlfs://project_id/data/processed.csv")

5. Organize files
   _drive_rename(old_path="data/raw.csv", new_path="archive/raw_2024.csv")
```

### **Workflow 2: Configuration Management**

```
1. Create initial configuration
   _drive_create(file_path="config.json", content='{"setting": "value"}')

2. Read configuration
   _drive_view(file_path="config.json")

3. Update specific setting
   _drive_str_replace(
       file_path="config.json",
       old_str='"setting": "value"',
       new_str='"setting": "new_value"'
   )

4. Verify changes
   _drive_view(file_path="config.json")
```

### **Workflow 3: Report Generation**

```
1. Create report directory structure
   _drive_create(file_path="reports/2024/summary.md", content="# Monthly Report\n")

2. Add sections incrementally
   _drive_insert(file_path="reports/2024/summary.md", line=2, content="## Executive Summary\n")
   _drive_insert(file_path="reports/2024/summary.md", line=3, content="Key findings...\n")

3. Download supporting documents
   _drive_upload_from_url(url="https://...", file_path="reports/2024/chart.png")

4. Organize final structure
   _drive_rename(old_path="reports/2024/summary.md", new_path="reports/2024/final_report.md")
```

***

## 🔒 **Security & Best Practices**

### **Security Features**

1. **Path Validation**
   * No path traversal (`..`) allowed
   * No backslashes (Windows-style paths) allowed
   * No null bytes allowed
2. **Working Directory Isolation**
   * Enforces subfolder restrictions
   * Prevents access outside designated directory
   * Automatically prefixes all paths

### **Best Practices**

1. **Use Working Directories for Multi-Agent Systems**

   ```
   Agent 1: working_dir = "agent1-workspace"
   Agent 2: working_dir = "agent2-workspace"
   Agent 3: working_dir = "agent3-workspace"
   ```
2. **Organize Files in Logical Folders**

   ```
   data/raw/
   data/processed/
   configs/
   reports/
   archive/
   ```
3. **Use Descriptive File Names**

   ```
    customer_data_2024_q1.csv
    api_config_production.json
   L data.csv
   L config.json
   ```
4. **Leverage replace=False to Prevent Overwrites**

   ```python
   # Fail if file exists (safe default)
   _drive_create(file_path="important.csv", content=data, replace=False)

   # Only use replace=True when intentional
   _drive_create(file_path="cache.json", content=data, replace=True)
   ```
5. **Handle Large Files Efficiently**

   ```python
   # View large files in chunks
   _drive_view(file_path="huge.log", start_line=1, end_line=500)
   _drive_view(file_path="huge.log", start_line=501, end_line=1000)

   # Binary files use download URLs (no context overflow)
   _drive_view(file_path="large_video.mp4")  # Returns URL
   ```

***

## ⚠️ **Important Limitations**

### **Drive vs Code Execution Sandbox**

Drive storage is **completely separate** from the code execution sandbox:

| Feature           | Drive Storage                     | Code Sandbox                   |
| ----------------- | --------------------------------- | ------------------------------ |
| **Persistence**   | Permanent (until deleted)         | Temporary (deleted after turn) |
| **Access Tools**  | `_drive_*` tools                  | `_code_*` tools                |
| **File Transfer** | Requires explicit upload/download | Direct file system access      |
| **Survival**      | Survives all sessions             | Cleared every turn             |

**To Use Drive Files in Code Execution:**

```python
# 1. Upload from Drive to sandbox
_code_upload_to_session(uri="pmlfs://project_id/data.csv")

# 2. Process in sandbox
_code_execute_python(code="import pandas as pd; df = pd.read_csv('data.csv')")

# 3. Download results back to Drive
_code_download_from_session(sandbox_path="output.csv", uri="pmlfs://project_id/results.csv")
```

### **File Size Considerations**

* **View Tool**: 500-line limit per view operation (prevents context overflow)
* **Binary Files**: Not loaded into context; download URLs provided instead
* **Large Text Files**: Use `start_line` and `end_line` parameters to view in chunks

### **Path Restrictions**

* Must use forward slashes: `folder/file.txt`
* No leading slash needed: `data.csv` not `/data.csv`
* Path `.` or `""` refers to root (or working directory if configured)
* Working directory paths are automatically prefixed

***

## 💼 **Use Cases by Agent Type**

### **Data Analysis Agents**

**Recommended Configuration:**

*  Enable: View, Create, String Replace, Rename, Upload from URL
* L Disable: Delete (preserve all data)
* Working Directory: `data-analysis/`

**Workflow:** Download datasets, process data, generate reports, organize results

***

### **Content Management Agents**

**Recommended Configuration:**

*  Enable: All tools
* Working Directory: `content/`

**Workflow:** Create articles, update documentation, organize media files, archive old content

***

### **Configuration Management Agents**

**Recommended Configuration:**

*  Enable: View, String Replace, Create (with replace=True)
* L Disable: Delete, Rename (prevent structure changes)
* Working Directory: `configs/`

**Workflow:** Read configurations, update settings, maintain version history

***

### **Read-Only Audit Agents**

**Recommended Configuration:**

*  Enable: View only
* L Disable: All modification tools
* Working Directory: `audit-logs/`

**Workflow:** Read logs, analyze data, generate audit reports without modification

***

### **File Organization Agents**

**Recommended Configuration:**

*  Enable: View, Rename, Delete, Create
* L Disable: String Replace, Insert (no content editing)
* Working Directory: None (full access)

**Workflow:** Organize files, clean up old data, maintain folder structure

***

## 💡 **Tips & Tricks**

### **1. Check Before Creating**

```python
# List directory first
contents = _drive_view(file_path="reports")

# Then create with appropriate name
_drive_create(file_path="reports/report_v2.txt", content=data)
```

### **2. Incremental File Building**

```python
# Create base file
_drive_create(file_path="report.md", content="# Report\n")

# Add sections incrementally
_drive_insert(file_path="report.md", line=2, content="## Section 1\nContent...\n")
_drive_insert(file_path="report.md", line=4, content="## Section 2\nContent...\n")
```

### **3. Safe Configuration Updates**

```python
# Read current config
current = _drive_view(file_path="config.json")

# Make targeted replacement
_drive_str_replace(
    file_path="config.json",
    old_str='"debug": false',
    new_str='"debug": true'
)

# Verify change
updated = _drive_view(file_path="config.json")
```

### **4. Batch Organization**

```python
# Create organized structure
_drive_create(file_path="archive/2024/q1/summary.txt", content="Q1 Summary")
_drive_rename(old_path="old_report.pdf", new_path="archive/2024/q1/report.pdf")
_drive_delete(file_path="temp")
```

***


# Agent Triggers

> **=� Complete Trigger Configuration Guide**
>
> Configure automated triggers to activate your agents based on external events like webhooks.

## = **What Are Agent Triggers?**

Agent Triggers enable your agents to respond automatically to external events without manual intervention. When a trigger is activated, it sends a message to your agent, which then processes the request and optionally returns a response.

**Key Benefits:**

* **Automated Activation**: Agents respond to events in real-time
* **Webhook Integration**: Connect external systems via HTTP webhooks
* **Thread Management**: Continue existing conversations or start new ones
* **Secure Authentication**: Support for multiple auth methods
* **Event Logging**: Track all trigger activations and their outcomes

***

## <� **Trigger Types**

### **Webhook Triggers**

Webhook triggers allow external systems to activate your agent by sending HTTP requests to a unique URL.

**How It Works:**

1. Create a webhook trigger for your agent
2. Configure the HTTP method, authentication, and response code
3. Share the webhook URL with your external system
4. When the webhook receives a request, it sends a message to your agent
5. The agent processes the request and optionally returns a response

***

## � **Webhook Configuration**

### **HTTP Method**

Choose which HTTP method the webhook should accept:

| Method     | Best For                                        |
| ---------- | ----------------------------------------------- |
| **POST**   | Sending data to create or process (recommended) |
| **GET**    | Simple queries or status checks                 |
| **PUT**    | Updating existing resources                     |
| **DELETE** | Removing or canceling operations                |

**Default**: POST

### **Authentication**

Protect your webhook endpoint from unauthorized access:

#### **None**

* No authentication required
* � **Use only for public endpoints or testing**

#### **Basic Authentication**

* Username and password protection
* Header format: `Authorization: Basic <username>:<password>`
* **Best for**: Internal systems with simple auth requirements

**Configuration:**

* **Username**: The required username for authentication
* **Password**: The required password for authentication

#### **Bearer Token**

* Token-based authentication
* Header format: `Authorization: Bearer <token>`
* **Best for**: API integrations with token-based security

**Configuration:**

* **Token**: The secret token that must be provided in the request

### **Response Code**

Configure the HTTP status code returned by the webhook:

| Code    | Meaning               | Use Case                            |
| ------- | --------------------- | ----------------------------------- |
| **200** | OK                    | Standard success response (default) |
| **201** | Created               | Resource creation confirmation      |
| **202** | Accepted              | Request accepted for processing     |
| **204** | No Content            | Success with no response body       |
| **301** | Moved Permanently     | Permanent redirect                  |
| **302** | Found                 | Temporary redirect                  |
| **304** | Not Modified          | Cached response                     |
| **400** | Bad Request           | Client error response               |
| **401** | Unauthorized          | Authentication required             |
| **403** | Forbidden             | Access denied                       |
| **404** | Not Found             | Resource not found                  |
| **500** | Internal Server Error | Server error                        |

**Default**: 200

***

## =� **Task Configuration**

Task configuration determines what happens when the trigger is activated.

### **Task Type: Send Message to Chat**

The trigger sends a message to your agent, optionally within a specific conversation thread.

#### **Message Template**

Define the message content sent to your agent. You can use template variables to include data from the webhook request:

**Available Variables:**

* `{{event.body}}` - The request body data
* `{{event.headers}}` - The request headers
* `{{event.method}}` - The HTTP method (GET, POST, PUT, DELETE)
* `{{event.url}}` - The request URL

**Examples:**

```
New support request: {{event.body}}
```

```
User {{event.body.name}} submitted a form with email {{event.body.email}}
```

```
Webhook received from {{event.headers.user-agent}} via {{event.method}} request
```

**Constraints:**

* Minimum length: 1 character
* Maximum length: 10,000 characters

#### **Chat ID (Optional)**

Specify whether to continue an existing conversation or start a new one:

* **Not provided**: Creates a new conversation thread each time the trigger fires
* **Provided**: Sends the message to an existing thread

**Using Dynamic Chat IDs:**

You can extract the chat ID from the webhook request:

```
{{event.body.thread_id}}
```

```
{{event.body.conversation_id}}
```

**Requirements:**

* Must be a valid UUID format
* Thread must exist and belong to the same agent
* If invalid, the trigger will fail with an error

***

## = **Trigger Lifecycle**

### **Creating a Trigger**

1. Navigate to your agent's configuration
2. Open the **Triggers** tab
3. Click **Create New Trigger**
4. Configure:
   * **Name**: Descriptive identifier for the trigger
   * **Description**: Optional details about the trigger's purpose
   * **Trigger Type**: Select "Webhook"
   * **Webhook Settings**: Method, authentication, response code
   * **Task Settings**: Message template and optional chat ID
5. Save to generate the webhook URL

### **Webhook URL**

After creating a trigger, you'll receive a unique webhook URL:

```
https://api.agenticflow.com/webhooks/{unique-path-id}
```

* The `{unique-path-id}` is a UUID automatically generated for security
* Share this URL only with authorized systems
* The URL remains the same unless you delete and recreate the trigger

### **Activating/Deactivating**

* **Active**: The trigger responds to incoming requests
* **Inactive**: The trigger ignores all requests (returns 404)
* Toggle the status anytime without deleting the trigger

### **Updating a Trigger**

You can modify:

*  Name and description
*  Authentication settings
*  HTTP method
*  Response code
*  Message template
*  Chat ID configuration
*  Active/inactive status

**Note**: The webhook URL/path cannot be changed after creation.

### **Deleting a Trigger**

* Permanently removes the trigger
* The webhook URL becomes invalid immediately
* All event history is retained for audit purposes

***

## =� **Event Monitoring**

### **Trigger Events**

Every time your webhook is called, an event is recorded with:

* **Event ID**: Unique identifier for the trigger activation
* **Timestamp**: When the webhook was called
* **Request Details**:
  * HTTP method
  * Request headers
  * Request body
  * Request URL
* **Response Details**:
  * Response status code
  * Response headers
  * Response body
* **Status**: `success` or `failed`
* **Error**: Error message if the trigger failed

### **Viewing Events**

Access event history through:

* The Triggers tab in your agent configuration
* Filter by specific trigger or view all events
* Paginate through historical events

### **Event Retention**

All trigger events are stored for auditing and troubleshooting purposes.

***

## =� **Security Best Practices**

1. **Always Use Authentication**
   * Avoid "None" auth for production webhooks
   * Use Bearer tokens for API integrations
   * Use Basic auth for simple internal systems
2. **Protect Your Webhook URL**
   * Treat the webhook URL as a secret
   * Don't expose it in public repositories or documentation
   * Rotate tokens periodically by updating the trigger
3. **Validate Request Data**
   * Design your agent prompts to handle unexpected data
   * Use structured message templates to sanitize inputs
4. **Monitor Event Logs**
   * Regularly review trigger events for suspicious activity
   * Set up alerts for failed authentications
   * Investigate unexpected usage patterns
5. **Use HTTPS**
   * All webhook URLs use HTTPS by default
   * Never downgrade to HTTP for production use

***

## =� **Use Cases**

### **Customer Support Integration**

Trigger your support agent when customers submit tickets:

**Webhook Config:**

* Method: POST
* Auth: Bearer token
* Response: 202 (Accepted)

**Message Template:**

```
New support ticket from {{event.body.customer_email}}:
Subject: {{event.body.subject}}
Message: {{event.body.message}}
Priority: {{event.body.priority}}
```

### **Form Processing**

Process form submissions automatically:

**Webhook Config:**

* Method: POST
* Auth: Basic
* Response: 200 (OK)

**Message Template:**

```
Process this form submission:
{{event.body}}
```

### **Multi-System Integration**

Continue conversations across different systems:

**Webhook Config:**

* Method: POST
* Auth: Bearer token
* Response: 200
* Chat ID: `{{event.body.session_id}}`

**Message Template:**

```
{{event.body.user_message}}
```

### **Notification Processing**

Handle incoming notifications from external services:

**Webhook Config:**

* Method: POST
* Auth: Bearer token
* Response: 204 (No Content)

**Message Template:**

```
Alert received: {{event.body.alert_type}}
Details: {{event.body.details}}
Action required: {{event.body.action}}
```

***

## � **Common Issues**

### **Trigger Returns 404**

**Possible Causes:**

* Trigger is set to inactive
* Webhook URL is incorrect
* Trigger has been deleted

**Solution:**

* Verify the trigger is active
* Check the webhook URL matches exactly
* Confirm the trigger still exists

### **Authentication Failures (401)**

**Possible Causes:**

* Incorrect username/password (Basic auth)
* Invalid or expired token (Bearer auth)
* Missing Authorization header

**Solution:**

* Verify credentials match the trigger configuration
* Check the Authorization header format
* Ensure the token hasn't been rotated

### **Method Not Allowed (405)**

**Possible Cause:**

* Request method doesn't match trigger configuration

**Solution:**

* Verify you're using the correct HTTP method (GET, POST, PUT, DELETE)

### **Invalid Thread ID (400)**

**Possible Causes:**

* Chat ID template returns invalid UUID
* Referenced thread doesn't exist
* Thread belongs to different agent

**Solution:**

* Validate the chat ID format is a valid UUID
* Ensure the thread exists before triggering
* Verify thread ownership

***

## =� **Quick Reference**

### **Supported HTTP Methods**

GET, POST, PUT, DELETE

### **Authentication Types**

None, Basic, Bearer Token

### **Response Codes**

200, 201, 202, 204, 301, 302, 304, 400, 401, 403, 404, 500

### **Template Variables**

* `{{event.body}}` - Request body
* `{{event.body.field}}` - Specific body field
* `{{event.headers}}` - All headers
* `{{event.method}}` - HTTP method
* `{{event.url}}` - Request URL

### **Message Constraints**

* Min length: 1 character
* Max length: 10,000 characters

***

## = **Related Documentation**

* [**MCP Tools Integration**](/ai-agents/mcp-tools) - Connect external tools to your agents
* [**Tasks & Multi-Step Workflows**](https://github.com/PixelML/agenticflow-docs/blob/main/docs/03-agents/configuration/tasks.md) - Configure complex agent workflows
* [**API Documentation**](/developers/api) - Programmatic trigger management

***

**Need Help?** Visit the [Support & Troubleshooting](/support/12-support) section.


# Chat Features

## 💬 **Advanced Chat Experience Configuration**

The Chat Features tab is where you craft the conversational experience that users will have with your AI agent. Here, you configure interface elements, interaction patterns, multimedia capabilities, and advanced chat features that create engaging, productive, and branded conversations.

***

## 🎨 **What Are Chat Features?**

Chat features are the interface elements and interaction capabilities that define how users communicate with your AI agent:

* **Visual Interface**: Chat layout, branding, colors, and styling
* **Input Methods**: Text, voice, file uploads, quick actions
* **Response Formats**: Text, rich media, interactive elements, structured data
* **Conversation Flow**: Greeting messages, conversation starters, guided interactions
* **Multimedia Support**: Images, documents, audio, video processing
* **Interactive Elements**: Buttons, forms, carousels, menus
* **Accessibility Features**: Screen reader support, keyboard navigation, language options

***

## 🖥️ **Chat Interface Design**

### **🎨 Visual Branding & Styling**

Customize the chat interface to match your brand and user experience:

#### **Brand Integration**

```
Visual Identity Configuration:
Brand Colors:
- Primary Color: #007BFF (your main brand color)
- Secondary Color: #6C757D (supporting accent)
- Success Color: #28A745 (positive actions/messages)
- Warning Color: #FFC107 (caution/attention)
- Error Color: #DC3545 (errors/problems)

Typography:
- Font Family: "Inter", "Roboto", sans-serif
- Header Font Size: 18px (agent name, headers)
- Body Font Size: 14px (conversation messages)  
- Small Font Size: 12px (timestamps, metadata)

Logo & Avatar:
- Agent Avatar: Custom logo or AI-generated character
- User Avatar: Initials, profile picture, or generic icon
- Company Logo: Header branding (optional)
- Favicon: Browser tab icon
```

#### **Layout & User Experience**

```
Interface Configuration:
Chat Window:
- Width: 400px (desktop), 100% (mobile)
- Height: 600px (desktop), viewport height (mobile)
- Position: Bottom-right corner, full-screen, or embedded
- Resize: Draggable corners, maximize/minimize buttons

Message Display:
- Bubble Style: Rounded corners, flat design, or custom
- Spacing: Comfortable padding between messages
- Alignment: Agent left, user right (or customizable)
- Timestamps: Optional, on hover, or always visible
- Read Receipts: Delivered, read, typing indicators

Navigation:
- Chat History: Scrollable conversation history
- Search: Find specific messages or topics
- Clear Chat: Reset conversation option
- Settings: User preference controls
```

### **🌍 Internationalization & Accessibility**

#### **Multi-Language Support**

```
Language Configuration:
Supported Languages:
- English (default)
- Spanish, French, German
- Chinese (Simplified/Traditional)
- Japanese, Korean
- Arabic, Hebrew (RTL support)
- Custom language packs

Language Detection:
- Automatic browser language detection
- User language preference selection
- Dynamic language switching mid-conversation
- Fallback to default language
- Translation quality indicators

Localization Features:
- Date/time format localization
- Number and currency formatting
- Cultural context awareness
- Region-specific knowledge
- Local compliance considerations
```

#### **Accessibility Features**

```
Accessibility Compliance:
Screen Reader Support:
- ARIA labels and descriptions
- Semantic HTML structure
- Focus management and navigation
- Audio descriptions for visual content
- Screen reader optimized message formats

Keyboard Navigation:
- Tab order optimization
- Keyboard shortcuts (Ctrl+Enter to send)
- Focus indicators and navigation
- Skip links for efficiency
- Alternative input methods

Visual Accessibility:
- High contrast mode support
- Font size adjustment controls
- Color blind friendly palettes
- Zoom and magnification support
- Reduced motion preferences
```

***

## 💬 **Conversation Flow & Experience**

### **📝 Greeting & Conversation Starters**

#### **Welcome Experience**

```
First Impression Configuration:
Welcome Message:
"Hi! I'm Sarah, your AgenticFlow assistant. I can help you with:"
- Creating and managing AI agents
- Setting up workflows and automations  
- Integrating with your favorite tools
- Troubleshooting technical issues
- Optimizing your business processes

What can I help you with today?

Conversation Starters:
[🤖 Create my first agent]
[⚡ Set up a workflow]
[🔗 Connect integrations]  
[❓ Get help with an issue]
[📚 Learn about features]
```

#### **Context-Aware Greetings**

```
Dynamic Welcome Messages:
New User:
"Welcome to AgenticFlow! I'm here to help you get started. Let's begin by creating your first AI agent."

Returning User:
"Welcome back! I see you were working on the Customer Service Agent. Ready to continue where you left off?"

Business Hours:
Morning: "Good morning! Ready to automate some processes today?"
Afternoon: "Good afternoon! How can I help optimize your workflows?"
Evening: "Good evening! Let's wrap up any automation tasks."

Based on User Activity:
Active Project: "I see you're working on [Project Name]. Need help with the next steps?"
Recent Issues: "Following up on your earlier question about [Topic]. Any other concerns?"
Achievements: "Congratulations on completing your first workflow! Ready for the next challenge?"
```

### **🔄 Conversation Management**

#### **Context Preservation**

```
Conversation Memory:
Short-term Context:
- Current conversation topic and focus
- Recently mentioned entities and references
- User preferences expressed in session
- Ongoing tasks and project context
- Previous questions and clarifications

Long-term Context:
- User profile and role information
- Historical interaction patterns
- Preferred communication style
- Past projects and configurations
- Learning from previous conversations

Context Switching:
- Seamless topic transitions
- Return to previous topics
- Multi-threaded conversations
- Context summary when resuming
- Clear context boundaries
```

#### **Conversation Controls**

```
User Controls:
- Clear conversation history
- Start new conversation thread
- Bookmark important messages
- Share conversation excerpts
- Export conversation transcripts
- Report inappropriate content
- Provide feedback on responses

Agent Controls:
- Suggest conversation branches
- Offer topic changes
- Propose next actions
- Summarize long conversations
- Clarify ambiguous requests
- Confirm understanding
```

***

## 📁 **Multimedia & Rich Content**

### **📤 File Upload & Processing**

#### **Supported File Types**

```
Document Processing:
Text Documents:
- PDF: Extract text, analyze structure, answer questions
- Word (.docx): Process content, maintain formatting context
- Excel (.xlsx): Analyze data, create summaries, answer queries
- PowerPoint (.pptx): Extract content, understand presentation flow
- Text files (.txt, .md): Direct processing and analysis

Images:
- Screenshots: UI analysis, troubleshooting, guidance
- Diagrams: Process flows, architecture, workflows
- Charts/Graphs: Data interpretation, trend analysis
- Photos: Object recognition, context understanding
- Technical drawings: Specification analysis, requirements

Code Files:
- Programming languages: Code review, debugging, optimization
- Configuration files: Analysis, validation, recommendations
- Log files: Error analysis, performance insights
- Database schemas: Structure analysis, optimization suggestions
```

#### **Processing Capabilities**

```
Advanced File Analysis:
Document Intelligence:
- Extract key information and entities
- Summarize content and main points
- Answer questions about document content
- Compare multiple documents
- Generate action items from content

Image Analysis:
- OCR for text extraction from images
- Visual element identification
- UI/UX analysis and recommendations
- Technical diagram interpretation
- Quality assessment and suggestions

Data Processing:
- Spreadsheet analysis and insights
- Chart interpretation and trends
- Statistical analysis of datasets
- Data validation and quality checks
- Report generation from raw data
```

### **🎵 Voice & Audio Features**

#### **Voice Input & Output**

```
Speech Capabilities:
Voice Input:
- Speech-to-text conversion
- Multi-language speech recognition
- Accent and dialect adaptation
- Noise cancellation and filtering
- Voice command recognition
- Continuous conversation mode

Voice Output:
- Text-to-speech with natural voices
- Custom voice selection
- Speaking rate and tone adjustment
- Pronunciation customization
- Multi-language speech synthesis
- Emotional expression in speech

Voice Interface:
- Push-to-talk or continuous listening
- Voice activity detection
- Hands-free operation mode
- Voice confirmation prompts
- Audio feedback for actions
- Accessibility voice controls
```

#### **Audio File Processing**

```
Audio Analysis:
Meeting Recordings:
- Automatic transcription
- Speaker identification
- Action item extraction
- Meeting summary generation
- Key decision capture

Customer Calls:
- Sentiment analysis
- Issue identification
- Quality scoring
- Compliance checking
- Follow-up recommendations

Training Materials:
- Content extraction
- Quiz generation
- Learning assessment
- Progress tracking
- Comprehension testing
```

***

## 🎮 **Interactive Elements & Rich Responses**

### **🔘 Quick Actions & Buttons**

#### **Dynamic Response Options**

```
Interactive Response Elements:
Quick Reply Buttons:
[✅ Yes, continue]  [❌ No, stop]  [ℹ️ Tell me more]
[📝 Edit this]     [🔄 Try again]   [📋 Save for later]
[📞 Contact support] [📚 View docs]   [⚡ Run workflow]

Action Buttons:
- Execute workflow or automation
- Open external links or resources
- Download generated files or reports
- Schedule meetings or appointments
- Share content or results
- Bookmark or save information

Navigation Buttons:
- Return to main menu
- Go to specific sections
- Previous/Next in guided flows
- Jump to related topics
- Access help or documentation
- View conversation history
```

#### **Form Integration**

```
Interactive Forms:
Data Collection Forms:
- User profile information
- Project requirements gathering
- Feedback and rating collection
- Configuration preferences
- Custom field definitions

Multi-Step Wizards:
- Agent creation workflow
- Integration setup process
- Troubleshooting diagnostics
- Onboarding sequences
- Complex configuration flows

Form Validation:
- Real-time field validation
- Error messaging and guidance
- Required field enforcement
- Format checking (email, phone, etc.)
- Custom validation rules
```

### **📊 Rich Media Responses**

#### **Structured Content Display**

```
Content Presentation Formats:
Cards and Carousels:
- Feature comparison cards
- Product showcase carousels
- Tutorial step cards
- Team member profiles
- Integration option cards

Tables and Lists:
- Pricing comparison tables
- Feature availability matrices
- Configuration option lists
- Status and progress tables
- Resource and link collections

Charts and Visualizations:
- Performance metrics charts
- Usage statistics graphs
- Process flow diagrams
- Timeline visualizations
- Comparison charts
```

#### **Embedded Content**

```
Rich Media Integration:
Video Embedding:
- Tutorial and training videos
- Product demonstration videos
- Webinar recordings and highlights
- Customer testimonial videos
- Interactive video guides

Interactive Maps:
- Office and location information
- Service area coverage
- Event and meeting locations
- Geographic data visualization
- Regional feature availability

External Integrations:
- Calendar event creation
- Document collaboration tools
- Project management boards
- Social media content
- Live chat escalation
```

***

## ⚙️ **Advanced Chat Configuration**

### **🎯 Personalization & Adaptive Behavior**

#### **User Preference Learning**

```
Adaptive Chat Experience:
Communication Style:
- Formal vs. casual tone preference
- Detailed vs. concise responses
- Technical vs. business language
- Step-by-step vs. overview approach
- Preferred interaction patterns

Content Preferences:
- Favorite topics and areas of interest
- Frequently used features and tools
- Preferred response formats
- Time zone and scheduling preferences
- Notification and alert settings

Behavioral Adaptation:
- Response time expectations
- Interaction frequency patterns
- Help-seeking behaviors
- Error recovery preferences
- Success celebration styles
```

#### **Contextual Intelligence**

```
Smart Response Adaptation:
Situation Awareness:
- Time of day and business hours
- User's current project or context
- Recent activity and interaction history
- Urgency level of current request
- User's expertise level and experience

Dynamic Response Adjustment:
- Complexity level matching user expertise
- Response length based on time constraints
- Priority ordering based on user needs
- Alternative suggestions for blocked users
- Escalation triggers for complex issues
```

### **🔧 Integration & Extensibility**

#### **Third-Party Chat Platforms**

```
Platform Integration:
Supported Platforms:
- Slack: Custom bots and slash commands
- Microsoft Teams: App integration and bots
- Discord: Server bots and direct messages
- WhatsApp Business: Customer service integration
- Telegram: Bot API and webhook integration
- Facebook Messenger: Page integration

Integration Features:
- Single sign-on (SSO) authentication
- Platform-specific features utilization
- Native emoji and reaction support
- File sharing and collaboration
- Group chat and channel integration
- Platform notification preferences
```

#### **Custom Chat Widgets**

```
Embeddable Chat Solutions:
Website Integration:
- JavaScript widget for any website
- Responsive design for mobile and desktop
- Customizable appearance and branding
- SEO-friendly implementation
- Analytics and tracking integration

Application Integration:
- SDK for mobile app integration
- API for custom chat implementations
- Webhook support for real-time events
- Custom authentication integration
- Enterprise security compliance
```

***

## 📈 **Chat Analytics & Optimization**

### **📊 Conversation Analytics**

#### **User Engagement Metrics**

```
Key Performance Indicators:
Conversation Metrics:
- Average conversation length
- User satisfaction ratings
- Completion rates for guided flows
- Response time and latency
- User retention and return visits

Interaction Analysis:
- Most popular conversation topics
- Feature utilization rates
- Error rates and recovery success
- Escalation triggers and patterns
- User journey and flow analysis

Content Performance:
- Most effective response formats
- Multimedia engagement rates
- Button click-through rates
- Form completion rates
- User-generated content quality
```

#### **Optimization Insights**

```
Improvement Opportunities:
User Experience:
- Identify friction points in conversations
- Optimize response timing and flow
- Improve unclear or confusing responses
- Enhance multimedia content effectiveness
- Streamline complex interactions

Content Quality:
- Analyze user satisfaction by topic
- Identify knowledge gaps and missing content
- Optimize response accuracy and relevance
- Improve conversation starter effectiveness
- Enhance personalization algorithms

Technical Performance:
- Reduce response latency and delays
- Optimize file processing speeds
- Improve voice recognition accuracy
- Enhance mobile experience performance
- Minimize conversation interruptions
```

***

## 🎯 **Chat Experience Best Practices**

### **👥 User-Centric Design**

#### **Conversation Design Principles**

```
Design Guidelines:
Clarity and Simplicity:
- Use clear, concise language
- Avoid technical jargon unless appropriate
- Provide context for complex topics
- Offer multiple ways to ask questions
- Structure information logically

Empathy and Personality:
- Acknowledge user frustration or confusion
- Celebrate user successes and achievements
- Maintain consistent personality and tone
- Show understanding of user goals
- Provide encouragement and positive reinforcement

Efficiency and Productivity:
- Minimize steps to accomplish goals
- Provide shortcuts for common tasks
- Remember user context and preferences
- Anticipate follow-up questions
- Offer proactive suggestions
```

#### **Accessibility and Inclusion**

```
Inclusive Design:
Universal Design:
- Design for diverse abilities and needs
- Provide multiple ways to interact
- Ensure content is perceivable by all users
- Make interface elements predictable
- Assist users in avoiding and correcting mistakes

Cultural Sensitivity:
- Respect cultural communication norms
- Avoid assumptions about user background
- Provide culturally appropriate examples
- Support diverse naming conventions
- Consider regional business practices
```

***

## 🚀 **Chat Feature Deployment Checklist**

Before launching your enhanced chat experience:

* [ ] **Brand Integration Complete**: Visual styling matches brand guidelines
* [ ] **Conversation Flow Tested**: Greeting and starter messages optimized
* [ ] **Multimedia Processing Validated**: File upload and processing working correctly
* [ ] **Interactive Elements Functional**: Buttons, forms, and rich responses working
* [ ] **Accessibility Compliance**: Screen reader and keyboard navigation tested
* [ ] **Multi-Language Support**: Language detection and switching operational
* [ ] **Performance Optimized**: Chat responsiveness meets user expectations
* [ ] **Analytics Configured**: User engagement and satisfaction tracking enabled
* [ ] **Error Handling Robust**: Graceful failure handling and recovery
* [ ] **Security Measures**: File upload scanning and content validation
* [ ] **Mobile Experience**: Responsive design and touch interface optimized
* [ ] **Integration Testing**: Third-party platform connections validated

***

**For complete agent configuration and setup guidance, see the** [**Agent Configuration Overview**](/ai-agents/03-agents)

Create conversations that users love—engaging, efficient, accessible, and perfectly aligned with your brand and business objectives.


# Agent Sharing

## 🌍 **Agent Sharing & Team Collaboration**

The Sharing tab is where your AI agent becomes a collaborative asset for your entire organization. Here, you configure permissions, access controls, team sharing, public availability, and collaborative features that enable multiple users, teams, and even external stakeholders to benefit from your agent's capabilities.

***

## 🤝 **What is Agent Sharing?**

Agent sharing enables controlled access to your AI agents across different user groups and contexts:

* **Team Collaboration**: Share agents within your organization with role-based permissions
* **Department Access**: Grant access to specific departments or project teams
* **Public Sharing**: Make agents available to external users with controlled access
* **Marketplace Publishing**: Share agents with the broader AgenticFlow community
* **API Access**: Provide programmatic access to agent capabilities
* **Embedded Widgets**: Allow others to embed your agent in their websites or applications

***

## 👥 **Sharing Models & Access Levels**

### **🏢 Internal Team Sharing**

Share agents within your organization with granular permission control:

#### **Team Member Access Levels**

```
Permission Hierarchy:

Owner (Agent Creator):
✅ Full configuration access
✅ Delete agent
✅ Manage sharing settings
✅ View all analytics and logs
✅ Export agent configuration
✅ Clone and modify

Editor:
✅ Modify agent configuration
✅ Update knowledge and tools
✅ View analytics and performance
✅ Test and debug agent
❌ Delete agent
❌ Change sharing settings

Contributor:
✅ Add knowledge and content
✅ Suggest improvements
✅ View basic analytics
✅ Test agent functionality
❌ Modify core configuration
❌ Access sensitive settings

Viewer:
✅ Use agent for conversations
✅ View agent capabilities
✅ Basic usage analytics
❌ Modify any settings
❌ Access configuration
❌ View detailed analytics

Guest (Limited Access):
✅ Use agent with restrictions
✅ Limited conversation topics
❌ Access any settings
❌ View analytics
❌ Extended usage
```

#### **Department & Team Assignment**

```
Organizational Sharing:

Department-Level Access:
- Sales Team: CRM integration, lead management
- Support Team: Knowledge base, ticket creation
- Marketing Team: Content creation, campaign management
- Engineering Team: Technical documentation, code assistance
- HR Team: Employee onboarding, policy guidance

Project-Based Sharing:
- Project Alpha Team: Specialized agent for project needs
- Product Launch Team: Campaign and coordination agent
- Compliance Team: Regulatory and audit assistance
- Training Team: Educational and onboarding agents

Role-Based Permissions:
- Managers: Full team agent access with analytics
- Team Members: Agent usage with limited configuration
- Contractors: Restricted access to relevant agents only
- Executives: High-level analytics and reporting access
```

### **🌐 Public & External Sharing**

#### **Public Agent Publishing**

```
Public Availability Options:

Community Marketplace:
- Share with AgenticFlow community
- Allow others to clone and customize
- Receive ratings and feedback
- Build reputation as agent creator
- Monetization options (premium features)

Industry-Specific Sharing:
- Real estate agents for property management
- Legal professionals for document review
- Healthcare providers for patient coordination
- Educational institutions for student support
- Retail businesses for customer service

Open Source Contribution:
- Share agent configuration templates
- Contribute to community knowledge base
- Collaborative improvement and enhancement
- Credit and recognition for contributions
```

#### **Controlled External Access**

```
External Stakeholder Sharing:

Client Access:
- Custom agents for specific clients
- White-label branding options
- Limited functionality exposure
- Usage analytics and reporting
- Billing and subscription integration

Partner Integration:
- API access for partner applications
- Embedded widget for partner websites
- Shared agent capabilities across organizations
- Cross-platform functionality
- Joint analytics and reporting

Vendor Collaboration:
- Shared agents for vendor management
- Supply chain coordination agents
- Procurement and ordering assistance
- Quality control and compliance monitoring
```

***

## ⚙️ **Access Control & Security**

### **🔐 Permission Management**

#### **Granular Access Controls**

```
Fine-Grained Permissions:

Configuration Access:
- Basic Info: View/Edit agent name, description
- System Prompt: View/Edit agent instructions
- Knowledge Base: Add/Remove/Edit knowledge sources
- Tools & Integrations: Configure MCP tools and APIs
- Workflows: Create/Modify automated processes
- Sub-Agents: Manage agent delegation settings

Data Access Controls:
- Conversation History: View own/team/all conversations
- Analytics Data: Basic/Advanced/Full analytics access
- User Information: Access to user profiles and data
- Business Data: Customer records, financial information
- Sensitive Content: Confidential or restricted information

Functional Permissions:
- Agent Testing: Debug and test agent responses
- Configuration Export: Download agent settings
- API Generation: Create programmatic access keys
- Webhook Configuration: Set up external integrations
- Usage Monitoring: Track and analyze agent performance
```

#### **Security & Compliance**

```
Security Measures:

Authentication & Authorization:
- Single Sign-On (SSO) integration
- Multi-Factor Authentication (MFA) requirements
- Role-Based Access Control (RBAC)
- Time-limited access tokens
- Session management and timeout

Data Protection:
- Appropriate security controls for sensitive conversations
- Data residency and geographic controls
- Audit logging of all access and modifications
- Data retention and deletion policies
- Compliance features and controls

Network Security:
- IP whitelisting and access restrictions
- VPN requirements for sensitive agents
- API rate limiting and abuse protection
- Secure webhook endpoints
- DDoS protection and monitoring
```

### **🎯 Usage Controls & Limits**

#### **Resource Management**

```
Usage Governance:

Conversation Limits:
- Daily/Monthly message limits per user
- Concurrent conversation restrictions
- Rate limiting for high-volume usage
- Premium tier access for extended usage
- Queue management for peak periods

Feature Access:
- Basic vs. Premium feature availability
- Advanced tool access restrictions
- File upload size and type limitations
- API call quotas and rate limits
- Workflow execution limits

Content Restrictions:
- Topic and domain limitations
- Inappropriate content filtering
- Industry-specific compliance rules
- Sensitive information handling
- Geographic content restrictions
```

#### **Monitoring & Analytics**

```
Usage Tracking:

Individual User Analytics:
- Conversation frequency and duration
- Feature utilization patterns
- Success rates and satisfaction scores
- Error rates and issue patterns
- Resource consumption metrics

Team Performance:
- Aggregate usage statistics
- Team productivity improvements
- Collaboration effectiveness
- Knowledge sharing patterns
- Training and adoption metrics

Business Impact:
- ROI measurement and cost savings
- Process improvement identification
- User satisfaction and engagement
- Competitive advantage metrics
- Strategic value assessment
```

***

## 🚀 **Advanced Sharing Features**

### **🔗 Integration & API Access**

#### **Programmatic Access**

```
API Integration Options:

RESTful API Access:
- Full agent conversation capabilities
- Configuration management endpoints
- Analytics and reporting APIs
- Webhook configuration and management
- User and permission management

SDK Integration:
- JavaScript/TypeScript SDK for web applications
- Python SDK for data science and automation
- Mobile SDKs for iOS and Android
- Custom SDK development for specific platforms

Webhook Support:
- Real-time conversation events
- Agent performance notifications
- User activity and engagement alerts
- System status and health monitoring
- Custom business event triggers
```

#### **Third-Party Integrations**

```
Platform Connections:

Communication Platforms:
- Slack bot integration with team permissions
- Microsoft Teams app with enterprise controls
- Discord bot with server-specific access
- WhatsApp Business API integration
- Custom chat widget for websites

Business Applications:
- CRM system integration (Salesforce, HubSpot)
- Project management tools (Asana, Jira, Monday.com)
- Documentation platforms (Confluence, Notion)
- Help desk systems (Zendesk, Freshdesk)
- E-commerce platforms (Shopify, WooCommerce)

Development Tools:
- GitHub integration for code assistance
- CI/CD pipeline integration
- Monitoring and alerting systems
- Documentation generation tools
- Testing and quality assurance platforms
```

### **🎨 Customization & White-Labeling**

#### **Brand Customization**

```
Visual Identity Options:

Custom Branding:
- Company logo and brand colors
- Custom chat interface styling
- Personalized agent avatars and names
- Brand-consistent messaging and tone
- Custom domain and URL structure

Client-Specific Customization:
- Per-client branding and styling
- Customized conversation flows
- Industry-specific terminology and knowledge
- Regional and cultural adaptations
- Compliance with client brand guidelines

White-Label Solutions:
- Complete removal of AgenticFlow branding
- Custom platform naming and identity
- Reseller and partner program access
- Revenue sharing and monetization options
- Technical support and documentation
```

#### **Marketplace & Monetization**

```
Agent Marketplace Features:

Agent Publishing:
- Public agent directory listing
- Category and tag-based organization
- Rating and review system
- Usage statistics and popularity metrics
- Featured agent promotional opportunities

Monetization Options:
- Free agents with premium features
- Subscription-based access models
- Pay-per-use pricing structures
- Enterprise licensing options
- Revenue sharing with AgenticFlow

Community Features:
- Agent creator profiles and portfolios
- User feedback and improvement suggestions
- Collaborative agent development
- Best practice sharing and tutorials
- Agent template and component library
```

***

## 📊 **Collaboration Analytics & Management**

### **📈 Sharing Performance Metrics**

#### **Usage Analytics**

```
Key Performance Indicators:

Adoption Metrics:
- Number of active users per agent
- Usage growth trends over time
- Feature adoption rates across teams
- User engagement and retention
- Geographic usage distribution

Collaboration Effectiveness:
- Team productivity improvements
- Knowledge sharing success rates
- Cross-departmental usage patterns
- Collaborative problem-solving metrics
- Training and onboarding effectiveness

Business Impact:
- Cost savings through agent usage
- Time savings and efficiency gains
- Customer satisfaction improvements
- Process automation success rates
- ROI measurement and tracking
```

#### **Quality & Satisfaction Monitoring**

```
Performance Tracking:

User Satisfaction:
- Agent helpfulness ratings
- Response quality assessments
- User experience feedback
- Feature request and improvement suggestions
- Overall satisfaction scores

Content Quality:
- Response accuracy and relevance
- Knowledge base effectiveness
- Tool integration success rates
- Error rates and resolution times
- Continuous improvement metrics

Collaboration Success:
- Team communication improvements
- Decision-making speed increases
- Knowledge transfer effectiveness
- Cross-functional project success
- Organizational learning acceleration
```

### **🔧 Management & Optimization**

#### **Sharing Strategy Optimization**

```
Continuous Improvement:

Access Pattern Analysis:
- Identify underutilized agents
- Optimize permission structures
- Streamline access request processes
- Improve user onboarding flows
- Enhance collaboration features

Performance Optimization:
- Scale agent capacity based on demand
- Optimize response times for shared usage
- Improve resource allocation efficiency
- Enhance security without limiting usability
- Balance functionality with simplicity

Strategic Planning:
- Expand sharing to new teams and departments
- Develop specialized agents for specific use cases
- Create agent template libraries
- Build center of excellence for agent development
- Establish governance and best practices
```

***

## 🎯 **Sharing Best Practices**

### **🏗️ Implementation Strategy**

#### **Phased Rollout Approach**

```
Deployment Phases:

Phase 1: Internal Team Sharing (Weeks 1-2)
- Start with core team and early adopters
- Configure basic permissions and access controls
- Establish usage guidelines and best practices
- Collect feedback and iterate on configuration

Phase 2: Department Expansion (Weeks 3-4)
- Roll out to additional departments
- Create department-specific agents and customizations
- Train department leads and power users
- Monitor usage patterns and performance

Phase 3: Organization-Wide Deployment (Weeks 5-6)
- Full organizational access with proper governance
- Advanced features and integrations
- Comprehensive training and support materials
- Performance monitoring and optimization

Phase 4: External Sharing (Weeks 7-8)
- Client and partner access where appropriate
- Public sharing and marketplace participation
- API and integration capabilities
- Advanced analytics and reporting
```

#### **Governance Framework**

```
Management Structure:

Agent Governance Council:
- Executive sponsor and strategic oversight
- Technical lead for architecture and security
- Business stakeholders for requirements
- IT security for compliance and risk management
- User representatives for feedback and adoption

Policies & Procedures:
- Agent creation and approval processes
- Sharing request and authorization workflows
- Security and compliance requirements
- Usage monitoring and enforcement
- Incident response and escalation procedures

Best Practices:
- Agent naming and categorization standards
- Documentation requirements and templates
- Testing and quality assurance procedures
- Training materials and user support
- Performance monitoring and optimization guidelines
```

***

## 📈 **Sharing ROI & Business Impact**

### **💰 Value Creation & Measurement**

```
Business Benefits:

Cost Savings:
- Reduced training and onboarding time
- Decreased support ticket volumes
- Improved process efficiency and automation
- Lower operational overhead
- Reduced need for specialized consultants

Revenue Generation:
- Faster customer response times
- Improved customer satisfaction and retention
- New service offerings and capabilities
- Partner collaboration opportunities
- Marketplace revenue and monetization

Strategic Advantages:
- Organizational knowledge sharing and retention
- Cross-functional collaboration improvement
- Innovation and competitive differentiation
- Scalable expertise and capability deployment
- Cultural transformation toward AI adoption

Risk Mitigation:
- Consistent information and process execution
- Reduced human error and oversight
- Improved compliance and governance
- Enhanced security through controlled access
- Business continuity and knowledge preservation
```

***

## 🎯 **Agent Sharing Deployment Checklist**

Before implementing agent sharing capabilities:

* [ ] **Sharing Strategy Defined**: Clear objectives and target user groups identified
* [ ] **Permission Structure Designed**: Granular access controls and roles configured
* [ ] **Security Measures Implemented**: Authentication, encryption, and audit logging enabled
* [ ] **Usage Policies Established**: Clear guidelines for appropriate use and limitations
* [ ] **Training Materials Created**: User guides and onboarding resources prepared
* [ ] **Analytics and Monitoring Setup**: Usage tracking and performance measurement enabled
* [ ] **Governance Framework Established**: Approval processes and oversight procedures
* [ ] **Technical Integration Tested**: API access, webhooks, and third-party connections validated
* [ ] **User Support Processes**: Help desk procedures and escalation paths defined
* [ ] **Performance Baselines Established**: Current metrics for improvement measurement
* [ ] **Rollback Procedures Ready**: Ability to restrict or revoke access if issues arise
* [ ] **Legal and Compliance Review**: Data protection and regulatory requirements met

***

Transform your AI agent from a personal assistant into a collaborative organizational asset—enabling teams to share knowledge, automate processes, and achieve better results together.


# Sub-Agents

## 🤖 **Multi-Agent Architecture & Delegation**

The Sub-Agents tab transforms your AI agent from a single assistant into a coordinated team of specialized experts. Here, you configure hierarchical agent relationships, delegation patterns, and collaborative workflows that enable sophisticated multi-agent problem-solving.

***

## 🎯 **What Are Sub-Agents?**

Sub-agents are specialized AI assistants that your primary agent can delegate specific tasks to, creating a hierarchical system where:

* **Primary Agent**: Acts as orchestrator and user interface
* **Sub-Agents**: Handle specialized functions, domains, or complex sub-tasks
* **Delegation**: Intelligent routing of tasks to most appropriate sub-agent
* **Coordination**: Results aggregation and workflow management
* **Escalation**: Complex cases handled by multiple agents working together

***

## 🏗️ **Sub-Agent Architecture Patterns**

### **🎭 Specialization by Domain**

Different sub-agents handle distinct subject areas:

#### **Example: Customer Service Agent Hierarchy**

```
Primary Agent: "Customer Support Assistant"
├── Technical Support Sub-Agent
│   ├── Handles: Hardware issues, software bugs, integrations
│   ├── Knowledge: Technical documentation, troubleshooting guides
│   └── Tools: Ticketing system, diagnostic tools, remote access
│
├── Billing & Payments Sub-Agent
│   ├── Handles: Invoices, payment issues, subscription changes
│   ├── Knowledge: Billing policies, payment processing, pricing
│   └── Tools: Payment gateway, billing system, accounting software
│
├── Account Management Sub-Agent
│   ├── Handles: Account setup, user management, permissions
│   ├── Knowledge: Account policies, user roles, compliance
│   └── Tools: User management system, audit logs, access controls
│
└── Sales Support Sub-Agent
    ├── Handles: Upselling, renewals, product recommendations
    ├── Knowledge: Product catalog, pricing, competitor analysis
    └── Tools: CRM, sales tracking, proposal generation
```

### **🔄 Process-Based Delegation**

Sub-agents organized around business processes:

#### **Example: Sales Process Agent Team**

```
Primary Agent: "Sales Assistant"
├── Lead Qualification Sub-Agent
│   ├── Handles: Initial prospect assessment, scoring
│   ├── Process: BANT qualification, needs assessment
│   └── Output: Qualified leads with priority scores
│
├── Proposal Generation Sub-Agent  
│   ├── Handles: Custom proposals, pricing calculations
│   ├── Process: Requirements analysis, solution design
│   └── Output: Tailored proposals with ROI analysis
│
├── Demo Coordination Sub-Agent
│   ├── Handles: Demo scheduling, preparation, follow-up
│   ├── Process: Calendar management, demo customization
│   └── Output: Scheduled demos with personalized content
│
└── Contract Negotiation Sub-Agent
    ├── Handles: Terms discussion, legal review coordination
    ├── Process: Contract preparation, stakeholder alignment
    └── Output: Finalized agreements ready for signature
```

### **⚡ Capability-Based Distribution**

Sub-agents with specialized functional abilities:

#### **Example: Content Creation Agent Network**

```
Primary Agent: "Content Manager"
├── Research Sub-Agent
│   ├── Capability: Data gathering, fact-checking, analysis
│   ├── Sources: Web research, database queries, API calls
│   └── Specialty: Market research, competitive analysis
│
├── Writing Sub-Agent
│   ├── Capability: Content creation, editing, optimization
│   ├── Styles: Blog posts, whitepapers, social media
│   └── Specialty: SEO optimization, brand voice consistency
│
├── Visual Design Sub-Agent
│   ├── Capability: Image generation, layout design, graphics
│   ├── Tools: AI image generation, template libraries
│   └── Specialty: Brand compliance, accessibility standards
│
└── Distribution Sub-Agent
    ├── Capability: Multi-channel publishing, scheduling
    ├── Platforms: Social media, email, website, blog
    └── Specialty: Timing optimization, audience targeting
```

***

## ⚙️ **Sub-Agent Configuration**

### **How to Configure Sub-Agents in Tab 7**

In the Visual Agent Builder, Tab 7 allows you to add other agents as "tools" that your primary agent can delegate tasks to. This creates a hierarchical multi-agent system where specialized sub-agents handle specific domains.

#### **Step-by-Step Configuration**

**1. Navigate to Tab 7: Sub-Agents & Delegation**

* Open your primary agent in the Visual Agent Builder
* Click on Tab 7 in the configuration interface
* This is where you'll add and configure all sub-agents

**2. Add a Sub-Agent**

* Click "Add Sub-Agent" or similar action button
* Select an existing agent from your workspace to use as a sub-agent
* Each sub-agent must be a fully configured agent in your workspace

**3. Configure Sub-Agent Tool Settings**

For each sub-agent, you configure:

| Setting                 | Description                                          | Configuration Details                                                |
| ----------------------- | ---------------------------------------------------- | -------------------------------------------------------------------- |
| **Sub-Agent Selection** | Choose which agent to use                            | Select from your existing agents in the workspace                    |
| **Description**         | How primary agent should use this sub-agent          | Describe the sub-agent's role, expertise, and when to delegate to it |
| **Metadata**            | Visual positioning (for multi-agent system diagrams) | Optional: Position coordinates for visual representation             |

**4. Write Effective Sub-Agent Descriptions**

The description field is critical - it tells your primary agent **when** and **how** to use each sub-agent:

**Good Description Examples:**

```
Technical Support Specialist
Use this agent when users report technical issues, bugs, API errors,
integration problems, or need help with system configuration.
This agent has access to technical documentation and troubleshooting guides.
```

```
Billing & Payments Expert
Delegate to this agent for all billing inquiries, payment issues,
invoice questions, subscription changes, or pricing discussions.
This agent can access billing systems and process payment-related requests.
```

```
Content Writer
Use this agent to create blog posts, marketing copy, social media content,
or any written materials. This agent specializes in brand voice consistency
and SEO optimization.
```

**Poor Description Examples:**

```
❌ "Technical agent" (too vague)
❌ "Use for support" (doesn't specify what kind)
❌ "Billing" (no context on when to use)
```

### **Creating Sub-Agents (Prerequisites)**

Before adding sub-agents to your primary agent, you must first create them as standalone agents:

#### **Sub-Agent Definition Example**

```
Agent Name: "Technical Support Specialist"
Purpose: Handle technical troubleshooting and integration issues
Specialization: Hardware problems, software bugs, API integrations
Expertise Level: Expert in product technical specifications

Model Configuration (Tab 2):
- Primary Model: GPT-4.1 (for complex technical reasoning)
- Fallback Model: Claude 4.5 Sonnet (for detailed explanations)
- Temperature: 0.3 (precise, consistent responses)
- Max Tokens: 2000 (detailed technical guidance)

System Instructions (Tab 3):
- Role definition as technical support specialist
- Troubleshooting methodology and escalation procedures
- Response format requirements

Knowledge Sources (Tab 4):
- Technical documentation repository
- Known issues database
- Integration guides and API specifications
- Hardware compatibility matrices
- Software troubleshooting workflows

Tools (Tab 5):
- Ticketing system integration
- Diagnostic tools
- Database query tools
- Documentation search
```

#### **Delegation Rules Configuration**

```
Delegation Triggers:
Keywords: ["technical", "bug", "error", "integration", "API", "setup"]
Intent Classification: Technical support request
Complexity Threshold: Technical questions requiring specialized knowledge
User Indicators: Mentions of specific technologies or error messages

Example Rules:
IF user_message.contains("API error") OR user_message.contains("integration")
   THEN delegate_to("Technical Support Specialist")
   
IF intent == "technical_troubleshooting" AND confidence > 0.8
   THEN delegate_to("Technical Support Specialist")
   
IF user_mentions_product_features AND query_complexity == "high"
   THEN delegate_to("Technical Support Specialist")
```

### **How Sub-Agent Delegation Works**

#### **Runtime Execution Flow**

When your primary agent decides to use a sub-agent, here's what happens:

**1. Tool Invocation**

```
Primary Agent Decision:
- Analyzes user request
- Determines appropriate sub-agent based on description
- Calls sub-agent as a tool with: run_agent_{sub_agent_name}(message, thread_id)
```

**2. Message Parameters**

```
message: The task or question to delegate to the sub-agent
thread_id: (Optional) UUID to continue an existing conversation thread
          - If provided: Sub-agent continues previous conversation
          - If omitted: Creates new conversation thread
```

**3. Sub-Agent Execution**

```
Sub-Agent Processing:
1. Receives delegated message
2. Processes using its own configuration:
   - AI model settings
   - System instructions
   - Knowledge bases
   - Available tools
3. Generates response
4. Returns results to primary agent
```

**4. Response Format**

```
Sub-Agent Returns:
{
  "final_message": "The sub-agent's complete response",
  "thread_id": "uuid-of-conversation-thread"
}

Primary Agent Receives:
- Full response from sub-agent
- Thread ID for potential follow-up
- Can continue conversation or return results to user
```

#### **Conversation Thread Management**

**Single-Turn Delegation:**

```
User → Primary Agent → Sub-Agent (new thread) → Primary Agent → User
- Each delegation creates a new conversation
- Best for independent, self-contained tasks
```

**Multi-Turn Delegation:**

```
User → Primary Agent → Sub-Agent (thread: abc-123) → Primary Agent → User
User → Primary Agent → Sub-Agent (thread: abc-123) → Primary Agent → User
- Primary agent maintains thread_id
- Sub-agent continues previous conversation
- Best for complex, multi-step problem solving
```

#### **Handoff Protocols**

```
Seamless Task Transfer:
1. Primary agent identifies delegation need based on sub-agent descriptions
2. Primary agent calls sub-agent tool with message and optional thread_id
3. Sub-agent receives message and processes with full capabilities
4. Sub-agent streams real-time progress updates
5. Sub-agent returns final response
6. Primary agent receives results
7. Primary agent synthesizes response for user or delegates further

Example Handoff:
User: "I'm getting a 401 error when calling your API"
Primary Agent: [Analyzes request, identifies technical nature]
Primary Agent: [Calls run_agent_technical_support("User getting 401 error on API")]
Technical Sub-Agent: [Processes using technical knowledge and tools]
Technical Sub-Agent: [Returns detailed troubleshooting steps]
Primary Agent: "I've consulted our technical specialist. Here's the solution..."
```

#### **Multi-Agent Collaboration**

```
Collaborative Problem Solving:
- Multiple sub-agents work on different aspects
- Real-time information sharing between agents
- Coordinated response compilation
- Conflict resolution and consensus building
- Quality assurance and consistency checking

Example Collaboration:
User Request: "Help me choose and implement a payment solution"
→ Research Sub-Agent: Analyzes payment options and requirements
→ Technical Sub-Agent: Evaluates integration complexity
→ Legal Sub-Agent: Reviews compliance and regulatory requirements
→ Primary Agent: Synthesizes recommendations into actionable plan
```

### **Context Management**

#### **Shared Context Pool**

```
Information Sharing:
- User profile and preferences
- Conversation history and context
- Previous sub-agent interactions
- Ongoing projects and tasks
- Learned preferences and patterns

Context Categories:
User Information:
- Name, role, company, contact preferences
- Technical skill level, experience
- Previous interactions and resolutions
- Preferred communication style

Business Context:
- Current projects and objectives
- Budget constraints and timelines
- Stakeholder relationships
- Decision-making processes

Technical Context:
- System configurations and setups
- Integration requirements
- Performance considerations
- Security and compliance needs
```

#### **Privacy & Access Control**

```
Context Access Management:
- Role-based information access
- Sensitive data protection
- Audit logging of information sharing
- User consent for data sharing
- Automatic data cleanup and retention

Example Access Controls:
Financial Sub-Agent: Access to billing, payments, pricing
Technical Sub-Agent: Access to system configs, integrations
Sales Sub-Agent: Access to opportunities, requirements, contacts
Support Sub-Agent: Access to tickets, issues, resolutions
```

***

## 🚀 **Advanced Sub-Agent Features**

### **Dynamic Sub-Agent Creation**

Automatically spawn specialized agents for complex scenarios:

```
Dynamic Agent Scenarios:
Complex Multi-Step Projects:
- Create project-specific coordination agent
- Spawn specialist agents for each work stream
- Establish temporary communication channels
- Coordinate deliverables and timelines

Crisis Response Situations:
- Incident commander agent for coordination
- Specialist agents for different impact areas
- Real-time status monitoring and reporting
- Stakeholder communication management

Learning & Adaptation:
- Create learning agents for new domains
- Develop expertise through interaction
- Share learnings across agent network
- Evolve capabilities over time
```

### **Sub-Agent Performance Optimization**

#### **Load Balancing & Scaling**

```
Resource Management:
- Distribute workload across sub-agents
- Scale sub-agent capacity based on demand
- Queue management for high-volume periods
- Priority routing for urgent requests

Performance Monitoring:
- Response time tracking per sub-agent
- Success rate and user satisfaction metrics
- Resource utilization and efficiency
- Bottleneck identification and resolution
```

#### **Continuous Learning & Improvement**

```
Adaptive Sub-Agent Network:
- Performance analytics and optimization
- User feedback integration
- Knowledge base updates from interactions
- Best practice sharing across agents
- Automated improvement recommendations

Quality Assurance:
- Cross-agent validation and fact-checking
- Consistency monitoring across responses
- Brand voice and tone compliance
- Accuracy verification and correction
```

### **Specialized Sub-Agent Types**

#### **Research & Analysis Agents**

```
Research Agent Capabilities:
- Web research and data gathering
- Competitive analysis and benchmarking  
- Market research and trend analysis
- Technical research and evaluation
- Data synthesis and insight generation

Configuration Example:
Name: "Market Research Specialist"
Tools: Web search, industry databases, analytics platforms
Knowledge: Market reports, competitor profiles, trend data
Output: Research reports, competitive analyses, recommendations
```

#### **Creative & Content Agents**

```
Creative Agent Capabilities:
- Content ideation and brainstorming
- Writing and editing in multiple styles
- Visual content creation and design
- Brand voice consistency maintenance
- Multi-channel content adaptation

Configuration Example:
Name: "Brand Content Creator"
Tools: AI writing tools, image generation, template libraries
Knowledge: Brand guidelines, content strategies, audience profiles
Output: Blog posts, social content, marketing materials
```

#### **Technical Implementation Agents**

```
Technical Agent Capabilities:
- Code review and technical validation
- Architecture design and recommendations
- Integration planning and execution
- Performance optimization guidance
- Security and compliance verification

Configuration Example:
Name: "Integration Architect"
Tools: API testing tools, documentation systems, monitoring
Knowledge: Technical specifications, best practices, security standards
Output: Integration plans, technical documentation, validation reports
```

***

## 📊 **Sub-Agent Analytics & Management**

### **Performance Metrics**

#### **Individual Sub-Agent Metrics**

```
Agent Performance Tracking:
- Task completion rates and accuracy
- Average response times
- User satisfaction scores
- Knowledge utilization effectiveness
- Error rates and quality issues

Success Indicators:
- First-contact resolution rates
- User engagement and follow-through
- Knowledge gap identification
- Learning and improvement trends
- Resource efficiency metrics
```

#### **Network-Level Analytics**

```
Multi-Agent System Metrics:
- Overall system throughput and capacity
- Inter-agent collaboration effectiveness
- Context sharing accuracy and speed
- Escalation patterns and success rates
- Network resilience and fault tolerance

Optimization Opportunities:
- Delegation decision accuracy
- Sub-agent specialization effectiveness
- Communication overhead reduction
- Resource allocation optimization
- User experience consistency
```

### **Sub-Agent Lifecycle Management**

#### **Creation & Deployment**

```
Sub-Agent Lifecycle:
1. Needs Assessment: Identify specialization requirements
2. Agent Design: Define role, capabilities, knowledge sources
3. Configuration: Set up models, tools, access controls
4. Training: Load knowledge, configure delegation rules
5. Testing: Validate performance with test scenarios
6. Deployment: Integrate with primary agent network
7. Monitoring: Track performance and user feedback
8. Optimization: Continuous improvement and updates
```

#### **Maintenance & Evolution**

```
Ongoing Management:
- Regular knowledge base updates
- Performance monitoring and tuning
- User feedback integration
- Capability expansion and enhancement
- Deprecation of obsolete agents

Version Control:
- Agent configuration versioning
- Rollback capabilities for issues
- A/B testing for improvements
- Change impact assessment
- Documentation and audit trails
```

***

## 🎯 **Sub-Agent Best Practices**

### **Design Principles**

#### **Clear Specialization**

```
Effective Specialization Strategy:
- Define distinct, non-overlapping domains
- Establish clear expertise boundaries
- Avoid capability redundancy across agents
- Create fallback and escalation paths
- Document agent roles and responsibilities
```

#### **Seamless User Experience**

```
User Experience Guidelines:
- Transparent agent transitions
- Consistent brand voice across all agents
- Context preservation during handoffs
- Clear communication about specialist involvement
- Unified interaction interface
```

### **Implementation Strategy**

#### **Gradual Rollout Approach**

```
Implementation Phases:
Phase 1: Single specialized sub-agent (high-impact domain)
Phase 2: Core sub-agent team (3-4 specialists)
Phase 3: Advanced delegation and collaboration features
Phase 4: Dynamic agent creation and optimization
Phase 5: Full multi-agent ecosystem with learning

Success Criteria:
- User satisfaction improvements
- Response accuracy increases
- Task completion rate improvements  
- Reduced escalation to human agents
- Positive ROI demonstration
```

#### **Change Management**

```
Organizational Adoption:
- Train users on multi-agent capabilities
- Set expectations for specialist interactions
- Provide feedback mechanisms for improvement
- Monitor and address user concerns
- Celebrate success stories and improvements

Staff Training:
- Understanding of agent specializations
- Escalation procedures for complex cases
- Monitoring and oversight responsibilities
- Quality assurance and feedback processes
- Continuous improvement participation
```

***

## 📈 **Sub-Agent ROI & Business Impact**

### **Value Creation Metrics**

```
Business Value Indicators:
- Expertise Access: Specialized knowledge available through automated routing
- Consistency: Standardized expert-level responses
- Scalability: Handle multiple complex inquiries simultaneously
- Cost Efficiency: Reduce need for human specialists
- Speed: Faster resolution through appropriate routing
- Quality: Higher accuracy through specialization

Measurement Approaches:
- Time savings through efficient delegation
- Improved first-contact resolution rates
- Reduced human expert intervention needs
- Higher customer satisfaction scores
- Increased throughput capacity
- Better knowledge retention and application
```

### **Strategic Advantages**

```
Competitive Benefits:
- Always-available expertise across all domains
- Consistent quality regardless of volume
- Rapid scaling of specialized capabilities
- Continuous learning and improvement
- Cost-effective expert knowledge deployment
- Enhanced customer experience through specialization
```

***

## 🎯 **Sub-Agent Deployment Checklist**

Before implementing sub-agent architecture:

* [ ] **Specialization Strategy Defined**: Clear domain boundaries and expertise areas
* [ ] **Delegation Rules Configured**: Accurate routing logic and trigger conditions
* [ ] **Context Sharing Setup**: Secure information flow between agents
* [ ] **Performance Monitoring**: Analytics and alerting systems in place
* [ ] **User Experience Tested**: Seamless handoffs and consistent quality
* [ ] **Access Controls Validated**: Proper security and privacy protections
* [ ] **Escalation Paths Clear**: Fallback procedures for complex scenarios
* [ ] **Knowledge Sources Integrated**: Comprehensive information access
* [ ] **Quality Assurance Processes**: Consistency and accuracy verification
* [ ] **Documentation Complete**: Agent roles, capabilities, and management guides
* [ ] **Training Materials Ready**: User and administrator guidance
* [ ] **Rollback Plan Available**: Ability to revert if issues arise

***

## 🛠️ **Complete Configuration Example**

### **Scenario: Customer Support Multi-Agent System**

Here's a complete example showing how to configure a customer support agent with three specialized sub-agents:

#### **Step 1: Create Sub-Agents**

**Sub-Agent 1: Technical Support Specialist**

```
Agent Name: Technical Support Specialist
Tab 2 (Model): Claude 4.5 Sonnet, Temperature: 0.3
Tab 3 (Instructions): "You are a technical support expert specializing in
                       troubleshooting software issues, API integrations,
                       and system configurations."
Tab 4 (Knowledge): Technical docs, API documentation, troubleshooting guides
Tab 5 (Tools): Database query tool, log analysis workflow
```

**Sub-Agent 2: Billing Specialist**

```
Agent Name: Billing Specialist
Tab 2 (Model): GPT-4.1, Temperature: 0.2
Tab 3 (Instructions): "You are a billing expert who handles payment inquiries,
                       subscription changes, and invoice questions."
Tab 4 (Knowledge): Billing policies, pricing documentation, payment FAQs
Tab 5 (Tools): Billing system integration, payment gateway workflow
```

**Sub-Agent 3: Product Expert**

```
Agent Name: Product Expert
Tab 2 (Model): Claude 4.5 Opus, Temperature: 0.4
Tab 3 (Instructions): "You are a product specialist who explains features,
                       provides usage guidance, and recommends solutions."
Tab 4 (Knowledge): Product documentation, feature guides, use case examples
Tab 5 (Tools): Product demo workflow, feature documentation search
```

#### **Step 2: Configure Primary Agent**

**Primary Agent: Customer Support Coordinator**

```
Agent Name: Customer Support Coordinator
Tab 2 (Model): GPT-4.1, Temperature: 0.4

Tab 3 (Instructions):
"You are a customer support coordinator who helps users with their inquiries.
You have access to three specialized agents:
- Technical Support Specialist for technical issues
- Billing Specialist for payment and subscription matters
- Product Expert for feature questions and usage guidance

Analyze each user request and delegate to the appropriate specialist when needed.
You can also handle general questions directly."

Tab 7 (Sub-Agents):
```

#### **Step 3: Add Sub-Agents in Tab 7**

**Sub-Agent Configuration 1:**

```
Selected Agent: Technical Support Specialist
Description:
"Use this agent when users report bugs, errors, technical issues,
API problems, integration challenges, or need help with system
configuration and troubleshooting. This agent has access to technical
documentation and can query system logs."
```

**Sub-Agent Configuration 2:**

```
Selected Agent: Billing Specialist
Description:
"Delegate to this agent for all billing-related inquiries including
payment issues, invoice questions, subscription changes, pricing
information, refund requests, and account balance questions.
This agent can access billing systems and payment records."
```

**Sub-Agent Configuration 3:**

```
Selected Agent: Product Expert
Description:
"Use this agent when users ask about product features, capabilities,
how to use specific functionality, best practices, or need product
recommendations. This agent provides detailed feature explanations
and usage guidance."
```

#### **Step 4: Test Your Multi-Agent System**

**Test Case 1: Technical Issue**

```
User: "I'm getting a 500 error when I try to create a new workflow"
Expected: Primary agent delegates to Technical Support Specialist
Result: Detailed troubleshooting steps and resolution
```

**Test Case 2: Billing Question**

```
User: "How do I upgrade to the enterprise plan?"
Expected: Primary agent delegates to Billing Specialist
Result: Upgrade process, pricing details, and subscription management
```

**Test Case 3: Product Question**

```
User: "What's the difference between agents and workflows?"
Expected: Primary agent delegates to Product Expert
Result: Clear explanation of both concepts and when to use each
```

**Test Case 4: General Question**

```
User: "What are your support hours?"
Expected: Primary agent handles directly (no delegation needed)
Result: Support hours and contact information
```

***

## 🎯 **Configuration Best Practices**

### **Sub-Agent Description Writing Tips**

**1. Be Specific About Scope**

```
✅ Good: "Use for API authentication errors, webhook configuration issues,
         and integration troubleshooting"
❌ Poor: "Use for technical issues"
```

**2. Mention Available Tools/Knowledge**

```
✅ Good: "This agent has access to billing records and can process refunds"
❌ Poor: "This agent handles billing"
```

**3. Include Example Scenarios**

```
✅ Good: "Delegate when users mention: payment failed, invoice missing,
         subscription cancellation, or upgrade requests"
❌ Poor: "For billing stuff"
```

**4. Clarify Boundaries**

```
✅ Good: "Handles product features and usage. Does NOT handle billing
         or technical troubleshooting"
❌ Poor: "Product agent"
```

### **Common Configuration Mistakes**

**❌ Overlapping Responsibilities**

```
Problem: Two sub-agents with similar descriptions
Sub-Agent 1: "Handles customer questions"
Sub-Agent 2: "Answers user inquiries"
Solution: Define distinct, non-overlapping domains
```

**❌ Missing Context in Descriptions**

```
Problem: Description doesn't explain when to use
"Technical support agent"
Solution: Provide clear delegation criteria
"Use when users report errors, bugs, or technical issues..."
```

**❌ Too Many Sub-Agents**

```
Problem: 10+ sub-agents causing delegation confusion
Solution: Start with 2-4 specialized agents, expand as needed
```

**❌ Sub-Agents Missing Required Tools**

```
Problem: Billing sub-agent has no billing system access
Solution: Ensure sub-agents have necessary tools in Tab 5
```

***

## 📋 **Quick Reference**

### **Configuration Checklist**

Before deploying your multi-agent system:

* [ ] Each sub-agent created as standalone agent
* [ ] Sub-agents have appropriate AI models configured (Tab 2)
* [ ] Sub-agents have clear system instructions (Tab 3)
* [ ] Sub-agents have necessary knowledge bases (Tab 4)
* [ ] Sub-agents have required tools enabled (Tab 5)
* [ ] Primary agent has all sub-agents added in Tab 7
* [ ] Each sub-agent has clear, specific description
* [ ] Descriptions explain WHEN to delegate
* [ ] No overlapping responsibilities between sub-agents
* [ ] Tested with representative user queries
* [ ] Verified delegation decisions are accurate
* [ ] Confirmed response quality from each sub-agent

### **When to Use Sub-Agents**

**✅ Use Sub-Agents When:**

* You need specialized expertise in different domains
* Different tasks require different knowledge bases
* You want to separate concerns (billing, technical, sales)
* Different workflows/tools needed for different request types
* You need to scale specialized capabilities independently

**❌ Don't Use Sub-Agents When:**

* Single domain/expertise is sufficient
* All requests can be handled with same knowledge/tools
* Adding complexity without clear benefit
* Sub-agents would just duplicate primary agent's capabilities

***

Transform your AI agent from a single assistant into an intelligent team of specialists—each expert bringing deep knowledge and specialized capabilities to solve complex challenges.


# Agent Variables

Variables are powerful placeholders that allow your Agents to access dynamic data, configuration settings, and secrets. Instead of hardcoding values, you references variables that are resolved at runtime.

## Why Use Variables?

* **Security**: Securely manage sensitive information like API keys using **Secret** variables.
* **Reusability**: Define a value once (like a brand tone or project ID) and reuse it across multiple agents.
* **Context**: Automatically access runtime information like the current user ID, time, or conversation details.

***

## Variable Scopes

For Agents, variables are organized into two primary scopes:

### 1. Project Variables (Global)

* **Access**: Available to **all agents** and workflows within the project.
* **Use Case**: Shared resources like database credentials, global API keys, or company-wide settings.
* **Syntax**: `{{ var.project.variable_name }}`

### 2. Agent Variables (Local)

* **Access**: Available **only to this specific agent**.
* **Use Case**: Agent-specific configuration, personality settings, or tools configurations unique to this agent.
* **Syntax**: `{{ var.agent.variable_name }}`

***

## System Variables (Automatic)

System variables are read-only values automatically populated by AgenticFlow every time an agent runs or replies. They provide essential context about the execution environment.

**Syntax**: `{{ sys.variable_name }}`

| Variable           | Description                                     | Example                     |
| ------------------ | ----------------------------------------------- | --------------------------- |
| `sys.user_id`      | ID of the user interacting with the agent       | `usr_8x92...`               |
| `sys.agent_id`     | ID of the current agent                         | `agent_abc123...`           |
| `sys.thread_id`    | ID of the current conversation thread           | `thread_xyz789...`          |
| `sys.agent_run_id` | Unique ID for the current execution             | `run_def456...`             |
| `sys.project_id`   | ID of the current project                       | `proj_ab12...`              |
| `sys.triggered_by` | Source of the interaction (user, API, schedule) | `user`                      |
| `sys.datetime`     | Current ISO datetime                            | `2024-01-19T10:30:00+00:00` |
| `sys.date`         | Current date (YYYY-MM-DD)                       | `2024-01-19`                |
| `sys.time`         | Current time (HH:MM:SS)                         | `10:30:00`                  |

***

## Configuring Variables

You can manage variables in the **Configuration** tab of your Agent editor.

### Data Types

* **String**: Text content.
* **Number**: Decimal values (e.g., `0.95`).
* **Integer**: Whole numbers (e.g., `42`).
* **Boolean**: True/False flags.

### Security & Constraints

* **Secret**: Encrypts the value and masks it in all logs/UI. **Essential for API keys.**
* **Read-only**: Ensures the variable cannot be modified during runtime.
* **Required**: Prevents the agent from running if the variable is empty.

***

## Where to Use Variables

You can use variables in almost any input field in the AgenticFlow builder by typing `#` to reference a variable. A dropdown list will appear—scroll to the bottom to find the variables you’ve created.

<figure><img src="/files/odOetL3fLzxm9aEGDV2J" alt=""><figcaption></figcaption></figure>

If # doesn’t work in a specific field, try using the double curly brace syntax: {{ }}.

### 1. System Prompt

Personalize the agent's behavior based on context.

```
You are an assistant for Project {{ var.project.project_name }}.
Today is {{ sys.date }}.
Please address the user as {{ sys.user_id }}.
```

### 2. Tool Arguments

Pass secure credentials or dynamic values to tools without exposing them.

```json
{
  "api_key": "{{ var.project.openai_api_key }}",
  "user_context": "{{ var.agent.user_preference }}"
}
```

### 3. Knowledge Retrieval

Filter knowledge base queries based on dynamic variables.


# Agent Versioning & Deployment

Manage your agent's lifecycle safely with AgenticFlow's explicit versioning system. Versioning allows you to iterate on your agent's design, test new features in a draft state, and only publish changes when they are ready for your users.

## Why Use Versioning?

* **Safe Experimentation**: Make changes to your agent's prompt, tools, or model without affecting live users.
* **Release Control**: Explicitly "publish" a version only when it's tested and ready.
* **History & Rollback**: Keep a snapshot of every major change and restore previous versions if something goes wrong.
* **Dependency Protection**: The system ensures you don't accidentally delete workflows or knowledge bases that your live agent depends on.

<div data-with-frame="true"><figure><img src="/files/hnt5r2LPt04nISu74HJO" alt=""><figcaption></figcaption></figure></div>

## Key Concepts

### 1. Draft (Working Copy)

The **Draft** is your mutable development environment. All configuration changes happen here first.

* **Editable**: This is the only state where configuration (prompts, tools, models) can be modified.
* **Private**: Changes in the Draft are isolated from the production environment. Users interacting with the public agent do not see these changes until they are explicitly published.
* **Testable**: The Draft environment allows for testing and verification of new behaviors before they are committed to a version.

### 2. Versions (Snapshots)

A **Version** is an immutable snapshot of an agent's configuration at a specific point in time.

* **Frozen**: Once created, a version cannot be modified. It preserves the exact combination of system prompt, model settings, tool definitions, and knowledge base connections that existed when it was created.
* **Traceable**: Each version serves as a historical record, allowing you to track the evolution of your agent's logic and capabilities.

### 3. Published Version (Production)

The **Published Version** is the single active configuration that requests to the agent's public endpoints will use.

* **Production Traffic**: All interactions via the Public URL, Website Widget, or standard API integrations are routed to this version.
* **Stability**: The published version remains constant even while you continue to experiment and make changes in the Draft.
* **Seamless Updates**: Switching the published version updates the agent's behavior instantly for new conversations, without changing the agent's identity or endpoint URL.

***

## The Release Lifecycle

The versioning system supports a structured deployment workflow designed for reliability.

### Step 1: Iteration (Draft)

Development begins in the Draft state. During this phase, you can freely modify the agent's definition—tuning the prompt, adding or removing tools, or switching AI models. These changes are saved to the Draft but have no impact on the live agent.

<figure><img src="/files/NudtJ0X9q2ChfSEquy7m" alt=""><figcaption></figcaption></figure>

### Step 2: Snapshotting (Create Version)

When the Draft reaches a stable state or functionality that is ready for release, it can be saved as a Version. This action "freezes" the current Draft configuration into a numbered release (e.g., `v1`, `v2`). This snapshot is stored permanently and can be referenced later.

<figure><img src="/files/n6N04nvR8mnO26GrlrPW" alt=""><figcaption></figcaption></figure>

### Step 3: Deployment (Publish)

To release changes to end-users, a specific Version is marked as **Published**. The system updates the live routing to point to this new version. This separation of "creating a version" and "publishing" allows you to maintain multiple historical versions while having control over exactly which one is live.

{% embed url="<https://www.loom.com/share/30bb84c17b924bf683854986dc1984ad>" %}

***

## Management & Safety

### Restoration (Rollback)

If development in the Draft diverges or introduces issues, the system allows you to **Restore** a previous version. This action overwrites the current Draft configuration with the settings from the selected version, effectively reverting the "working copy" to a known good state. This does not affect the Published version, ensuring safety during recovery.

### Unpublishing

Agents can be **Unpublished**, which stops the agent from serving public traffic. This is useful for taking an agent offline for maintenance or decommissioning.

### Dependency Integrity

The platform enforces referential integrity to prevent "broken" agents. Because a published agent relies on specific external resources (such as specific Workflows, Knowledge Bases, or Credentials), the system prevents the deletion of these dependent resources while they are in use by a published version.

* **Deletion Blocking**: Attempts to delete a resource used by a live agent will be blocked.
* **Impact Analysis**: The system identifies exactly which agent versions depend on the resource, requiring you to update or unpublish the agent before the resource can be removed.


# Agent Templates

Use our pre-built AI agent templates to jumpstart your automated operations.

### What Are Agent Templates?

Agent templates are pre-built team members that come ready to complete specific tasks. They serve as a launchpad, allowing you to test and explore autonomous agents before tailoring them to your own business objectives. With these templates, you can quickly experience what it takes to transform routine tasks into intelligent workflows.

### How to Use an Agent Template

Getting started is simple:

* **Choose Your Template:** Browse our collection of pre-built agent templates designed for common operational needs.
* **Customize with Ease:** Adjust every setting and behavior to align with your company’s procedures. Modify tools, tweak core instructions, and update settings effortlessly.
* **Deploy Instantly:** Save your customizations and start leveraging your new AI agent immediately to optimize your processes.

### Spotlight on Business Excellence

Meet **Iris – the Visual Designer**, our premier agent template crafted for creative excellence. Iris leverages advanced AI tools to generate and edit images based on your precise requirements, delivering striking visuals that balance creativity with technical precision. With Iris on your team, you can expect:

* **High-Quality Image Generation:** Transform intricate design prompts into stunning visuals effortlessly.
* **Dynamic Image Editing:** Adjust colors, composition, and resolution to enhance every detail.
* **Innovative Creative Suggestions:** Receive proactive recommendations to elevate your design projects.
* **Efficient and Accurate Output:** Experience fast delivery and reliable quality, empowering your creative workflows.

Ready to elevate your creative process? Dive into our library of agent templates, explore the capabilities of Iris, and customize the experience to unlock your full potential. Embrace intelligent automation and let AgenticFlow redefine your approach to design.


# Workflows Hub

Build powerful sequential automation workflows with AgenticFlow's visual drag-and-drop builder. No coding required.

## What are Workflows?

Workflows are **linear, sequential automation flows** that execute step-by-step tasks by connecting nodes together. Each workflow:

* Executes nodes **one by one, from top to bottom**
* Processes data through a **linear chain of nodes**
* Integrates with **300+ tools (MCPs)**
* Runs **on-demand or on schedule**
* Follows a **single execution path** (no branching or loops)

## How Workflows Work

### Core Concepts

<figure><img src="/files/xtHFmwHaUIB1q4n15YnU" alt="" width="563"><figcaption></figcaption></figure>

Every workflow consists of three main components:

**1. Input Schema** (What data does the workflow need?)

* Define parameters users provide when starting the workflow
* Supports multiple input types: text, numbers, files, dropdowns, JSON, etc.
* Each input has a unique name that nodes can reference

**2. Nodes** (What processing steps happen?)

* The workflow executes nodes **sequentially from top to bottom**
* Each node has a unique name (e.g., `web_scraper`, `send_email`)
* Each node performs a specific task (API call, data transform, AI generation, etc.)
* Nodes reference data using parameter substitution: `{{input_name}}` or `{{node_name.output_field}}`

**3. Output Mapping** (What data does the workflow return?)

* Define which node outputs to return as final workflow results
* Map output fields to node outputs: `{"result": "{{final_node.output}}"}`
* **Optional**: If not configured, the workflow automatically returns the last node's output

### Execution Flow

Workflows execute in a **strict linear order**:

```
User Inputs → Node 1 → Node 2 → Node 3 → ... → Node N → Workflow Output
```

* **No branching**: Every node executes every time
* **No loops**: Nodes run exactly once in sequence
* **Top-to-bottom**: Execution order matches visual layout
* **Data flows forward**: Later nodes can reference earlier nodes' outputs

### Parameter Substitution

Connect data between workflow steps using `{{...}}` syntax:

**Reference workflow inputs:**

```
{{user_email}}
{{website_url}}
{{search_query}}
```

**Reference node outputs:**

```
{{web_scraper.content}}
{{llm_analyzer.summary}}
{{api_call.response}}
```

**Use in node configurations:**

```json
{
  "email_body": "Here's your analysis: {{llm_analyzer.summary}}",
  "recipient": "{{user_email}}",
  "subject": "Results for {{search_query}}"
}
```

### Output Mapping Behavior

The workflow's output mapping is **optional** and controls what data is returned:

**When Output Mapping IS Defined:**

```json
{
  "summary": "{{analyzer.result}}",
  "status": "{{email.success}}",
  "timestamp": "{{current_time.value}}"
}
```

* Returns only the specified fields
* Can combine outputs from multiple nodes
* Gives you full control over the response structure

**When Output Mapping IS NOT Defined:**

* The workflow automatically returns **all outputs from the last node**
* Simpler for workflows where you only care about the final step's result
* No need to manually map outputs

**Example:**

```
Node 1: fetch_data → {data: [...], count: 10}
Node 2: process_data → {processed: [...], errors: []}
Node 3: save_results → {success: true, id: "123"}

Without output mapping → Returns: {success: true, id: "123"}
With output mapping → Returns: Whatever you specify
```

## When to Use Workflows

**Perfect for**:

* **Sequential automation**: Step-by-step processes with a clear order
* **Data processing pipelines**: Transform data through multiple stages
* **API orchestration**: Chain multiple API calls together
* **Scheduled tasks**: Run automated processes on a schedule
* **Tool integration**: Connect different services in sequence
* **Batch operations**: Process data in a predictable, linear way

**Use Agents instead when**:

* You need conversational interaction
* Real-time chat with users
* Interactive Q\&A systems
* Dynamic decision-making during execution

**Use Workforce instead when**:

* You need multiple AI agents collaborating
* Complex multi-agent orchestration
* Dynamic routing between different processing paths

***

## Your First Workflow: A Simple Example

Let's build a workflow that scrapes a website and sends the content via email.

### Step 1: Define Inputs

```json
{
  "website_url": {
    "type": "string",
    "title": "Website URL",
    "description": "URL to scrape"
  },
  "recipient_email": {
    "type": "string",
    "title": "Email",
    "description": "Where to send results"
  }
}
```

### Step 2: Add Nodes (Top to Bottom)

**Node 1: `web_scraper`** (Scrape the website)

* Node type: `web_scraping`
* Input config: `{"url": "{{website_url}}"}`

**Node 2: `send_email`** (Email the content)

* Node type: `send_email`
* Input config:

  ```json
  {
    "recipient": "{{recipient_email}}",
    "subject": "Website Content",
    "body": "{{web_scraper.content}}"
  }
  ```

### Step 3: Define Output (Optional)

**Option A: Custom Output Mapping**

```json
{
  "status": "{{send_email.success}}",
  "content": "{{web_scraper.content}}"
}
```

**Option B: No Output Mapping**

* If you don't define output mapping, the workflow automatically returns the output from the last node (`send_email`)

### Execution

When you run this workflow:

1. User provides `website_url` and `recipient_email`
2. `web_scraper` node executes, scrapes the URL, outputs `content`
3. `send_email` node executes, sends email with scraped content
4. **Workflow returns**:
   * With custom mapping: `status` and `content` fields
   * Without mapping: All outputs from `send_email` node

***

## Getting Started

### [Workflows Quickstart](/get-started/workflows-quickstart)

Build your first workflow in 10 minutes.

### [Data Flow & Type Handling](/workflows/data-flow-and-types)

**Essential guide** to how data flows between nodes and handling data types correctly. Learn how to reference data and avoid type mismatch errors.

***

## Workflow Building Blocks

### [User Inputs](/workflows/workflow-inputs/text-input)

Collect data to start your workflow:

* Text Input
* Number Input
* File Upload
* Date/Time Picker
* Dropdown Select
* Checkbox
* Multi-select
* Email Input
* URL Input
* Phone Input
* JSON Input
* Rich Text Editor

### [Variables](/workflows/variables)

Manage constants, configuration, and secrets across your project:

* **Project Variables** - Global values shared across workflows
* **Workflow Variables** - Local configuration for a single workflow
* **System Variables** - Auto-injected runtime context (User ID, Workflow ID)
* **Secret Management** - Secure storage for API keys and tokens

### [Actions](/reference/nodes)

Execute tasks and operations:

* **AI/LLM Actions** - AI model calls, text generation, embeddings
* **Data Processing** - Transform, filter, aggregate data
* **Integrations** - Connect to 300+ tools via MCPs
* **API Calls** - HTTP requests, webhooks
* **Database** - Read/write operations
* **File Operations** - Upload, download, process files
* **Notifications** - Email, Slack, SMS
* **Data Transformation** - Format, parse, convert data

### Logic & Control

Control workflow execution:

* **Error Handling** - Handle failures gracefully
* **Delays** - Wait for time or conditions
* **Data Validation** - Verify data meets requirements

### Outputs

Return results and data:

* Display results
* Return JSON
* Download files
* Send notifications
* Trigger webhooks
* Store in database

***

## Advanced Features

### Error Handling

Handle failures gracefully:

* Try/catch blocks
* Retry logic
* Fallback actions
* Error notifications

***

## Workflow Templates

Start with pre-built workflow templates:

### [Browse All Templates](/workflows/templates)

**Popular Templates**:

* Data Processing Pipeline
* Email Automation
* Lead Qualification
* Report Generation
* Content Publishing
* File Processing
* API Integration
* Notification System
* Data Synchronization
* Scheduled Batch Jobs

***

## Workflow Patterns

### Common Automation Patterns

**Sequential Processing** (Basic linear flow):

```
Input → Process → Transform → Output
```

**Multi-Step Data Pipeline**:

```
Input → Fetch Data → Transform → Enrich → Validate → Store → Output
```

**AI Analysis Chain**:

```
Input → Extract Text → Analyze with LLM → Summarize → Format → Output
```

**API Integration Flow**:

```
Input → Call API 1 → Parse Response → Call API 2 → Combine Results → Output
```

**Content Generation Pipeline**:

```
Input → Research → Generate Draft → Review → Format → Publish → Output
```

***

## Best Practices

### Workflow Design Best Practices

**Design Principles**:

* Keep workflows focused and modular
* Use clear node names
* Add comments and documentation
* Handle errors gracefully
* Test edge cases

**Performance**:

* Minimize AI calls (they're slower and cost more)
* Reduce unnecessary nodes in the chain
* Cache data when possible
* Keep workflows focused and concise

**Maintainability**:

* Use parameter substitution for flexibility
* Avoid hardcoding values
* Document complex logic
* Version control your workflows

**Error Handling**:

* Always handle API failures
* Provide fallback options
* Log errors for debugging
* Notify on critical failures

***

## Node Reference

AgenticFlow provides **193+ workflow nodes** across categories:

* **AI & LLM** (20+ nodes) - Text generation, embeddings, vision
* **Data** (30+ nodes) - Transform, filter, aggregate, validate
* **Integrations** (300+ MCPs) - Connect to external tools
* **Logic** (15+ nodes) - Conditionals, loops, branches
* **HTTP** (10+ nodes) - API calls, webhooks, requests
* **Files** (12+ nodes) - Upload, download, process, convert
* **Database** (15+ nodes) - SQL, NoSQL operations
* **Text** (20+ nodes) - String operations, parsing, formatting
* **Math** (10+ nodes) - Calculations, statistics
* **Date/Time** (8+ nodes) - Date operations, scheduling
* **Notifications** (10+ nodes) - Email, Slack, SMS, push
* **Utilities** (40+ nodes) - Various helper functions

See [Complete Node Reference](/reference/nodes) for all 193+ nodes.

***

## Testing & Debugging

### Testing Your Workflow

1. Start with sample data
2. Run step-by-step
3. Inspect node outputs
4. Test error cases
5. Verify edge cases
6. Performance testing

### Debugging Tools

* Node output inspection
* Execution logs
* Error messages
* Variable inspection
* Step-through execution

***

## Deployment & Scheduling

### Execution Options

* **Manual** - Run on-demand via UI or API
* **Scheduled** - Cron-based scheduling
* **Triggered** - Webhook or event-based
* **API** - Call via REST API
* **Embedded** - Integrate in applications

### Monitoring

* Execution history
* Success/failure rates
* Performance metrics
* Credit consumption
* Error tracking

***

## Integrations

Connect workflows to 300+ tools via MCPs:

### Popular Workflow Integrations

* **Data Sources**: Google Sheets, Airtable, Databases
* **Communication**: Gmail, Slack, Discord, Telegram
* **CRM**: Salesforce, HubSpot, Pipedrive
* **Storage**: Google Drive, Dropbox, S3
* **APIs**: Custom HTTP requests
* **Databases**: PostgreSQL, MongoDB, MySQL

See [All Integrations](/integrations/07-integrations)

***

## Troubleshooting

Common issues and solutions:

* **Workflow fails**: Check node connections and required inputs
* **Slow execution**: Optimize node count and parallel processing
* **Integration errors**: Verify MCP credentials and permissions
* **Data issues**: Validate input formats and transformations
* **Timeout errors**: Split long-running tasks, increase limits

See [Troubleshooting Guide](/support/troubleshooting) for more help.

***

## Workflows vs Workforce vs Agents

**Use Workflows when**:

* You need **linear, sequential automation**
* Single execution path from start to finish
* Connecting tools and APIs in a predictable order
* Scheduled or triggered batch processing
* Data pipelines with fixed steps

**Use Agents when**:

* You need **conversational interaction**
* Real-time chat with users
* Dynamic decision-making during conversations
* Interactive Q\&A and assistance

**Use Workforce when**:

* You need **multiple AI agents collaborating**
* Complex multi-agent orchestration
* Dynamic routing between different agents
* Advanced coordination patterns

See [Workforce Documentation](/workforce/05-workforce)

***

## Related Documentation

* [Agents](/ai-agents/03-agents) - For conversational AI
* [Workforce](/workforce/05-workforce) - For multi-agent systems
* [Integrations](/integrations/07-integrations) - Available MCPs
* [Node Reference](/reference/nodes) - All 193+ nodes
* [API Reference](https://github.com/PixelML/agenticflow-docs/blob/main/docs/09-developers/api/endpoints/workflows.md) - Workflow API

***

## Learn More

* [Learning Hub](/learn/02-learn) - Foundation concepts and learning resources
* [Video Tutorials](/learn/video-series) - Visual learning
* [Use Cases](/use-cases/10-use-cases) - Real-world examples
* [Community](/support/community) - Ask questions

***

**Ready to build your first workflow?** [Start the Quickstart →](/get-started/workflows-quickstart)


# Data Flow & Type Handling

Learn how data flows between nodes in workflows and handle data types correctly to avoid runtime errors.

## Overview

In workflows, **data flows from one node to the next** by referencing outputs from previous nodes or workflow inputs. You control this data flow using `{{...}}` reference syntax. Each field has a specific **data type**, and type compatibility is critical for successful workflow execution.

**Key Concepts:**

* Workflow inputs and node outputs have defined types
* Node inputs expect specific types
* Type mismatches cause workflow failures at runtime
* Type conversion nodes help transform data between incompatible types

***

## How Data Flows in Workflows

Understanding how data moves through your workflow is essential for building reliable automations.

### Workflow Execution Flow

Workflows execute **linearly from top to bottom**, with data passing from one node to the next:

```
1. User provides workflow inputs
   ↓
2. Node 1 executes → produces outputs
   ↓
3. Node 2 executes (can reference Node 1 outputs) → produces outputs
   ↓
4. Node 3 executes (can reference Node 1 & 2 outputs) → produces outputs
   ↓
5. Workflow returns final output
```

### Available Data at Each Node

Each node can access:

* **Workflow inputs**: Data provided when the workflow starts
* **Previous node outputs**: Results from any node that executed before it
* **Cannot access**: Future node outputs (nodes that haven't executed yet)

**Example:**

```
Node 1: fetch_user
  Can access: workflow inputs only

Node 2: analyze_data
  Can access: workflow inputs + fetch_user outputs

Node 3: send_email
  Can access: workflow inputs + fetch_user outputs + analyze_data outputs
```

### Controlling Data Flow

You control what data flows between nodes by:

1. **Referencing specific fields** - Choose exactly which data to pass
2. **Transforming data** - Use conversion techniques to match types
3. **Combining data** - Merge multiple sources into one field

***

## How to Reference Data

Use double curly braces `{{...}}` to reference data in node configurations and text fields:

### Reference Workflow Inputs

```
{{input_field_name}}
```

**Example:**

```json
{
  "url": "{{website_url}}",
  "email": "{{user_email}}"
}
```

### Reference Node Outputs

```
{{node_name.output_field}}
```

**Example:**

```json
{
  "content": "{{web_scraper.html}}",
  "summary": "{{llm_analyzer.result}}"
}
```

### Use in Text Strings

You can embed references inside text strings - **they will always be converted to string type**:

```json
{
  "message": "Hello {{user_name}}, your order #{{order_id}} is ready!",
  "subject": "Analysis complete: {{analyzer.status}}",
  "body": "Found {{search_results.count}} results for {{query}}"
}
```

**Important:** When used in strings, all values are automatically converted to text:

* Numbers become strings: `{{count}}` → `"42"`
* Objects become JSON strings: `{{user}}` → `'{"name":"John"}'`
* Arrays become JSON strings: `{{items}}` → `'["a","b","c"]'`

### Nested Field Access

Access nested objects and arrays:

```
{{node_name.data.users[0].name}}
{{api_response.result.items[2].id}}
```

***

## Understanding Data Types

Every field in **workflow inputs**, **node inputs**, and **node outputs** has a specific data type defined in its schema.

### Common Data Types

| Type      | Description                   | Example Values                  |
| --------- | ----------------------------- | ------------------------------- |
| `string`  | Text data                     | `"hello"`, `"user@example.com"` |
| `number`  | Numeric values (int or float) | `42`, `3.14`, `-10`             |
| `boolean` | True/false values             | `true`, `false`                 |
| `object`  | JSON objects/dictionaries     | `{"name": "John", "age": 30}`   |
| `array`   | Lists of items                | `[1, 2, 3]`, `["a", "b", "c"]`  |

### How to Check Field Types

**1. Workflow Input Types** When defining workflow inputs, you specify the type:

```json
{
  "user_email": {
    "type": "string",
    "title": "User Email"
  },
  "max_results": {
    "type": "number",
    "title": "Maximum Results"
  }
}
```

**2. Node Input and Output Types** Each node defines its input and output types in its schema. **Check the node's detail page** to see:

* What input types each field expects
* What output types each field produces

**Where to find node type information:**

* [Node Reference Documentation](/reference/nodes) - Browse all 193+ nodes by category
* Individual node detail pages - Shows complete input/output schemas
* Visual builder node panel - Displays field types when configuring nodes

***

## Type Compatibility Rules

### ✅ Compatible Substitution

You can substitute a field if the **types match exactly**:

```json
// Workflow input: user_email (string)
// Node 1 output: email_address (string)
// Node 2 input: recipient (string)

{
  "recipient": "{{user_email}}"  // ✅ string → string
}

{
  "recipient": "{{node_1.email_address}}"  // ✅ string → string
}
```

### ❌ Incompatible Substitution

Type mismatches will cause **runtime errors**:

```json
// Node 1 output: user_data (object)
// Node 2 input: email (string)

{
  "email": "{{node_1.user_data}}"  // ❌ object → string
}
```

**Error at runtime:**

```
Type mismatch: Expected string, got object
```

### Example: Type Mismatch Scenario

**Workflow Setup:**

```
Node 1: api_call
  Output: response (object) = {"users": [{"email": "test@example.com"}]}

Node 2: send_email
  Input: recipient (string)
```

**Incorrect Configuration:**

```json
{
  "recipient": "{{api_call.response}}"  // ❌ Fails!
}
```

Error: Cannot assign object to string field.

**Correct Configuration:**

```json
{
  "recipient": "{{api_call.response.users[0].email}}"  // ✅ Works!
}
```

Access the nested string field directly.

***

## Type Conversion Techniques

When you need to connect fields with different types, use these techniques:

### 1. String to JSON (Object/Array)

**Use Case:** Convert JSON string to object or array

**Node:** `string_to_json`

**Example:**

```
Node 1: api_call
  Output: json_string (string) = '{"name": "John", "age": 30}'

Node 2: string_to_json
  Input: string_to_convert (string) = "{{api_call.json_string}}"
  Output: json_output (object) = {"name": "John", "age": 30}

Node 3: process_user
  Input: user_object (object) = "{{string_to_json.json_output}}"
```

### 2. Object/Array to String

**Use Case:** Convert object or array to string

**Technique:** Use string interpolation (automatic conversion)

```json
{
  "text_field": "User data: {{object_node.data}}",
  "message": "Items: {{array_node.items}}"
}
```

When embedded in strings, objects and arrays are automatically converted to JSON string format.

### 3. Number to String

**Use Case:** Convert numeric values to text

**Technique:** Use string interpolation (automatic conversion)

```json
{
  "message": "Count: {{counter_node.value}}",
  "id": "ID-{{order_id}}"
}
```

Numbers are automatically converted to strings when embedded in text.

### 4. Extract Array Item

**Use Case:** Get a single item from an array

**Technique:** Use array indexing

```json
{
  "first_user": "{{users_node.list[0]}}",
  "last_item": "{{items[2]}}"
}
```

### 5. Extract Object Field

**Use Case:** Get a specific field from an object

**Technique:** Use dot notation

```json
{
  "user_name": "{{user_object.name}}",
  "user_age": "{{user_object.age}}",
  "nested_value": "{{data.results.items[0].id}}"
}
```

### 6. Custom Transformations with Code

**Use Case:** Complex type conversions and data transformations

**Available Nodes:**

* `run_javascript` - Execute JavaScript code for transformations
* `run_python_code` - Execute Python code for transformations

**Example (JavaScript):**

```javascript
// Input: data_array (array of objects)
// Output: CSV string

const headers = Object.keys(data_array[0]).join(',');
const rows = data_array.map(obj =>
  Object.values(obj).join(',')
).join('\n');

return headers + '\n' + rows;
```

**Example (Python):**

```python
# Input: items (array)
# Output: formatted_list (string)

formatted = '\n'.join([f"- {item}" for item in items])
return formatted
```

***

## Common Type Mismatch Scenarios

### Scenario 1: API Response to Email Body

**Problem:**

```json
// API returns: {"status": "success", "message": "Done"}
// Email expects: string

{
  "email_body": "{{api_call.response}}"  // ⚠️ May not be what you want
}
```

This will work (objects are auto-converted to JSON strings), but you'll get:

```
{"status":"success","message":"Done"}
```

**Better Solutions:**

**Solution A:** Access the specific field you want

```json
{
  "email_body": "{{api_call.response.message}}"  // ✅ Returns: "Done"
}
```

**Solution B:** Format it nicely in a string

```json
{
  "email_body": "Status: {{api_call.response.status}}, Message: {{api_call.response.message}}"
  // ✅ Returns: "Status: success, Message: Done"
}
```

**Solution C:** Use the whole object if you want JSON

```json
{
  "email_body": "API Response: {{api_call.response}}"
  // ✅ Returns: 'API Response: {"status":"success","message":"Done"}'
}
```

### Scenario 2: String ID to Number ID

**Problem:**

```json
// Node 1 returns: user_id (string) = "12345"
// Node 2 expects: id (number)

{
  "id": "{{node_1.user_id}}"  // ❌ Type error: string → number
}
```

**Solution:** Use `run_javascript` or `run_python_code` to convert

```javascript
// JavaScript
return parseInt(user_id);  // Converts "12345" → 12345
```

```python
# Python
return int(user_id)  # Converts "12345" → 12345
```

### Scenario 3: Multiple Values to Array

**Problem:**

```json
// Need array of emails
// Have: email1 (string), email2 (string)

{
  "recipients": "{{email1}}, {{email2}}"  // ❌ string, not array
}
```

**Solution:** Use array construction

```json
{
  "recipients": ["{{email1}}", "{{email2}}"]  // ✅
}
```

***

## Type Validation and Error Messages

### Runtime Type Errors

When types don't match, workflows fail with clear error messages:

**Example Error:**

```
Node: send_email (step 3)
Field: recipient
Error: Type validation failed
Expected: string
Received: object
Value: {"email": "user@example.com", "name": "John"}
```

### How to Fix Type Errors

1. **Check the error message** - identifies the node, field, expected type, and actual type
2. **Review node documentation** - confirm expected input types
3. **Inspect previous node outputs** - verify what type is being produced
4. **Add conversion node** - insert appropriate type conversion between nodes
5. **Adjust substitution** - use dot notation or array indexing to access correct type

***

## Best Practices

### 1. Verify Types Before Substituting

Always check:

* What type does the source field produce?
* What type does the target field expect?
* Do they match?

### 2. Use Node Documentation

Refer to the [Node Reference](/reference/nodes) to understand:

* Input schemas (expected types)
* Output schemas (produced types)

### 3. Test Incrementally

Build workflows step-by-step:

1. Add a node
2. Configure inputs with substitution
3. Run and verify output types
4. Continue to next node

### 4. Add Type Conversion Early

If you know types don't match:

* Insert conversion nodes immediately
* Don't wait for runtime errors

### 5. Use Explicit Field Access

Instead of:

```json
{"data": "{{api_node.response}}"}  // May be wrong type
```

Use:

```json
{"data": "{{api_node.response.data.result}}"}  // Explicit field
```

### 6. Handle Arrays Carefully

Remember:

* `{{node.items}}` → entire array
* `{{node.items[0]}}` → first item
* `{{node.items[0].name}}` → field from first item

***

## Type Conversion Node Reference

Available nodes and techniques for type conversion:

| Conversion                | Method                               | Example                                 |
| ------------------------- | ------------------------------------ | --------------------------------------- |
| **String → Object/Array** | `string_to_json` node                | Parse `'{"a":1}'` → `{a: 1}`            |
| **Object/Array → String** | String interpolation                 | `"Data: {{obj}}"` → `'Data: {"a":1}'`   |
| **Number → String**       | String interpolation                 | `"Count: {{num}}"` → `"Count: 42"`      |
| **String → Number**       | `run_javascript` / `run_python_code` | `parseInt("42")` → `42`                 |
| **Array → String**        | String interpolation                 | `"Items: {{arr}}"` → `'Items: [1,2,3]'` |
| **Extract from Array**    | Array indexing                       | `{{arr[0]}}` → first item               |
| **Extract from Object**   | Dot notation                         | `{{obj.field}}` → field value           |
| **Custom Transform**      | `run_javascript` / `run_python_code` | Any complex conversion                  |

**Key Nodes:**

* `string_to_json` - Parse JSON strings to objects/arrays
* `run_javascript` - Execute JavaScript for custom transformations
* `run_python_code` - Execute Python for custom transformations
* `get_value_by_key` - Extract value from object by key name

See the [Node Reference](/reference/nodes) for available utility nodes.

***

## Troubleshooting Guide

### Issue: "Type mismatch" error at runtime

**Solution:**

1. Check error message for expected vs. actual type
2. Add conversion node between incompatible nodes
3. Use dot notation to access nested fields of correct type

### Issue: "Cannot read property of undefined"

**Solution:**

1. Verify previous node executed successfully
2. Check field name spelling: `{{node.field}}` must match exactly
3. Ensure previous node actually outputs that field

### Issue: "Invalid JSON" error

**Solution:**

1. Verify string is valid JSON before using `string_to_json`
2. Check for escaped quotes or formatting issues
3. Test JSON string in external validator

### Issue: Array indexing fails

**Solution:**

1. Verify array is not empty: check previous node output
2. Use valid index: `[0]` for first item, not `[1]`
3. Handle potential empty arrays in workflow logic

***

## Related Documentation

* [Node Reference](/reference/nodes) - Complete node type documentation
* [Node Reference](/reference/nodes) - Type conversion nodes
* [Troubleshooting Guide](https://github.com/PixelML/agenticflow-docs/blob/main/docs/12-support/troubleshooting/troubleshooting-guide.md) - Common workflow errors

***

## Complete Example: Step-by-Step Workflow Execution

Let's walk through a real workflow execution to see exactly what data is available at each step and how the workflow state changes.

### Workflow Setup

**Workflow Definition:**

```json
{
  "name": "API Analysis Workflow",
  "input_schema": {
    "type": "object",
    "properties": {
      "api_url": {
        "type": "string",
        "title": "API URL"
      },
      "recipient_email": {
        "type": "string",
        "title": "Recipient Email"
      }
    }
  }
}
```

***

### 📊 STEP 1: User Starts Workflow

**User provides inputs:**

```json
{
  "api_url": "https://api.example.com/users/123",
  "recipient_email": "admin@company.com"
}
```

**Workflow State:**

```json
{
  "inputs": {
    "api_url": "https://api.example.com/users/123",
    "recipient_email": "admin@company.com"
  },
  "nodes": {}
}
```

**What you can reference:**

* ✅ `{{api_url}}` → `"https://api.example.com/users/123"`
* ✅ `{{recipient_email}}` → `"admin@company.com"`
* ❌ No node outputs available yet

***

### 📊 STEP 2: Node 1 (fetch\_data) Executes

**Node Configuration:**

```json
{
  "name": "fetch_data",
  "node_type_name": "api_call",
  "input_config": {
    "url": "{{api_url}}",
    "method": "GET"
  }
}
```

**After {{...}} substitution, node receives:**

```json
{
  "url": "https://api.example.com/users/123",
  "method": "GET"
}
```

**Node executes and produces output:**

```json
{
  "status_code": 200,
  "response_body": {
    "id": 123,
    "name": "John Doe",
    "email": "john@example.com",
    "status": "active"
  }
}
```

**Workflow State after Node 1:**

```json
{
  "inputs": {
    "api_url": "https://api.example.com/users/123",
    "recipient_email": "admin@company.com"
  },
  "nodes": {
    "fetch_data": {
      "status_code": 200,
      "response_body": {
        "id": 123,
        "name": "John Doe",
        "email": "john@example.com",
        "status": "active"
      }
    }
  }
}
```

**What you can now reference:**

* ✅ `{{api_url}}` → `"https://api.example.com/users/123"`
* ✅ `{{recipient_email}}` → `"admin@company.com"`
* ✅ `{{fetch_data.status_code}}` → `200`
* ✅ `{{fetch_data.response_body}}` → `{"id": 123, "name": "John Doe", ...}`
* ✅ `{{fetch_data.response_body.name}}` → `"John Doe"`
* ✅ `{{fetch_data.response_body.status}}` → `"active"`
* ❌ Cannot reference nodes that haven't executed yet

***

### 📊 STEP 3: Node 2 (analyze\_user) Executes

**Node Configuration:**

```json
{
  "name": "analyze_user",
  "node_type_name": "claude_ask",
  "input_config": {
    "prompt": "Analyze this user data: Name is {{fetch_data.response_body.name}}, status is {{fetch_data.response_body.status}}",
    "model": "claude-3-5-sonnet-latest",
    "max_tokens": 500
  }
}
```

**After {{...}} substitution, node receives:**

```json
{
  "prompt": "Analyze this user data: Name is John Doe, status is active",
  "model": "claude-3-5-sonnet-latest",
  "max_tokens": 500
}
```

**Node executes and produces output:**

```json
{
  "content": "This user John Doe appears to be an active account holder in good standing."
}
```

**Workflow State after Node 2:**

```json
{
  "inputs": {
    "api_url": "https://api.example.com/users/123",
    "recipient_email": "admin@company.com"
  },
  "nodes": {
    "fetch_data": {
      "status_code": 200,
      "response_body": {
        "id": 123,
        "name": "John Doe",
        "email": "john@example.com",
        "status": "active"
      }
    },
    "analyze_user": {
      "content": "This user John Doe appears to be an active account holder in good standing."
    }
  }
}
```

**What you can now reference:**

* ✅ All workflow inputs
* ✅ All `fetch_data` outputs
* ✅ `{{analyze_user.content}}` → `"This user John Doe appears to be..."`
* ❌ Cannot reference nodes that haven't executed yet

***

### 📊 STEP 4: Node 3 (send\_report) Executes

**Node Configuration:**

```json
{
  "name": "send_report",
  "node_type_name": "send_email",
  "input_config": {
    "recipient_emails": ["{{recipient_email}}"],
    "subject": "User Analysis Report",
    "body": "Analysis for {{fetch_data.response_body.name}}:\n\n{{analyze_user.content}}"
  }
}
```

**After {{...}} substitution, node receives:**

```json
{
  "recipient_emails": ["admin@company.com"],
  "subject": "User Analysis Report",
  "body": "Analysis for John Doe:\n\nThis user John Doe appears to be an active account holder in good standing."
}
```

**Node executes and produces output:**

```json
{
  "message": "Email sent successfully",
  "email_id": "msg_abc123xyz"
}
```

**Final Workflow State after Node 3:**

```json
{
  "inputs": {
    "api_url": "https://api.example.com/users/123",
    "recipient_email": "admin@company.com"
  },
  "nodes": {
    "fetch_data": {
      "status_code": 200,
      "response_body": {
        "id": 123,
        "name": "John Doe",
        "email": "john@example.com",
        "status": "active"
      }
    },
    "analyze_user": {
      "content": "This user John Doe appears to be an active account holder in good standing."
    },
    "send_report": {
      "message": "Email sent successfully",
      "email_id": "msg_abc123xyz"
    }
  }
}
```

**What you can now reference:**

* ✅ All workflow inputs
* ✅ All outputs from all executed nodes
* ✅ `{{send_report.message}}` → `"Email sent successfully"`
* ✅ `{{send_report.email_id}}` → `"msg_abc123xyz"`

***

### 📊 STEP 5: Workflow Completes

**If no output mapping is defined:**

The workflow returns the last node's output:

```json
{
  "message": "Email sent successfully",
  "email_id": "msg_abc123xyz"
}
```

**If output mapping is defined:**

```json
{
  "output_mapping": {
    "user_name": "{{fetch_data.response_body.name}}",
    "analysis": "{{analyze_user.content}}",
    "email_status": "{{send_report.message}}"
  }
}
```

The workflow returns:

```json
{
  "user_name": "John Doe",
  "analysis": "This user John Doe appears to be an active account holder in good standing.",
  "email_status": "Email sent successfully"
}
```

***

### Key Observations from This Example

**1. Data Accumulates as You Go:**

```
After Node 1: Can reference → inputs + fetch_data
After Node 2: Can reference → inputs + fetch_data + analyze_user
After Node 3: Can reference → inputs + fetch_data + analyze_user + send_report
```

**2. Cannot Reference Future Nodes:**

* At Node 1, you CANNOT use `{{analyze_user.content}}` (hasn't run yet)
* At Node 2, you CANNOT use `{{send_report.message}}` (hasn't run yet)

**3. String Interpolation:**

* `"Name is {{fetch_data.response_body.name}}"` → `"Name is John Doe"`
* Numbers become strings: If `id` was in the string, `"ID: {{fetch_data.response_body.id}}"` → `"ID: 123"`
* Objects become JSON: `"Data: {{fetch_data.response_body}}"` → `"Data: {\"id\":123,\"name\":\"John Doe\"...}"`

**4. Exact Field Names Matter:**

* ✅ `{{fetch_data.response_body}}` (correct - matches `ApiCallNodeOutput`)
* ❌ `{{fetch_data.response}}` (wrong - field doesn't exist)
* ✅ `{{analyze_user.content}}` (correct - matches `AskClaudeOutput`)
* ❌ `{{analyze_user.response}}` (wrong - field doesn't exist)

**5. Check Node Documentation:**

* Each node type has specific input and output field names
* Always refer to [Node Reference](/reference/nodes) for exact field names

***

## Summary

**Key Takeaways:**

**Data Flow:**

1. ✅ Workflows execute top-to-bottom, data flows linearly between nodes
2. ✅ Each node can access workflow inputs and outputs from previous nodes
3. ✅ Use `{{...}}` syntax to reference data from inputs and previous nodes

**Type Handling:** 4. ✅ All fields in workflow inputs, node inputs, and node outputs have defined types 5. ✅ Types must match when passing values between nodes 6. ✅ Type mismatches cause runtime errors, not design-time warnings 7. ✅ Check node detail pages to see input/output types

**Automatic Conversions:** 8. ✅ When embedded in strings, all values auto-convert to strings 9. ✅ Objects and arrays become JSON strings: `"Data: {{obj}}"` works 10. ✅ Numbers become text: `"Count: {{num}}"` works

**Manual Conversions:** 11. ✅ Use `string_to_json` to parse JSON strings to objects/arrays 12. ✅ Use `run_javascript` or `run_python_code` for complex transformations 13. ✅ Use dot notation and array indexing to extract specific values

**Best Practices:** 14. ✅ Test workflows incrementally to catch type errors early 15. ✅ Use explicit field access: `{{api.response.data.id}}` vs `{{api.response}}`

**Remember:** When in doubt, check the node's detail page for exact input/output types!

***


# Variables

Variables serve as secure, reusable containers for values across your automation ecosystem. Instead of hardcoding API keys, configuration settings, or email addresses into every single step, you can define them once as **Variables** and reference them anywhere.

## Why Use Variables?

* **Centralized Control**: Update an API key or setting in one place, and it instantly updates across all your workflows and agents.
* **Security**: Use **Secret Variables** to encrypt sensitive data (like passwords and API tokens). These values are masked in logs and never exposed in the UI.
* **Portability**: Build workflows that act differently based on the environment or team without changing the workflow structure.

***

## Variable Scopes

Where you define a variable determines where it can be used. AgenticFlow offers four levels of scoping:

### 1. Project Variables (Global)

* **Access**: Available to **everything** in the project (all Workflows, Agents, and Workforces).
* **Best For**: Global API keys (OpenAI, Stripe), database credentials, or company-wide settings (e.g., `brand_color`).
* **Syntax**: `{{ var.project.variable_name }}`

### 2. Workflow Variables

* **Access**: Available only within the specific **Workflow** where they are defined.
* **Best For**: Workflow-specific defaults (e.g., `default_retry_count`, `admin_email_recipient`).
* **Syntax**: `{{ var.workflow.variable_name }}`

### 3. Agent Variables

* **Access**: Available only to a specific **Agent**.
* **Best For**: Personality settings, agent-specific memory limits, or distinct tool credentials for that agent.
* **Syntax**: `{{ var.agent.variable_name }}`

### 4. Workforce Variables

* **Access**: Available to all agents within a specific **Workforce** (Multi-Agent Team).
* **Best For**: Shared goals, team-specific resources, or coordination parameters.
* **Syntax**: `{{ var.mas.variable_name }}`

***

Có 2 loại variable bao gồm:

* System Variables
* Creating & Configuring Variables

## System Variables (Read-Only)

AgenticFlow automatically provides "System Variables" for every execution. These are read-only values that give you context about "who, what, and when" the automation is running.

**Syntax**: `{{ sys.variable_name }}`

| Variable              | Description                                 | Example Output              |
| --------------------- | ------------------------------------------- | --------------------------- |
| `sys.user_id`         | ID of the user who triggered the run        | `usr_8x92...`               |
| `sys.project_id`      | ID of the current project                   | `proj_ab12...`              |
| `sys.workflow_id`     | ID of the current workflow                  | `wf_abc123...`              |
| `sys.workflow_run_id` | Unique ID for this specific execution       | `run_xyz789...`             |
| `sys.triggered_by`    | How the run started (manual, schedule, API) | `manual`                    |
| `sys.timestamp`       | Current Unix timestamp (seconds)            | `1705680123`                |
| `sys.datetime`        | Current ISO datetime                        | `2024-01-19T10:30:00+00:00` |
| `sys.date`            | Current date (YYYY-MM-DD)                   | `2024-01-19`                |
| `sys.time`            | Current time (HH:MM:SS)                     | `10:30:00`                  |

***

## Creating & Configuring Variables

When adding a new variable in the Settings panel, you will configure:

### Data Types

* **String**: Text values (e.g., "Welcome to AgenticFlow").
* **Number**: Decimal numbers (e.g., `0.75`).
* **Integer**: Whole numbers (e.g., `42`).
* **Boolean**: True/False usage flags.

### Special Properties

* **Secret**: **Crucial for security**. Checks this box to encrypt the value. It will be hidden from the UI after creation and masked in all execution logs.
* **Read-only**: Prevents the variable from being modified during runtime.
* **Required**: The workflow will refuse to start if this variable is empty.

<figure><img src="/files/YsZdlXIzlAyo5EmwrUEk" alt=""><figcaption></figcaption></figure>

***

## How to Use Variables

You can use variables in almost any input field in the AgenticFlow builder by typing `#` to reference a variable. A dropdown list will appear—scroll to the bottom to find the variables you’ve created.<br>

{% embed url="<https://www.loom.com/share/bdfb1ff61b5e4e0cafd75db2066922fd>" %}

If `#` doesn’t work in a specific field, try using the double curly brace syntax: `{{ }}`.

### Syntax Cheat Sheet

| Type          | Syntax                             |
| ------------- | ---------------------------------- |
| **Project**   | `{{ var.project.your_var_name }}`  |
| **Workflow**  | `{{ var.workflow.your_var_name }}` |
| **Agent**     | `{{ var.agent.your_var_name }}`    |
| **Workforce** | `{{ var.mas.your_var_name }}`      |
| **System**    | `{{ sys.your_sys_var }}`           |

### Common Examples

**1. Using a Secure API Key in a Header** Instead of pasting your key directly, reference the secret project variable:

```json
{
  "Authorization": "Bearer {{ var.project.openai_api_key }}"
}
```

**2. Dynamic File Naming** Create unique filenames automatically using system date and run IDs:

```
invoice_{{ sys.date }}_{{ sys.workflow_run_id }}.pdf
```

*Result: `invoice_2024-01-19_run_xyz789.pdf`*

**3. Conditional Logic** Use a Boolean variable to control workflow paths:

```
{{ var.workflow.is_debug_mode }} == true
```


# Workflow Inputs


# Text Input

The Text Input control allows a user to provide a short line of text when running a workflow.

A **Text Input** is a fundamental input control that allows a user to enter a single line of text when they run a workflow. It is suitable for short pieces of text like a name, a search query, or a topic for content generation.

## How to Add

1. From your workflow's **Build** page, click on **+ Add Input** in the main canvas or the sidebar.
2. Select **Text Input** from the list of available controls.

## Configuration

When you add a Text Input control, you can configure the following settings:

* **Title:** The main label for the input field that the user will see.
* **Description:** Optional helper text that appears below the title to provide more context.
* **Variable Name:** The name used to access this input's value within the workflow. You can rename this by clicking on the green variable name at the bottom left of the control.
* **Optional/Required:** A toggle to specify whether the user must fill in this field before running the workflow.

## Setting a Default Value

You can pre-fill the Text Input with a default value:

1. Enter the desired default text into the input field.
2. Click the settings icon (⚙️) at the bottom right of the control.
3. Select **Set Current Value as Default**.

## Accessing the Value

To use the text provided by the user, you reference its variable name within double curly braces `{{}}`. For example, if the variable name is `topic`:

* **In most nodes:** You can directly use `{{topic}}` in a prompt or parameter field.
* **In a Code Node (Python):** You would access it as a variable, e.g., `topic = "{{topic}}"`
* **In a JavaScript step:** You would access it via `params.topic`.

### Example

If you create a **Text Input** with the variable name `product_name`, you could use it in a downstream OpenAI node like this:

```
Write a 50-word marketing description for the following product: {{product_name}}
```


# Long Text Input

The Long Text Input control allows a user to provide a large block of text when running a workflow.

A **Long Text Input** is an input control that provides a larger text area, allowing a user to enter multiple lines or paragraphs of text when they run a workflow.

## When to Use

This control is ideal for longer pieces of content, such as:

* An email body
* An article or blog post
* A transcript
* Detailed feedback or instructions

## How to Add

1. From your workflow's **Build** page, click on **+ Add Input**.
2. Select **Long Text Input** from the list of available controls.

## Configuration

* **Title:** The main label for the input field.
* **Description:** Optional helper text to provide more context.
* **Variable Name:** The name used to access this input's value within the workflow.
* **Optional/Required:** A toggle to specify if the user must provide this input.

## Setting a Default Value

You can pre-fill the Long Text Input with a default value:

1. Enter the desired default text into the text area.
2. Click the settings icon (⚙️) at the bottom right of the control.
3. Select **Set Current Value as Default**.

## Accessing the Value

You access the value using its variable name in double curly braces `{{}}`. For example, if the variable name is `customer_feedback`:

* **In most nodes:** Use `{{customer_feedback}}`.
* **In a Code Node (Python):** Access as a variable, e.g., `feedback = "{{customer_feedback}}"`
* **In a JavaScript step:** Access via `params.customer_feedback`.

### Example

If you create a **Long Text Input** with the variable name `article_text`, you could use it in a downstream OpenAI node to summarize the content:

```
Please provide a three-sentence summary of the following article:

{{article_text}}
```


# Number Input

The Number Input control allows a user to provide a numeric value when running a workflow.

A **Number Input** is an input control that allows a user to enter a numeric value. This ensures the input is treated as a number, not a string, making it suitable for calculations, comparisons, and other numerical operations.

## When to Use

This control is ideal for any input that requires a number, such as:

* A quantity or count (e.g., number of articles to generate).
* A threshold or limit.
* A score or rating.
* Any value that will be used in a mathematical calculation.

## How to Add

1. From your workflow's **Build** page, click on **+ Add Input**.
2. Select **Number Input** from the list of available controls.

## Configuration

* **Title:** The main label for the input field.
* **Description:** Optional helper text to provide more context.
* **Variable Name:** The name used to access this input's value.
* **Optional/Required:** A toggle to specify if the user must provide this input.

## Setting a Default Value

You can pre-fill the Number Input with a default value:

1. Enter the desired default number into the input field.
2. Click the settings icon (⚙️) at the bottom right of the control.
3. Select **Set Current Value as Default**.

## Accessing the Value

You access the value using its variable name in double curly braces `{{}}`. For example, if the variable name is `item_count`:

* **In most nodes:** Use `{{item_count}}`.
* **In a Code Node (Python):** The value will be injected as a string, so you may need to convert it to a number, e.g., `count = int("{{item_count}}")`.
* **In a JavaScript step:** Access via `params.item_count`.

### Example

**Goal:** Generate a specific number of new product ideas.

1. **Add a Number Input:**
   * Title: "Number of Ideas"
   * Variable Name: `num_ideas`
   * Default Value: `5`
2. **Add a Text Input:**
   * Title: "Product Category"
   * Variable Name: `category`
3. **Add an OpenAI MCP Node:**
   * **Action:** `Chat`
   * **Prompt:** `Generate a list of {{num_ideas}} new product ideas for the following category: {{category}}.`

When this workflow runs, it will use the number provided in the "Number of Ideas" input to generate the requested number of product ideas.


# Checkbox

The Checkbox control allows a user to provide a simple true/false or on/off input.

A **Checkbox** is a simple input control that allows a user to provide a boolean (true/false) value. It's a straightforward way to capture a binary "yes/no" or "on/off" decision.

## When to Use

Use a Checkbox control for any input that has only two states:

* Enabling or disabling a feature (e.g., "Include summary?").
* Agreeing to terms and conditions.
* Confirming an action (e.g., "Are you sure?").

## How to Add

1. From your workflow's **Build** page, click on **+ Add Input**.
2. Select **Checkbox** from the list of available controls.

## Configuration

* **Title:** The main label for the checkbox.
* **Description:** Optional helper text to provide more context about what the checkbox controls.
* **Variable Name:** The name used to access the `true` or `false` value.
* **Optional/Required:** A toggle to specify if the user must interact with the checkbox.

## Setting a Default Value

You can set the default state of the checkbox to be either checked or unchecked:

1. Click the checkbox in the control to set your desired default state (checked for `true`, unchecked for `false`).
2. Click the settings icon (⚙️) at the bottom right of the control.
3. Select **Set Current Value as Default**.

## Accessing the Value

The Checkbox control outputs either `true` (if checked) or `false` (if unchecked). You can access this value using its variable name. This is most powerful when used with an **If/Else Node** to control the workflow's path.

### Example

**Goal:** Allow a user to optionally request an executive summary when generating a report.

1. **Add a Checkbox Control:**
   * Title: "Include Executive Summary"
   * Variable Name: `include_summary`
   * Default Value: `false` (unchecked)
2. **Add a Long Text Input:**
   * Title: "Source Data"
   * Variable Name: `source_data`
   * Content: `[...some long report data...]`
3. **Add an If/Else Node:**
   * **Condition:** `{{include_summary}} == true`
   * This will check if the user ticked the box.
4. **On the "True" Branch:**
   * **Add an OpenAI MCP Node:**
     * **Action:** `Chat`
     * **Prompt:** `Create a full report and a one-paragraph executive summary from the following data: {{source_data}}`
5. **On the "False" Branch:**
   * **Add an OpenAI MCP Node:**
     * **Action:** `Chat`
     * **Prompt:** `Create a full report from the following data: {{source_data}}`

This workflow now dynamically changes its behavior based on the simple check of a box.


# Select Dropdown

The Select control allows a user to choose a single option from a predefined list in a dropdown menu.

The **Select** control (also known as a dropdown) is an input component that lets a user choose a single option from a list that you define.

## When to Use

Use the Select control when you want to restrict a user's choice to a specific set of options. This is useful for:

* Selecting a category (e.g., `Marketing`, `Sales`, `Support`).
* Choosing an action to perform (e.g., `Summarize`, `Translate`, `Rewrite`).
* Setting a specific mode or parameter (e.g., `Fast`, `Balanced`, `High Quality`).

## How to Add

1. From your workflow's **Build** page, click on **+ Add Input**.
2. Select **Select** from the list of available controls.

## Configuration

* **Title:** The main label for the dropdown field.
* **Description:** Optional helper text to provide more context.
* **Options:** This is where you define the items that will appear in the dropdown. Add one option per line.
* **Variable Name:** The name used to access the user's selected value.
* **Optional/Required:** A toggle to specify if the user must make a selection.

## Setting a Default Value

You can pre-select one of the options as the default:

1. Add all your desired options to the **Options** list.
2. From the dropdown menu in the control, select the option you want to be the default.
3. Click the settings icon (⚙️) at the bottom right of the control.
4. Select **Set Current Value as Default**.

## Accessing the Value

You access the selected option using its variable name in double curly braces `{{}}`. For example, if the variable name is `analysis_type`:

* You can use `{{analysis_type}}` in a prompt or parameter field.
* You can use it as the input to a **Switch Node** to route the workflow down different paths based on the user's selection.

### Example

**Goal:** Allow a user to choose a language and then translate a piece of text into that language.

1. **Add a Select Control:**
   * Title: "Target Language"
   * Variable Name: `target_language`
   * Options:

     ```
     Spanish
     French
     German
     ```
2. **Add a Long Text Input:**
   * Title: "Text to Translate"
   * Variable Name: `source_text`
3. **Add an OpenAI MCP Node:**
   * **Action:** `Chat`
   * **Prompt:** \`Translate the following text into {{target\_language}}:

     {{source\_text}}\`

Now, when a user runs the workflow, they can pick a language from the dropdown, and that choice will be used to generate the correct translation prompt.


# Multi-Select

The Multi Select control allows a user to choose multiple options from a predefined list.

The **Multi Select** control is an input component that allows a user to select one or more options from a list of predefined choices, typically presented as checkboxes.

## When to Use

Use the Multi Select control when you want to allow the user to choose any number of options from a list. This is useful for:

* Selecting multiple features to include in a report.
* Choosing several topics to write about.
* Tagging an item with multiple categories.
* Specifying a list of recipients for a notification.

## How to Add

1. From your workflow's **Build** page, click on **+ Add Input**.
2. Select **Multi Select** from the list of available controls.

## Configuration

* **Title:** The main label for the group of choices.
* **Description:** Optional helper text to provide more context.
* **Options:** This is where you define the items that will appear as choices. Add one option per line.
* **Variable Name:** The name used to access the list of the user's selected values.
* **Optional/Required:** A toggle to specify if the user must make at least one selection.

## Setting Default Values

You can pre-select any number of options as the default:

1. Add all your desired options to the **Options** list.
2. Check the boxes next to the options you want to be selected by default.
3. Click the settings icon (⚙️) at the bottom right of the control.
4. Select **Set Current Value as Default**.

## Accessing the Value

The Multi Select control outputs a **list (or array) of strings**, where each string is one of the selected options. You access this list using its variable name in double curly braces `{{}}`.

For example, if the variable name is `features`:

* The value of `{{features}}` would look like `["SEO Analysis", "Competitor Tracking"]`.
* You can pass this directly to an LLM, which can iterate through the list in its response.
* In a **Map Node**, you can use this list as the input to run a sub-workflow for each selected feature.

### Example

**Goal:** Allow a user to select multiple social media platforms and then draft a post for each one.

1. **Add a Multi Select Control:**
   * Title: "Select Platforms"
   * Variable Name: `platforms`
   * Options:

     ```
     Twitter
     LinkedIn
     Facebook
     ```
2. **Add a Long Text Input:**
   * Title: "Core Message"
   * Variable Name: `message`
3. **Add a Map Node:**
   * **Input List:** `{{platforms}}`
   * **Sub-Workflow:**
     * **Sub-Node 1: OpenAI MCP**
       * **Action:** `Chat`
       * **Prompt:** \`Rewrite the following message to be appropriate for the {{item}} platform:

         {{message}}\`
       * **Note:** `{{item}}` refers to the individual platform name for each iteration (e.g., "Twitter").
4. **Add a Save to File Node:**
   * **Content:** The collected list of drafted posts will be saved: `{{map_1.output}}`


# Image Select

The Image Select control allows a user to choose an option from a visually-driven list of items, each with an image.

The **Image Select** control (also known as a carousel) is an input component that allows a user to select a single option from a horizontal list of choices, where each choice is represented by an image and a title.

## When to Use

Use the Image Select control when a visual representation of the options can help the user make a more intuitive and informed decision. It is ideal for:

* Choosing a style or template (e.g., for image or video generation).
* Selecting a product type from a visual catalog.
* Picking a character or avatar.
* Any scenario where the options are best understood visually rather than with text alone.

## How to Add

1. From your workflow's **Build** page, click on **+ Add Input**.
2. Select **Image Select** from the list of available controls.

## Configuration

* **Title:** The main label for the Image Select component.
* **Description:** Optional helper text to provide more context.
* **Items:** This is where you configure the choices for the carousel. For each item, you must provide:
  * **Image:** Upload an image to represent the option.
  * **Title:** A short text label that appears below the image.
  * **Value:** The actual text value that will be passed into the workflow when this option is selected.
* **Variable Name:** The name used to access the `Value` of the user's selected item.
* **Optional/Required:** A toggle to specify if the user must make a selection.

## Setting a Default Value

You can pre-select one of the images as the default choice:

1. After configuring all your items, click on the image in the carousel that you want to be the default.
2. Click the settings icon (⚙️) at the bottom right of the control.
3. Select **Set Current Value as Default**.

## Accessing the Value

You access the **Value** of the selected item using its variable name. For example, if you have an item with `Title: "Vintage"` and `Value: "vintage_style_v1"` and the variable name is `image_style`, the value of `{{image_style}}` will be `vintage_style_v1`.

### Example

**Goal:** Allow a user to select a visual style and then generate an image using that style.

1. **Add an Image Select Control:**
   * Title: "Select Image Style"
   * Variable Name: `selected_style`
   * **Items:**
     * Item 1: Image of a futuristic city, Title: `Futuristic`, Value: `cyberpunk, futuristic, neon lights`
     * Item 2: Image of a watercolor painting, Title: `Watercolor`, Value: `watercolor art style, soft, blended colors`
     * Item 3: Image of a cartoon drawing, Title: `Cartoon`, Value: `bold lines, vibrant colors, cartoon style`
2. **Add a Text Input:**
   * Title: "Image Subject"
   * Variable Name: `subject`
3. **Add an OpenAI MCP Node (DALL-E):**
   * **Action:** `Create Image`
   * **Prompt:** `A high-quality image of a {{subject}} in the following style: {{selected_style}}`

When the user runs this workflow, they can click on one of the style images, and the corresponding value (e.g., "cyberpunk, futuristic, neon lights") will be inserted into the DALL-E prompt.


# Upload Image

The Upload Image control allows a user to upload an image file when running a workflow.

The **Upload Image** control is an input component that allows a user to upload an image file (e.g., JPEG, PNG) when they run a workflow. The uploaded image is then accessible via a temporary URL that can be used by downstream nodes.

## When to Use

Use the Upload Image control for any workflow that needs to process or analyze a user-provided image. Common use cases include:

* Analyzing the content of an image with a vision-capable LLM.
* Extracting text from an image (OCR).
* Resizing or modifying an image.
* Using an image as a source or reference for generating other content.

## How to Add

1. From your workflow's **Build** page, click on **+ Add Input**.
2. Select **Upload Image** from the list of available controls.

## Configuration

* **Title:** The main label for the file upload field.
* **Description:** Optional helper text to provide more context.
* **Variable Name:** The name used to access the URL of the uploaded image.
* **Optional/Required:** A toggle to specify if the user must upload an image.

## Accessing the Value

After the user uploads an image, this control outputs a temporary, secure URL pointing to that image. This URL is accessible via the variable name you assigned.

For example, if the variable name is `source_image`, the value of `{{source_image}}` will be a URL (e.g., `https://cdn.agenticflow.ai/.../image.png`).

**Note:** For security, this URL expires after a few days. It is intended for immediate processing within the workflow run, not for permanent storage.

### Example

**Goal:** Allow a user to upload a picture of a meal and get its nutritional information.

1. **Add an Upload Image Control:**
   * Title: "Upload a Photo of Your Meal"
   * Variable Name: `meal_photo_url`
2. **Add an OpenAI MCP Node (GPT-4 Vision):**
   * **Action:** `Analyze Image Content`
   * **Image URL:** `{{meal_photo_url}}`
   * **Prompt:** `Analyze the attached image of a meal. Identify the food items and provide an estimated nutritional breakdown (calories, protein, carbs, fat).`

When a user uploads an image and runs this workflow, the image URL is sent to the vision model, which then analyzes the image and provides the requested information based on the prompt.




---

[Next Page](/llms-full.txt/1)