Create AI Agent

Before You Begin

• Use the GraphQL Playground.
• Authenticate with a Service Account token.

Prerequisites

• You must have admin permission on the pipe or table where you want to create the agent.
• The organization must have the AI Agents feature enabled.
• You need the pipe or table UUID. See Get Resource IDs → Pipe UUID.

Create an AI Agent

Basic example (agent without behaviors)

Inputs

• agent.name: Display name for the agent (required).
• agent.repoUuid: UUID of the pipe or table the agent belongs to (required).
• agent.instruction: Agent-level system instruction (optional). Applies to all behaviors unless overridden at the behavior level.
• agent.dataSourceIds: IDs of knowledge bases the agent can query for additional context (optional). See Knowledge Bases.
• agent.disabledAt: Pass null to create the agent as enabled. If omitted, the agent is created in a disabled state.

mutation {
  createAiAgent(input: {
    agent: {
      name: "Customer Support Agent"
      repoUuid: "1cc2bce3-1ea3-4af0-8fe9-0b899c73ae84"
      instruction: "You help customers with their inquiries. Be concise and accurate."
      dataSourceIds: ["93779687-19d5-42dd-8b8a-e8b75e1c12dd"]
      disabledAt: null
    }
  }) {
    agent {
      uuid
      name
      instruction
      repoUuid
      dataSourceIds
      disabledAt
    }
  }
}

Response:

{
  "data": {
    "createAiAgent": {
      "agent": {
        "uuid": "bfcf25c0-afcf-40db-8a63-04094620c1e8",
        "name": "Customer Support Agent",
        "instruction": "You help customers with their inquiries. Be concise and accurate.",
        "repoUuid": "1cc2bce3-1ea3-4af0-8fe9-0b899c73ae84",
        "dataSourceIds": ["93779687-19d5-42dd-8b8a-e8b75e1c12dd"],
        "disabledAt": null
      }
    }
  }
}

Response explained

• agent.uuid: Unique identifier for the created agent.
• agent.name / instruction: Echoed from input.
• agent.repoUuid: UUID of the pipe or table.
• agent.dataSourceIds: Knowledge base IDs configured for this agent.
• agent.disabledAt: null means the agent is active; a timestamp means it is disabled.

Behaviors

Behaviors define when an AI agent acts and what it does. Each behavior is an automation-like object: it has a trigger event and an AI instruction that can reference card fields and call specific actions. The actionId for all behaviors is always "ai_behavior".

Behavior input structure

Note: Behaviors inherit the agent's repoUuid as both the event and action repo. You do not need to specify event_repo_id or action_repo_id.

actionParams.aiBehaviorParams

Instruction syntax

The instruction string supports two types of references:

Field references — %{field:FIELD_ID_OR_SLUG} — reads the value of a card field or attribute when the behavior runs:

• %{field:413928300} — reads a pipe field by its internal ID
• %{field:all_comments} — reads a card attribute by its slug (e.g., all comments on the card)
• See Automation Actions Parameters → Card Attributes for all available slugs

List each field ID or slug used in the instruction in referencedFieldIds as well.

Action references — %{action:REFERENCE_ID} — tells the AI to execute a specific action from actionsAttributes:

• %{action:88eb26bc-c838-41a7-a8f7-4f6c3df337a4} — calls the action whose referenceId matches this UUID
• You can reference multiple actions in the same instruction
• The referenceId in each action entry is the UUID you define and use here

Event params

Behavior eventParams follow the exact same structure as regular automation events. See Automation Events Parameters for the full reference.

Conditions

The optional condition field works identically to automation conditions. Pass { expressions: [], expressions_structure: [] } for no filter. See Conditions for the full reference.

Behavior actions

Each entry in actionsAttributes defines one action the AI can perform. The actionType determines what the agent does and which metadata fields apply.

Capabilities

Optional capabilities that can be enabled per behavior:

capabilitiesAttributes: [
  { capabilityType: web_search, enabled: true }
]

capabilityType is a GraphQL enum — pass the value unquoted (e.g., web_search, not "web_search").

Knowledge Bases

dataSourceIds accepts UUIDs of knowledge base data sources that provide additional context to the agent. Data sources can be configured at the agent level (applies to all behaviors) or at the behavior level (overrides the agent-level setting for that behavior).

Note: Mutations and queries to manage knowledge base data sources will be documented in a future update.

Create an agent with behaviors

mutation {
  createAiAgent(input: {
    agent: {
      name: "Comments Summary Agent"
      repoUuid: "1cc2bce3-1ea3-4af0-8fe9-0b899c73ae84"
      instruction: "Summarize card comments and update fields."
      dataSourceIds: ["93779687-19d5-42dd-8b8a-e8b75e1c12dd"]
      disabledAt: null
      behaviors: [
        {
          name: "Summarize comments when card moves"
          actionId: "ai_behavior"
          eventId: "card_moved"
          active: true
          eventParams: {
            to_phase_id: "338796240"
          }
          condition: {
            expressions_structure: []
            expressions: []
          }
          actionParams: {
            aiBehaviorParams: {
              instruction: "Read the field %{field:all_comments} and update the card with the summary of those comments, executing the action %{action:63637099-d172-4196-b46a-1864ed61e685} and executing the action %{action:88eb26bc-c838-41a7-a8f7-4f6c3df337a4}"
              referencedFieldIds: ["all_comments"]
              dataSourceIds: ["93779687-19d5-42dd-8b8a-e8b75e1c12dd"]
              actionsAttributes: [
                {
                  name: "Move card"
                  actionType: "move_card"
                  referenceId: "88eb26bc-c838-41a7-a8f7-4f6c3df337a4"
                  metadata: {
                    destinationPhaseId: "338796241"
                    pipeId: "306422123"
                    fieldsAttributes: []
                  }
                },
                {
                  name: "Update card fields"
                  actionType: "update_card"
                  referenceId: "63637099-d172-4196-b46a-1864ed61e685"
                  metadata: {
                    pipeId: "306422123"
                    fieldsAttributes: [
                      {
                        fieldId: "421679209"
                        inputMode: "fill_with_ai"
                        value: ""
                      }
                    ]
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }) {
    agent {
      uuid
      name
      instruction
      repoUuid
      disabledAt
      behaviors {
        id
        name
        active
        event_id
        action_id
      }
    }
  }
}

Error handling

{
  "data": {
    "createAiAgent": null
  },
  "errors": [
    {
      "message": "Record Not Saved - Validation failed: Name can't be blank",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["createAiAgent"]
    }
  ]
}

• data.createAiAgent: Returns null when the operation fails.
• errors[].message: Human-readable error description including validation details.

Tips

• Pass disabledAt: null to create an enabled agent. If omitted, the agent is created disabled.
• Behaviors inherit the agent's repoUuid as their repo — no need to specify event_repo_id or action_repo_id.
• Each action's referenceId is a UUID you choose. Use it in the instruction via %{action:UUID} to tell the AI when to call that action.
• List every field ID or slug used in the instruction in referencedFieldIds as well.
• dataSourceIds on a behavior overrides the agent-level dataSourceIds for that specific behavior.

See also

• Update AI Agent
• AI Behavior Actions
• Conditions
• Automation Events Parameters
• Get Resource IDs