Get an AI Agent by UUID

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. Agent UUID: Identify the AI Agent to retrieve details from.

Step 1: Find Your Agent UUID

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

1. Via Pipefy UI

• Open the AI Agent in your browser.
• The URL will include the Agent UUID.

2. Via GraphQL Query

• Use the aiAgents query to list agents and find the UUID:

{
  aiAgents(repoUuid: "pipe-uuid-123") {
    edges {
      node {
        uuid
        name
      }
    }
  }
}

Step 2: Query AI Agent

Use the aiAgent query to retrieve an AI agent by its UUID. Below is an example:

{
  aiAgent(uuid: "agent-uuid-123") {
    uuid
    name
    instruction
    repoUuid
    behaviors {
      id
      name
    }
    dataSourceIds
    disabledAt
    createdAt
    updatedAt
    lastExecution
    needReview
  }
}

Key Fields Explained:

• 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: List of behaviors (automations) associated with the agent.
• 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, due to some missing information.

Step 3: Execute and Interpret the Response

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

{
  "data": {
    "aiAgent": {
      "uuid": "agent-uuid-123",
      "name": "Customer Support Agent",
      "instruction": "Help customers with their inquiries",
      "repoUuid": "pipe-uuid-123",
      "behaviors": [
        {
          "id": "1",
          "name": "Respond to Customer"
        }
      ],
      "dataSourceIds": ["ds-1", "ds-2"],
      "disabledAt": null,
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-20T14:30:00Z",
      "lastExecution": "2025-01-20T14:25:00Z",
      "needReview": false
    }
  }
}

This query provides a quick and effective way to retrieve detailed information about a specific AI agent.