--- agentTools: projectIndex: https://developers.pipefy.com/llms.txt --- # AI Behavior Actions Reference for actionsAttributes in AI agent behaviors ## Overview `actionsAttributes` in `actionParams.aiBehaviorParams` defines the actions an AI agent can perform when a behavior runs. Each entry is one action the agent may call. The behavior's `instruction` must reference every action via `%{action:REFERENCE_ID}`. *** ## Action fields | Field | Type | Required | Description | | ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `actionType` | string | Yes | Determines what the agent does. See [Action types](#action-types). | | `name` | string | Yes | Display name for this action. | | `referenceId` | string | Yes | UUID you assign to this action. Must be a valid UUID format and unique within the behavior. Used in the instruction via `%{action:REFERENCE_ID}`. | | `id` | string | No | Existing action UUID. Include this when updating an existing action via `updateAiAgent`. | | `metadata` | object | No | Action-specific configuration. See [Metadata fields](#metadata-fields) and each action type below. | *** ## Metadata fields All metadata fields are optional at the input level, but certain fields are required by specific action types: | Field | Type | Used by | | ---------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `pipeId` | string | `move_card`, `update_card`, `create_card`, `create_connected_card` | | `tableId` | string | `create_table_record` | | `destinationPhaseId` | string | `move_card` (required), `create_card`, `create_connected_card`, `create_table_record` (optional — card goes to default phase if omitted) | | `fieldsAttributes` | array of objects | `update_card`, `create_card`, `create_connected_card`, `create_table_record` | | `emailTemplateId` | string | `send_email_template` | | `allowTemplateModifications` | boolean | `send_email_template` | | `mcpServerId` | string | `mcp_tool` (required) | | `toolName` | string | `mcp_tool` (required) | | `toolInputs` | array of objects | `mcp_tool` (optional) | *** ## fieldsAttributes Defines how each field on the target card is populated. Each item has: | Field | Type | Required | Description | | ----------- | ------ | -------- | -------------------------------------------------------------------------------------------------------- | | `fieldId` | string | Yes | Internal ID of the field to populate. See [Get Resource IDs](https://developers.pipefy.com/reference/get-resource-ids) → Field internal\_id. | | `inputMode` | string | Yes | How the value is determined. See below. | | `value` | string | No | Source or static value. Required for `copy_from` and `fixed_value`. Pass `""` for `fill_with_ai`. | **`inputMode` values:** | Value | Description | | -------------- | ----------------------------------------------------------------------------------- | | `fill_with_ai` | The AI generates a value for this field based on the behavior instruction. | | `copy_from` | Copies the value from another field. Set `value` to the source field's internal ID. | | `fixed_value` | Uses a hardcoded static value. Set `value` to the literal text. | *** ## toolInputs Pre-set values for individual parameters of an MCP tool (used by `mcp_tool`). Include **only** the parameters you want to fix — any parameter you omit is decided by the AI at runtime. Only top-level tool parameters are supported. Pre-set parameters are hidden from the model, so it cannot override them. | Field | Type | Required | Description | | --------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | Yes | The tool parameter name, exactly as exposed by the MCP tool's input schema. | | `source` | enum | Yes | How the value is supplied. See below. | | `value` | JSON | Conditional | The literal value, used as-is. Required when `source` is `fixed_value`. Accepts any JSON type (string, number, boolean, array, object). | | `fieldId` | string | Conditional | A field internal ID, or a card attribute key (`title`, `id`, `uuid`). Required when `source` is `card_field`. Resolved when the agent runs. | **`source` values:** | Value | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `fixed_value` | Injects the literal `value` exactly as provided. | | `card_field` | Resolves `fieldId` against the triggering card at execution time: first a field whose internal ID matches, otherwise a card attribute (`title`/`id`/`uuid`). | *** ## Action types ### `move_card` Moves the current card to a specific phase. **Required metadata:** `destinationPhaseId`, `pipeId` ``` { name: "Move to Review" actionType: "move_card" referenceId: "88eb26bc-c838-41a7-a8f7-4f6c3df337a4" metadata: { destinationPhaseId: "342876484" pipeId: "307108581" } } ``` *** ### `update_card` Updates fields on the current card. **Required metadata:** `fieldsAttributes` (at least one entry) ``` { name: "Fill summary fields" actionType: "update_card" referenceId: "63637099-d172-4196-b46a-1864ed61e685" metadata: { fieldsAttributes: [ { fieldId: "428299825" inputMode: "fill_with_ai" value: "" }, { fieldId: "428299828" inputMode: "fixed_value" value: "Reviewed" }, { fieldId: "428299830" inputMode: "copy_from" value: "413928300" } ] } } ``` *** ### `create_card` Creates a new card in a pipe. **Required metadata:** `pipeId` **Optional metadata:** `destinationPhaseId` (card goes to the pipe's default phase if omitted), `fieldsAttributes` ``` { name: "Create follow-up card" actionType: "create_card" referenceId: "b031aebf-985c-48d2-b3ee-a5e09c9df591" metadata: { pipeId: "306422123" destinationPhaseId: "" fieldsAttributes: [ { fieldId: "413928300" inputMode: "fill_with_ai" value: "" } ] } } ``` *** ### `create_connected_card` Creates a card in a pipe that is connected to the current pipe. **Required metadata:** `pipeId` (the connected pipe) **Optional metadata:** `destinationPhaseId`, `fieldsAttributes` ``` { name: "Create connected card" actionType: "create_connected_card" referenceId: "2186f683-da4c-4f96-a954-089176d2a534" metadata: { pipeId: "302959103" fieldsAttributes: [ { fieldId: "371542895" inputMode: "fill_with_ai" value: "" } ] } } ``` *** ### `create_table_record` Creates a new record in a database table. **Required metadata:** `tableId` **Optional metadata:** `fieldsAttributes` ``` { name: "Create table record" actionType: "create_table_record" referenceId: "6c2584d9-0f0d-4702-8ae7-f4bf83bf8ba2" metadata: { tableId: "301619858" fieldsAttributes: [ { fieldId: "324912126" inputMode: "fill_with_ai" value: "" } ] } } ``` *** ### `send_email_template` Sends an email using a pre-configured email template. **Required metadata:** `emailTemplateId` **Optional metadata:** `allowTemplateModifications` — when `true`, the AI can modify the template content before sending. ``` { name: "Send email template" actionType: "send_email_template" referenceId: "1e35d489-65ef-488a-8954-9e60d79c4b1b" metadata: { emailTemplateId: "309545798" allowTemplateModifications: true } } ``` *** ### `mcp_tool` Invokes a tool exposed by a connected MCP server. Requires the `agents_with_mcp_tools` feature to be enabled for the organization. **Required metadata:** `mcpServerId`, `toolName` **Optional metadata:** `toolInputs` — pre-set values for individual tool parameters. See [toolInputs](#toolinputs). Any parameter not listed is filled by the AI at runtime. ``` { name: "Create calendar event" actionType: "mcp_tool" referenceId: "f0a1c2d3-4e5f-6789-abcd-ef0123456789" metadata: { mcpServerId: "b8c1e2f3-1234-4abc-9def-0123456789ab" toolName: "create_event" toolInputs: [ { name: "location" source: "fixed_value" value: "HQ — Room 4" }, { name: "calendar_id" source: "card_field" fieldId: "428299825" }, { name: "subject" source: "card_field" fieldId: "title" } ] } } ``` *** ## Notes * Every action must be referenced in the behavior instruction via `%{action:REFERENCE_ID}`. An instruction without at least one action reference will fail validation. * `referenceId` must be a valid UUID format (e.g., `"88eb26bc-c838-41a7-a8f7-4f6c3df337a4"`). It does not need to match any existing record — it is a label you choose and use in the instruction. * When updating an existing action via `updateAiAgent`, include the action's `id` (a UUID returned by the API). Actions without an `id` are created as new. * `fieldsAttributes` with `inputMode: "fill_with_ai"` instructs the agent to populate that field autonomously based on the behavior instruction. You do not need to reference those fields explicitly in the instruction, but you can. * `toolInputs` (on `mcp_tool`) pre-sets only the parameters you list; omit a parameter to let the AI decide it. A pre-set parameter is hidden from the model and cannot be overridden by it. With `source: "card_field"`, a numeric `fieldId` resolves to that field's value on the triggering card, while keys like `title`/`id`/`uuid` resolve to the corresponding card attribute. ## See also * [Create AI Agent](https://developers.pipefy.com/reference/create-ai-agent) * [Update AI Agent](https://developers.pipefy.com/reference/update-ai-agent) * [Automation Events Parameters](https://developers.pipefy.com/reference/events-params) * [Conditions](https://developers.pipefy.com/reference/conditions) * [Get Resource IDs](https://developers.pipefy.com/reference/get-resource-ids)