AI Behavior Actions

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

---

Metadata fields

All metadata fields are optional at the input level, but certain fields are required by specific action types:

---

fieldsAttributes

Defines how each field on the target card is populated. Each item has:

inputMode values:

---

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.

source values:

---

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. 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
• Update AI Agent
• Automation Events Parameters
• Conditions
• Get Resource IDs