Delete AI Agent

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 agent's pipe/table to delete it.
3. Feature Toggle: The organization must have AI Agents feature enabled via toggle.
4. Agent UUID: Identify the AI Agent to delete. See Get an AI Agent by UUID or Retrieve AI Agents to find agent UUIDs.

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: Delete an AI Agent

Basic example (delete agent by UUID)

Inputs

• uuid: The agent UUID to delete (required).

mutation {
  deleteAiAgent(input: {
    uuid: "agent-uuid-123"
  }) {
    success
    errors
  }
}

Response:

{
  "data": {
    "deleteAiAgent": {
      "success": true,
      "errors": null
    }
  }
}

Response explained

• success: Boolean indicating whether the deletion was successful.
• errors: Array of error messages if deletion failed, or null if successful.

Error handling

If the agent doesn't exist or you don't have permission to delete it, you'll receive an error response:

{
  "data": {
    "deleteAiAgent": null
  },
  "errors": [
    {
      "message": "Resource Not Found - Couldn't find Agent with uuid agent-uuid-123",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "deleteAiAgent"
      ]
    }
  ]
}

Error response explained

• data.deleteAiAgent: Returns null when the operation fails.
• errors: Array containing error details when the operation fails.
• errors[].message: Human-readable error description.

If deletion fails but the agent exists, the response might include errors in the errors field:

{
  "data": {
    "deleteAiAgent": {
      "success": false,
      "errors": [
        "Cannot delete agent: Agent is currently in use"
      ]
    }
  }
}

Tips

• Permanent action: Deletion is irreversible. Consider disabling the agent first using Update AI Agent Status if you might need to restore it later.
• Error handling: Always check the success field and errors array in the response to handle potential errors gracefully.