workflows-ai-by-zapier · v0.1.0 · 2026-09-04 · sha256 5d6cc9dd8346dfdd

workflows-ai-by-zapier v0.1.0A

Immutable. This exact content never changes and is served at /api/v1/blob/5d6cc9dd8346dfdd.

---
name: workflows-ai-by-zapier
description: Configure a bounded AI by Zapier step in a durable workflow, including prompt-only semantic work, structured outputs, integration or web tools, and knowledge sources. Use when a workflow must summarize, extract meaning, classify, generate, analyze, disambiguate, or let AI choose and refine searches.
license: MIT
metadata:
author: zapier
version: "0.1.0"
sdk_cli_min: "0.67.4"
sdk_cli_validated: "0.67.5"
refresh_source: "zapier/agent-skills"
---

# AI by Zapier Workflow Steps

Use this companion with `workflows-create` or `workflows-modify`; it configures the bounded AI step but does not replace the workflow lifecycle. If the request involves creating, testing, publishing, or enabling a complete workflow and neither lifecycle skill is loaded, load the appropriate one first.

## SDK CLI discovery

Use the public SDK CLI's live catalog before writing the AI step:

- Find the current implementation: `zapier-sdk list-apps --search "AI by Zapier" --json`.
- Inspect actions: `zapier-sdk list-actions <appKey> --json`.
- Inspect fields: `zapier-sdk list-action-input-fields <appKey> <actionType> <actionKey> --json`.
- Resolve dependent choices: `zapier-sdk list-action-input-field-choices` with the settled parent inputs.
- Resolve an embedded app's connection: `zapier-sdk list-connections <appKey> --owner me --json`.

For `tools[].auth_id`, accept only the positive integer connection ID required by the live schema. If connection discovery returns only a UUID or other public ID, do not coerce it, substitute an alias, or guess the numeric ID; report that this SDK version cannot safely configure that authenticated tool.

Use the exact command signatures shown by the installed CLI's `--help`; command flags may evolve. Record the discovered implementation, action, fields, choices, defaults, and connection metadata so you do not repeat calls or substitute remembered values.

Configure a bounded AI by Zapier step inside a durable workflow. This skill owns AI by Zapier configuration; the workflow skill still owns the trigger, deterministic graph, testing, deployment, and verification.

## Confirm the bounded step

Use prompt-only AI by Zapier when the trigger and previous steps already contain all evidence. Add an embedded read or search tool only when the model must choose a query, inspect the result, and adapt or repeat the lookup. If the query is known before execution, keep the search as an ordinary workflow step.

Keep predetermined side effects — messages, emails, CRM updates, rows, tasks, and approvals — as durable steps after the AI returns typed output. Embed a write action only when the write genuinely belongs inside the bounded decision loop, its allowed effects are narrow, and the user approved that behavior. Variable-length output alone is not a reason to embed writes: return a typed array and let durable code perform them.

## Discover the current action and defaults

Discover AI by Zapier's current versioned implementation, actions, and fields before authoring the call. Derive `sdk.runAction`'s unversioned `appKey` from the discovered implementation and use the discovered action type and key. Re-fetch dependent fields after settling parent values such as authentication or provider.

Use the discovered `get_completion` action for both prompt-only and tool-enabled work. Never run `get_completion_agentic`; it is an administrative restriction action, not the agentic execution path. Tools and knowledge sources belong on `get_completion`.

Resolve model configuration in this order:

1. Honor an explicit managed tier using its exact writable sentinel: `standard/auto`, `advanced/auto`, or `premium/auto`.
2. If the user names a provider or concrete model, settle `provider_id`, then discover valid `model_id` and `authentication_id` values. Explain when it requires the user's provider connection and billing.
3. Otherwise use the non-null `model_id` and `authentication_id` defaults returned by the live `get_completion` fields.

Never invent a near-match such as `standard`, `basic`, `standard/default`, a remembered vendor slug, an empty value, or a connection ID. Do not set `provider_id` for a managed-tier sentinel unless the live fields require it.

AI by Zapier normally carries its own action-level authentication input rather than a workflow connection alias. The literal `"0"` is valid only when returned as the managed-auth default by live discovery; it is not a general fallback for provider or embedded app connections.

## Separate instructions from runtime context

Configure the action according to its live schema:

