Get an AI Agent by UUID

Before You Begin

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

Prerequisites

You must have admin permission on the agent's pipe or table.
The organization must have the AI Agents feature enabled.
You need the agent UUID. Use the aiAgents query to list agents and find the UUID:

{
  aiAgents(repoUuid: "1cc2bce3-1ea3-4af0-8fe9-0b899c73ae84") {
    edges {
      node {
        uuid
        name
      }
    }
  }
}

Query an AI Agent

Basic example

query aiAgent($uuid: ID!) {
  aiAgent(uuid: $uuid) {
    uuid
    name
    instruction
    repoUuid
    dataSourceIds
    disabledAt
    createdAt
    updatedAt
  }
}

Variables:

{
  "uuid": "bfcf25c0-afcf-40db-8a63-04094620c1e8"
}

Full query including behaviors

The behaviors field exposes the full configuration of each behavior, including event params, conditions, and AI action details.

query aiAgent($uuid: ID!) {
  aiAgent(uuid: $uuid) {
    uuid
    name
    instruction
    repoUuid
    dataSourceIds
    disabledAt
    createdAt
    updatedAt
    behaviors {
      id
      name
      active
      event_id
      action_id
      event_params {
        to_phase_id
        fromPhaseId
        inPhaseId
        triggerFieldIds
        kindOfSla
        triggerAutomationId
        phase {
          uuid
          name
          deletedAt
        }
      }
      condition {
        expressions_structure
        expressions {
          id
          field_address
          operation
          value
          structure_id
        }
      }
      action_params {
        aiBehaviorParams {
          dataSourceIds
          instruction
          referencedFieldIds
          actionsAttributes {
            id
            name
            actionType
            referenceId
            metadata {
              destinationPhaseId
              pipeId
              tableId
              emailTemplateId
              allowTemplateModifications
              emailTemplate {
                id
                name
                deletedAt
              }
              pipe {
                id
                name
                deletedAt
              }
              phase {
                id
                name
                deletedAt
              }
              fieldsAttributes {
                fieldId
                inputMode
                value
              }
            }
          }
          capabilitiesAttributes {
            capabilityType
            enabled
          }
        }
      }
    }
  }
}

Response:

{
  "data": {
    "aiAgent": {
      "uuid": "bfcf25c0-afcf-40db-8a63-04094620c1e8",
      "name": "Comments Summary Agent",
      "instruction": "Summarize card comments and update fields.",
      "repoUuid": "1cc2bce3-1ea3-4af0-8fe9-0b899c73ae84",
      "dataSourceIds": ["93779687-19d5-42dd-8b8a-e8b75e1c12dd"],
      "disabledAt": null,
      "createdAt": "2025-01-20T10:00:00Z",
      "updatedAt": "2025-01-20T15:00:00Z",
      "behaviors": [
        {
          "id": "305992651",
          "name": "Summarize comments when card moves",
          "active": false,
          "event_id": "card_moved",
          "action_id": "ai_behavior",
          "event_params": {
            "to_phase_id": "338796240",
            "fromPhaseId": null,
            "inPhaseId": null,
            "triggerFieldIds": null,
            "kindOfSla": null,
            "triggerAutomationId": null,
            "phase": {
              "uuid": "980ee9b1-c9ea-4d56-b427-03e752c0a9d1",
              "name": "Doing",
              "deletedAt": null
            }
          },
          "condition": {
            "expressions_structure": [],
            "expressions": []
          },
          "action_params": {
            "aiBehaviorParams": {
              "dataSourceIds": ["93779687-19d5-42dd-8b8a-e8b75e1c12dd"],
              "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"],
              "actionsAttributes": [
                {
                  "id": "74b6f9e8-de85-417b-9abd-5040019f8f5b",
                  "name": "Update card fields",
                  "actionType": "update_card",
                  "referenceId": "63637099-d172-4196-b46a-1864ed61e685",
                  "metadata": {
                    "destinationPhaseId": "",
                    "pipeId": "306422123",
                    "tableId": null,
                    "emailTemplateId": null,
                    "allowTemplateModifications": null,
                    "emailTemplate": null,
                    "pipe": {
                      "id": "306422123",
                      "name": "Sample Pipe",
                      "deletedAt": null
                    },
                    "phase": null,
                    "fieldsAttributes": [
                      {
                        "fieldId": "421679209",
                        "inputMode": "fill_with_ai",
                        "value": ""
                      }
                    ]
                  }
                },
                {
                  "id": "0e73ad94-496c-4fa1-99e2-089f880ed6ca",
                  "name": "Move card",
                  "actionType": "move_card",
                  "referenceId": "88eb26bc-c838-41a7-a8f7-4f6c3df337a4",
                  "metadata": {
                    "destinationPhaseId": "338796241",
                    "pipeId": "306422123",
                    "tableId": null,
                    "emailTemplateId": null,
                    "allowTemplateModifications": null,
                    "emailTemplate": null,
                    "pipe": {
                      "id": "306422123",
                      "name": "Sample Pipe",
                      "deletedAt": null
                    },
                    "phase": {
                      "id": "338796241",
                      "name": "Done",
                      "deletedAt": null
                    },
                    "fieldsAttributes": []
                  }
                }
              ],
              "capabilitiesAttributes": null
            }
          }
        }
      ]
    }
  }
}

