Update AI Agent Status

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.
3. Feature Toggle: The organization must have AI Agents feature enabled via toggle.
4. Agent UUID: Identify the AI Agent to update. 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: Update an AI Agent Status

Basic example (disable an agent)

Inputs

• uuid: The agent UUID to update (required).
• active: Boolean to enable (true) or disable (false) the agent (required).

mutation {
  updateAiAgentStatus(input: {
    uuid: "agent-uuid-123"
    active: false
  }) {
    success
  }
}

Response:

{
  "data": {
    "updateAiAgentStatus": {
      "success": true
    }
  }
}

Response explained

• success: Boolean indicating whether the status update was successful.

Example (enable an agent)

To enable a previously disabled agent:

mutation {
  updateAiAgentStatus(input: {
    uuid: "agent-uuid-123"
    active: true
  }) {
    success
  }
}

Response:

{
  "data": {
    "updateAiAgentStatus": {
      "success": true
    }
  }
}

Error handling

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

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

Error response explained

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

Tips

• Temporary disable: Use active: false to temporarily disable an agent instead of deleting it. This allows you to re-enable it later without losing configuration.
• Status vs deletion: Disabling an agent (active: false) is reversible, while deletion is permanent. Consider disabling before deleting if you might need to restore the agent.
• Error handling: Always check the success field and errors array in the response to handle potential errors gracefully.