- `instructions` — the stable task, constraints, tool-use rules, and return contract.
- `inputFields` — runtime values from the trigger and earlier steps; serialize nested values when the field requires strings.
- `tools` — only the bounded capabilities the model may invoke.
- `knowledgeSources` — exact supported source entries resolved through the available product surface.
- `outputFields` — flat typed fields consumed by later durable steps.
- `isOutputArray` — `true` only when the intended result is genuinely a list.

Pass only the context needed for the task. Do not interpolate all runtime data into `instructions` or replace the stable task at runtime.

After discovery, a prompt-only structured call should have this shape; replace every angle-bracketed value with a literal returned by discovery:

```typescript
const analysis = await ctx.step("analyze-with-ai", async () =>
sdk.runAction({
appKey: "<discovered-unversioned-app-key>",
actionType: "write",
actionKey: "get_completion",
inputs: {
authentication_id: "<discovered-authentication>",
model_id: "<discovered-model>",
instructions: "Classify the supplied text and explain the decision.",
inputFields: { source_text: input.text },
outputFields: [
{
name: "category",
description: "The selected category.",
type: "category_single",
isRequired: true,
options: ["match", "no_match"],
},
{
name: "reason",
description: "A concise explanation grounded in the supplied text.",
type: "text",
isRequired: true,
},
],
isOutputArray: false,
},
}),
);
```

Prefer `outputFields` over legacy `outputSchema`; never configure both. Use only output types accepted by the live field schema, and provide `options` for category fields. Keep `tools`, `knowledgeSources`, and `outputFields` as directly inspectable object and array literals inside `runAction.inputs`, not hidden behind builders, spreads, or dynamic assembly.

Without structured output, read the generated text from `result.data[0].output`. With `outputFields`, read the configured fields from `result.data[0]`. Test the real result before finalizing downstream mappings, especially for array output.

## Configure integration tools from discovery

An app action embedded in AI by Zapier is an `integration` tool, not a builtin. Copy its identifiers, metadata, fields, labels, and connection from live discovery:

```typescript
tools: [
{
type: "integration",
id: "<stable-unique-tool-id>",
selected_api: "<discovered-versioned-implementation>",
action_key: "<discovered-action-key>",
action_type: "<discovered-action-type>",
display_name: "<discovered-app-and-action-name>",
description: "<discovered-action-description>",
app_needs_auth: true,
auth_id: 123456, // Illustrative only; replace with the discovered numeric connection ID.
inputs: {
query: { type: "guess" },
status: { type: "locked", value: "open" },
},
input_labels: { status: "Open" },
approval_policy: "always_allow",
},
]
```

The placeholders illustrate shape only; every concrete value must come from the selected account's current app, action, field, choice, and connection results. Set `app_needs_auth: true` when a selected connection proves the app requires authentication, `false` when the surface identifies it as connectionless, or `null` when the surface does not expose that metadata; never guess `false`. Configure each relevant action field deliberately:

- `locked` — a fixed user-supplied or resolved value.
- `guess` — a value the model must choose at runtime.
- `guess-locked` — the model may choose only from the supplied values.
- `default` — use the action's declared default.
- `ignore` — deliberately omit the field.

Do not leave a search tool's `inputs` empty and expect instructions to supply fields the tool schema never exposed. Set an explicit `approval_policy`: use `always_allow` for an approved read/search capability; keep consequential writes outside AI by Zapier by default, or use `require_approval` when an embedded write genuinely needs review.

Normal workflow actions use connection aliases. An integration tool's numeric `auth_id` is a narrow schema-owned exception that does not accept a workflow alias. Use the selected connection's numeric ID from discovery. Use `auth_id: 0` only when discovery says the embedded app is connectionless, never for authenticated apps.

## Configure builtins and knowledge sources

Use only builtin names accepted by the live `tools` schema. Prefer its concrete `web_search` and `web_scrape` capabilities for durable source; do not assume the editor's `browse_web` shorthand is itself a runtime builtin. Builtins still need unique stable `id` values.

Knowledge sources are separate from integration tools. Resolve the user's named source through the available surface and pass its exact returned configuration in `knowledgeSources`; never pass a raw ID in place of that configuration. Modern entries are objects containing `integrationId`; string entries are legacy encoded objects, not plain IDs.

If the surface cannot resolve a requested tool connection, action field, model, or knowledge source, report the limitation instead of guessing.

## Return to the workflow lifecycle

After the AI step is configured, return to the loaded workflow skill. Test it inside the complete durable source so runtime `inputFields`, embedded tools, output shape, deterministic continuation, and side effects are exercised together.