Response explained

Agent fields:

Field	Description
`uuid`	Unique identifier for the agent.
`name`	Display name.
`instruction`	Agent-level system instruction, applies to all behaviors unless overridden.
`repoUuid`	UUID of the pipe or table the agent belongs to.
`dataSourceIds`	UUIDs of knowledge bases configured for this agent.
`disabledAt`	`null` when the agent is active; a timestamp when disabled.
`createdAt`	When the agent was created.
`updatedAt`	When the agent was last updated.

Behavior fields:

Field	Description
`id`	Numeric automation ID for this behavior. Used as the behavior `id` in update mutations.
`name`	Display name of the behavior.
`active`	Whether the behavior is currently enabled.
`event_id`	Trigger event identifier. Same values as regular automations (e.g., `"card_moved"`).
`action_id`	Always `"ai_behavior"`.

eventParams fields:

Field	Description
`to_phase_id`	Phase ID for `card_moved` and `all_children_in_phase` events.
`fromPhaseId`	Phase ID for `card_left_phase`.
`inPhaseId`	Phase ID for `card_inbox_received_email`.
`triggerFieldIds`	Field IDs for `field_updated`.
`kindOfSla`	SLA state for `sla_based` (`"late"`, `"expired"`, `"overdue"`).
`triggerAutomationId`	Automation ID for `http_response_received`.
`phase`	Resolved phase object for the configured phase ID. Includes `uuid`, `name`, and `deletedAt`.

condition fields:

Field	Description
`expressions_structure`	Logical grouping of expression IDs. Empty array means no condition filter is applied.
`expressions`	Array of condition expressions. Each has `field_address`, `operation`, `value`, `structure_id`.

actionParams.aiBehaviorParams fields:

Field	Description
`dataSourceIds`	Knowledge base UUIDs for this behavior. Overrides the agent-level `dataSourceIds` when set.
`instruction`	The AI prompt. May contain `%{field:ID}` (field references) and `%{action:UUID}` (action calls).
`referencedFieldIds`	Field IDs and slugs referenced in the instruction via `%{field:...}`.
`actionsAttributes`	Array of actions the AI can perform. See below.
`capabilitiesAttributes`	Array of enabled capabilities, or `null` if none are configured.

actionsAttributes item fields:

Field	Description
`id`	UUID identifying this action instance. Pass as `id` in update mutations to update the action in place.
`name`	Display name.
`actionType`	`"create_card"`, `"update_card"`, `"move_card"`, or `"send_email_template"`.
`referenceId`	UUID used to call this action from the instruction via `%{action:REFERENCE_ID}`.
`metadata`	Action configuration. See below.

metadata fields:

Field	Description
`destinationPhaseId`	Target phase ID for `move_card`.
`pipeId`	Pipe ID context for the action.
`tableId`	Table ID context (when applicable).
`emailTemplateId`	Email template ID for `send_email_template`.
`allowTemplateModifications`	Whether the AI can modify the email template content.
`pipe`	Resolved pipe object (`id`, `name`, `deletedAt`).
`phase`	Resolved phase object (`id`, `name`, `deletedAt`). `null` when not applicable.
`emailTemplate`	Resolved email template object. `null` when not applicable.
`fieldsAttributes`	Field mappings for `update_card` and `create_card`. Each item: `fieldId`, `inputMode`, `value`.