Update AI Agent

Before You Begin

Use the GraphQL Playground.
Authenticate with a Service Account token.

Prerequisites

You must have admin permission on the agent's pipe or table (and on the new pipe or table if moving the agent).
The organization must have the AI Agents feature enabled.
You need the agent UUID. Query it using the aiAgents query:

{
  aiAgents(repoUuid: "1cc2bce3-1ea3-4af0-8fe9-0b899c73ae84") {
    edges {
      node {
        uuid
        name
      }
    }
  }
}

Update an AI Agent

Inputs

uuid: The agent UUID to update (required).
agent.name: Updated display name (required).
agent.repoUuid: UUID of the pipe or table (required). Change this to move the agent to a different pipe or table.
agent.instruction: Updated agent-level instruction (optional).
agent.dataSourceIds: Updated list of knowledge base IDs (optional). See Create AI Agent → Knowledge Bases.
agent.disabledAt: Pass null to enable the agent; pass a timestamp to disable it (optional).
agent.behaviors: Updated list of behaviors (optional). If included, any existing behavior whose id is not in the list will be deleted.

Basic example (update agent name and instruction)

mutation {
  updateAiAgent(input: {
    uuid: "bfcf25c0-afcf-40db-8a63-04094620c1e8"
    agent: {
      name: "Updated Customer Support Agent"
      repoUuid: "1cc2bce3-1ea3-4af0-8fe9-0b899c73ae84"
      instruction: "Help customers with inquiries. Escalate complex issues to a human agent."
      dataSourceIds: ["93779687-19d5-42dd-8b8a-e8b75e1c12dd"]
      disabledAt: null
    }
  }) {
    agent {
      uuid
      name
      instruction
      repoUuid
      dataSourceIds
      disabledAt
    }
  }
}

Response:

{
  "data": {
    "updateAiAgent": {
      "agent": {
        "uuid": "bfcf25c0-afcf-40db-8a63-04094620c1e8",
        "name": "Updated Customer Support Agent",
        "instruction": "Help customers with inquiries. Escalate complex issues to a human agent.",
        "repoUuid": "1cc2bce3-1ea3-4af0-8fe9-0b899c73ae84",
        "dataSourceIds": ["93779687-19d5-42dd-8b8a-e8b75e1c12dd"],
        "disabledAt": null
      }
    }
  }
}

Response explained

agent.uuid: The agent identifier (unchanged).
agent.name / instruction: Updated values.
agent.repoUuid: UUID of the pipe or table. Can be changed to move the agent.
agent.dataSourceIds: Updated list of knowledge base IDs.
agent.disabledAt: null means the agent is active.

Important: When behaviors is omitted from the update and disabledAt is not passed, the agent is automatically disabled (because there are no active behaviors in the request). Always pass disabledAt: null explicitly if you want the agent to remain active when updating only name, instruction, or other fields.

Updating behaviors

The behaviors field follows the same input structure as in Create AI Agent. When behaviors is included in the update:

Behaviors with an id matching an existing behavior are updated in place.
Behaviors without an id are created as new.
Existing behaviors whose id is not present in the list are deleted.

If you omit behaviors entirely, existing behaviors are left unchanged.

Update an existing behavior

Pass the behavior's numeric id (automation ID) to update it. Any behavior IDs not included in the list will be deleted.

mutation {
  updateAiAgent(input: {
    uuid: "bfcf25c0-afcf-40db-8a63-04094620c1e8"
    agent: {
      name: "Comments Summary Agent"
      repoUuid: "1cc2bce3-1ea3-4af0-8fe9-0b899c73ae84"
      dataSourceIds: ["93779687-19d5-42dd-8b8a-e8b75e1c12dd"]
      behaviors: [
        {
          id: "305992651"
          name: "Summarize comments when card moves"
          actionId: "ai_behavior"
          eventId: "card_moved"
          active: false
          eventParams: {
            to_phase_id: "338796240"
          }
          condition: {
            expressions_structure: []
            expressions: []
          }
          actionParams: {
            aiBehaviorParams: {
              instruction: "Read the field %{field:all_comments} and update the card with the summary of those comments, executing the action %{action:63637099-d172-4196-b46a-1864ed61e685} and executing the action %{action:88eb26bc-c838-41a7-a8f7-4f6c3df337a4}"
              referencedFieldIds: ["all_comments"]
              dataSourceIds: ["93779687-19d5-42dd-8b8a-e8b75e1c12dd"]
              actionsAttributes: [
                {
                  id: "0e73ad94-496c-4fa1-99e2-089f880ed6ca"
                  name: "Move card"
                  actionType: "move_card"
                  referenceId: "88eb26bc-c838-41a7-a8f7-4f6c3df337a4"
                  metadata: {
                    destinationPhaseId: "338796241"
                    pipeId: "306422123"
                    fieldsAttributes: []
                  }
                },
                {
                  id: "74b6f9e8-de85-417b-9abd-5040019f8f5b"
                  name: "Update card fields"
                  actionType: "update_card"
                  referenceId: "63637099-d172-4196-b46a-1864ed61e685"
                  metadata: {
                    pipeId: "306422123"
                    fieldsAttributes: [
                      {
                        fieldId: "421679209"
                        inputMode: "fill_with_ai"
                        value: ""
                      }
                    ]
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }) {
    agent {
      uuid
      name
      behaviors {
        id
        name
        active
        event_id
        action_id
      }
    }
  }
}

Important: Including only one behavior in behaviors will delete all other existing behaviors. Always include the id of every behavior you want to keep.

Disable a behavior

Set active: false on the behavior to disable it without deleting it. Include the behavior id and all other existing behavior IDs to avoid unintended deletions.

Move the agent to a different pipe

Update repoUuid to move the agent. The name and repoUuid fields are always required.

mutation {
  updateAiAgent(input: {
    uuid: "bfcf25c0-afcf-40db-8a63-04094620c1e8"
    agent: {
      name: "Comments Summary Agent"
      repoUuid: "new-pipe-uuid-456"
    }
  }) {
    agent {
      uuid
      name
      repoUuid
      disabledAt
    }
  }
}

Error handling

If the agent doesn't exist or you don't have permission to update it:

{
  "data": {
    "updateAiAgent": null
  },
  "errors": [
    {
      "message": "Resource Not Found - Couldn't find Agent with uuid bfcf25c0-afcf-40db-8a63-04094620c1e8",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["updateAiAgent"]
    }
  ]
}

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

Tips

name and repoUuid are always required even when updating only other fields.
Behavior IDs: The behavior id is the numeric automation ID (e.g., "305992651"). Action IDs within actionsAttributes are UUIDs (e.g., "0e73ad94-...").
Behavior deletion: When behaviors is included, any existing behavior not represented by an id in the list is deleted. Always include all behavior IDs you want to keep.
Omitting behaviors: Existing behaviors are unchanged when the field is omitted entirely.
disabledAt and agent status: Pass disabledAt: null to keep the agent active. If disabledAt is omitted and no active behavior is included in the request, the agent is automatically disabled. Pass disabledAt: null explicitly whenever you want the agent to remain enabled.