For coding agents

Overview

There are three entry points an agent can use, in increasing order of integration:

Authoring best practices

When a workflow is developed as code, keep its editable JSON in the application repository. Git is the authoring history, the Chatterfly draft is the latest mutable platform copy, and each deployment is an immutable record of what ran. A dashboard save is not a replacement for source control: undeployed draft history cannot be recovered.

edit local JSON → validate → review → deploy → trigger a test run
                                              ↓
                         inspect the immutable deployment snapshot

Live converse authoring

Coding agents should always author adaptive conversations as Agent[mode="converse"]. Runtime selection is derived from the effective participant surface after inheritance resolves. A Live-capable Gemini voice surface uses one persistent audio session; other surfaces use the existing turn-based collector. There is no live_converse mode.

Parallel authoring

Use Parallel only for a small, static set of independent branches. Branches read frozen parent state, write under their branch ID, and cannot reference sibling-local output while they run. Read output after the join as {{parallel_id.branch_id.step_id}}.

Load the Parallel execution guide before authoring joins, failure policy, or recovery operations.

llms.txt & DSL reference

Every Chatterfly deployment serves an llms.txt discovery file plus the full DSL reference as plain Markdown. All URLs are derived from your app origin.

$APP_URL/llms.txt                 # discovery entry point
$APP_URL/llms/dsl-authoring.md    # workflow-as-code best practices
$APP_URL/llms/dsl-core.md         # execution model, state, IDs
$APP_URL/llms/dsl-nodes.md        # node table + field specs
$APP_URL/llms/dsl-conditions.md   # condition expression syntax
$APP_URL/llms/dsl-input-fields.md # input_type variants
$APP_URL/llms/dsl-hitl.md         # human-in-the-loop model
$APP_URL/schemas/workflow.json    # JSON schema
$APP_URL/openapi.yaml             # management API spec

AGENTS.md

When workflow definitions live in your repository, drop an AGENTS.md at the root so agents pick up the operational rules automatically. Adapt this starter to your workflow paths and deployment policy:

# Chatterfly workflow authoring

- Workflow JSON under `workflows/` is the authoring source of truth. Edit the local file; do not treat the Chatterfly draft as version history.
- Before authoring, load the Chatterfly DSL references needed for the nodes, conditions, inputs, HITL, surfaces, or providers involved.
- Never author `dsl_version`. Use PascalCase node types and sibling-unique node IDs.
- Use stable logical connection slugs. Never put tokens, keys, OAuth data, deployment bindings, or environment-specific connection IDs in workflow JSON.
- Default to the `widget` surface. Discover surface capabilities before using voice, messaging, forms, uploads, or other gated nodes.
- Author multi-turn collection as `Agent[mode="converse"]`. Never invent a `live_converse` mode; the resolved participant surface selects the runtime.
- Orient people before a new interaction task. Add a participant-facing `Message` before a Repeater, form, upload, review, handoff, or converse Agent when the next prompt alone lacks context. Do not narrate node types or duplicate a clear prompt.
- Use `Input.validation` for immediate participant correction and Agent `output_schema` / `output_validation` for model repair. The host application must revalidate completed output before persistence or side effects.
- For mutations: collect, validate, show a review, obtain explicit confirmation, then call the mutating Tool. Keep privileged and multi-participant workflows private.
- Validate the exact local definition and fix every error before create, update, or deploy. Trigger a test run after deployment.
- Inspect immutable deployment snapshots to verify what is or was live. Do not infer runtime state from the mutable draft.
- Use workflow IDs for latest-live embeds, stable `cfw_` keys for server integrations, and deployment IDs only for deliberate pinning, canary, or rollback.

MCP server

The backend can expose a Model Context Protocol server over streamable HTTP at /mcp.

The tools are thin clients over the management API. Authenticate with a personal access token (cfpat_…) — create one in the dashboard under Settings → API tokens. The token is bound to one workspace, so no X-Tenant-IDheader is needed. Chatterfly Cloud's MCP endpoint is https://api.chatterfly.in/mcp.

Claude Code requires type: "http" for remote servers; the example below is valid in its project-scoped .mcp.json configuration.

{
  "mcpServers": {
    "chatterfly": {
      "type": "http",
      "url": "https://api.chatterfly.in/mcp",
      "headers": {
        "Authorization": "Bearer ${CHATTERFLY_TOKEN}"
      }
    }
  }
}

Available tools:

Native providers

Discover provider products and capabilities before authoring tools; never guess operation names, scopes, or provider hosts. For Zoho, uselist_connection_operations andget_connection_metadata, bind logical slugs at deploy time, and load get_dsl_referencewith section zoho for the maintained LLM reference.

Validation endpoint

The validation endpoint has no side effects — agents can call it as often as needed while iterating. It runs the same engine validators as the save path plus a DSL-version gate.

curl -X POST "$CHATTERFLY_API_URL/api/management/workflows/validate" \
  -H "Authorization: Bearer $CHATTERFLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "definition": { /* workflow JSON */ } }'

The response shape is { valid, dsl_version, errors[], warnings[] }, where each issue carries { path, code, message, severity }. When present, path is the offending workflow node ID and can be used to focus the editor or repair the definition.

Before selecting inline ephemeral bulk execution, inspect a target workflow with GET /api/management/workflows/{id}/ephemeral-eligibility. It returns every nested node that can suspend, create durable work, or communicate with a participant. The runtime repeats that check against the pinned deployment before execution.