Retrieve AI Agents

Before You Begin

🔗 Use the GraphQL Playground to execute the queries in this guide.

➡️ New to GraphQL? Learn how to navigate the Playground with our Playground Basics Guide.

Prerequisites

Authentication: Use a Service Account token (Personal Access Tokens are deprecated).
Permissions: You must be admin of the pipe/table.
Feature Toggle: The organization must have AI Agents feature enabled via toggle.
Repo UUID: Identify the pipe/table to retrieve agents from.

Step 1: Find Your Repo UUID

See our Get resource IDs page for how to find the pipe UUID.

Step 2: Query AI Agents

Use the aiAgents query to retrieve a paginated list of AI agents in a pipe/table. Below is an example:

{
  aiAgents(repoUuid: "pipe-uuid-123") {
    edges {
      node {
        uuid
        name
        instruction
        repoUuid
        createdAt
        updatedAt
        lastExecution
        needReview
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Available filters and sorting

The aiAgents query also accepts filters and sorting that can be used individually or combined:

Filtering

filter.byName: Filter agents by name (partial match).
filter.byStatus: Filter agents by status (e.g., "active", "disabled").

{
  aiAgents(
    repoUuid: "pipe-uuid-123"
    filter: {
      byName: "customer"
      byStatus: "active"
    }
  ) {
    edges {
      node {
        uuid
        name
        instruction
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Sorting

The agents list can also be sorted using the sort property:

sort.by: Field to sort by (includes name and last_execution, etc.).
sort.order: Sort direction - asc for ascending or desc for descending.

{
  aiAgents(
    repoUuid: "pipe-uuid-123"
    sort: {
      by: NAME
      order: ASC
    }
  ) {
    edges {
      node {
        uuid
        name
        createdAt
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Pagination

first: Number of items to return (default: 10).
after: Cursor for pagination - use the endCursor from the previous response (default: '0').

{
  aiAgents(
    repoUuid: "pipe-uuid-123"
    first: 20
    after: "cursor-from-previous-page"
  ) {
    edges {
      node {
        uuid
        name
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Listing agents with their behaviors

Each agent's behaviors can be requested directly from the list, with the same fields the
aiAgent query exposes. A behavior carries its own trigger (event_id and
event_params) and, under action_params.aiBehaviorParams, the instruction the agent follows and
the actions it is allowed to take.

{
  aiAgents(repoUuid: "pipe-uuid-123") {
    edges {
      node {
        uuid
        name
        behaviors {
          id
          name
          active
          event_id
          event_params {
            to_phase_id
            fromPhaseId
            inPhaseId
            triggerFieldIds
          }
          action_params {
            aiBehaviorParams {
              uuid
              instruction
              actionsAttributes {
                actionType
                metadata {
                  destinationPhaseId
                  pipeId
                  tableId
                }
              }
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Behaviors are stored in a separate service and are fetched per agent, so this selection is heavier
than the rest of the query. Request it only when you need it, and keep first small when you do.

Key Fields Explained:

The aiAgents query uses pagination. Refer to our Pagination basics page to understand more about how it works.

uuid: Agent unique identifier.
name: Name of the agent.
instruction: Custom instruction for the agent.
repoUuid: UUID of the pipe/table the agent belongs to.
behaviors: The behaviors of the agent, with the same shape as in the aiAgent query. It is null for an agent that has no behaviors. See Listing agents with their behaviors.
dataSourceIds: List of data source IDs (knowledge base) for the agent.
disabledAt: Timestamp when the agent was disabled (null if active).
createdAt: When the agent was created.
updatedAt: When the agent was last updated.
lastExecution: Timestamp of the last execution.
needReview: Indicates if the agent needs review.

Step 3: Execute and Interpret the Response

After running the query, you'll receive a structured JSON response. Here's an example:

{
  "data": {
    "aiAgents": {
      "edges": [
        {
          "node": {
            "uuid": "agent-uuid-123",
            "name": "Customer Support Agent",
            "instruction": "Help customers with inquiries",
            "repoUuid": "pipe-uuid-123",
            "createdAt": "2025-01-15T10:00:00Z",
            "updatedAt": "2025-01-20T14:30:00Z",
            "lastExecution": "2025-01-20T14:25:00Z",
            "needReview": false
          }
        },
        {
          "node": {
            "uuid": "agent-uuid-456",
            "name": "Document Processing Agent",
            "instruction": "Process and categorize documents",
            "repoUuid": "pipe-uuid-123",
            "createdAt": "2025-01-16T09:00:00Z",
            "updatedAt": "2025-01-19T11:20:00Z",
            "lastExecution": "2025-01-19T11:15:00Z",
            "needReview": true
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": "MQ"
      }
    }
  }
}

This query provides a quick and effective way to retrieve information about all AI agents in a pipe/table with filtering, sorting, and pagination support.