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

1. Authentication: Use a Service Account token (Personal Access Tokens are deprecated).
2. Permissions: You must be admin of the pipe/table.
3. Feature Toggle: The organization must have AI Agents feature enabled via toggle.
4. 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
    }
  }
}

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: For this query, we do not provide support for listing the behaviors, so the result is always null; use the individual aiAgent query instead.
• 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.