Update 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

Authentication: Use a Service Account token (Personal Access Tokens are deprecated).
Permissions: You must be admin of the agent's pipe/table (and of the new pipe/table if moving the agent).
Feature Toggle: The organization must have AI Agents feature enabled via toggle.
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

Basic example (update agent name and instruction)

Inputs

uuid: The agent UUID to update (required).
agent.name: Updated display name for the agent (required).
agent.repoUuid: UUID of the pipe/table the agent belongs to (required).
agent.instruction: Updated instruction for the agent (optional).
agent.dataSourceIds: Updated list of data source IDs (optional).
agent.behaviors: Updated list of behaviors (optional).
agent.disabledAt: Timestamp to disable the agent (optional).

mutation {
  updateAiAgent(input: {
    uuid: "agent-uuid-123"
    agent: {
      name: "Updated Customer Support Agent"
      repoUuid: "pipe-uuid-123"
      instruction: "Updated instruction: Help customers with inquiries and escalate complex issues"
      dataSourceIds: ["ds-1", "ds-3"]
    }
  }) {
    agent {
      uuid
      name
      instruction
      repoUuid
      dataSourceIds
      updatedAt
    }
  }
}

Response:

{
  "data": {
    "updateAiAgent": {
      "agent": {
        "uuid": "agent-uuid-123",
        "name": "Updated Customer Support Agent",
        "instruction": "Updated instruction: Help customers with inquiries and escalate complex issues",
        "repoUuid": "pipe-uuid-123",
        "dataSourceIds": ["ds-1", "ds-3"],
        "updatedAt": "2025-01-20T15:00:00Z"
      }
    }
  }
}

Response explained

agent.uuid: The agent identifier (unchanged).
agent.name: Updated display name for the agent.
agent.instruction: Updated instruction for the agent.
agent.repoUuid: UUID of the pipe/table (can be changed to move the agent to a different pipe/table).
agent.dataSourceIds: Updated list of data source IDs.
agent.updatedAt: When the agent was last updated.

Moving an agent to a different pipe/table

You can move an agent to a different pipe/table by updating the repoUuid:

mutation {
  updateAiAgent(input: {
    uuid: "agent-uuid-123"
    agent: {
      name: "Customer Support Agent"
      repoUuid: "pipe-uuid-456"
      instruction: "Help customers with their inquiries"
    }
  }) {
    agent {
      uuid
      name
      repoUuid
      updatedAt
    }
  }
}

Error handling

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

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

Error response explained

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

Tips

Partial updates: You can update individual fields. Only include the fields you want to change, but remember that name and repoUuid are required. However, behaviors not sent in the updating of an agent will be deleted.
Error handling: Always check the errors array in the response to handle potential errors gracefully.