--- agentTools: projectIndex: https://developers.pipefy.com/llms.txt --- # Get an AI Agent by UUID Retrieve a single AI agent and its full behavior configuration ## Before You Begin * Use the [GraphQL Playground](https://app.pipefy.com/graphiql). * Authenticate with a [Service Account token](https://developers.pipefy.com/reference/service-accounts). ## Prerequisites * You must have **admin** permission on the agent's pipe or table. * The organization must have the **AI Agents** feature enabled. * You need the agent UUID. Use the `aiAgents` query to list agents and find the UUID: ```graphql { aiAgents(repoUuid: "1cc2bce3-1ea3-4af0-8fe9-0b899c73ae84") { edges { node { uuid name } } } } ``` ## Query an AI Agent ### Basic example ```graphql query aiAgent($uuid: ID!) { aiAgent(uuid: $uuid) { uuid name instruction repoUuid dataSourceIds disabledAt createdAt updatedAt } } ``` Variables: ```json { "uuid": "bfcf25c0-afcf-40db-8a63-04094620c1e8" } ``` ### Full query including behaviors The `behaviors` field exposes the full configuration of each behavior, including event params, conditions, and AI action details. ```graphql query aiAgent($uuid: ID!) { aiAgent(uuid: $uuid) { uuid name instruction repoUuid dataSourceIds disabledAt createdAt updatedAt behaviors { id name active event_id action_id event_params { to_phase_id fromPhaseId inPhaseId triggerFieldIds kindOfSla triggerAutomationId phase { uuid name deletedAt } } condition { expressions_structure expressions { id field_address operation value structure_id } } action_params { aiBehaviorParams { dataSourceIds instruction referencedFieldIds actionsAttributes { id name actionType referenceId metadata { destinationPhaseId pipeId tableId emailTemplateId allowTemplateModifications emailTemplate { id name deletedAt } pipe { id name deletedAt } phase { id name deletedAt } fieldsAttributes { fieldId inputMode value } } } capabilitiesAttributes { capabilityType enabled } } } } } } ``` Response: ```json { "data": { "aiAgent": { "uuid": "bfcf25c0-afcf-40db-8a63-04094620c1e8", "name": "Comments Summary Agent", "instruction": "Summarize card comments and update fields.", "repoUuid": "1cc2bce3-1ea3-4af0-8fe9-0b899c73ae84", "dataSourceIds": ["93779687-19d5-42dd-8b8a-e8b75e1c12dd"], "disabledAt": null, "createdAt": "2025-01-20T10:00:00Z", "updatedAt": "2025-01-20T15:00:00Z", "behaviors": [ { "id": "305992651", "name": "Summarize comments when card moves", "active": false, "event_id": "card_moved", "action_id": "ai_behavior", "event_params": { "to_phase_id": "338796240", "fromPhaseId": null, "inPhaseId": null, "triggerFieldIds": null, "kindOfSla": null, "triggerAutomationId": null, "phase": { "uuid": "980ee9b1-c9ea-4d56-b427-03e752c0a9d1", "name": "Doing", "deletedAt": null } }, "condition": { "expressions_structure": [], "expressions": [] }, "action_params": { "aiBehaviorParams": { "dataSourceIds": ["93779687-19d5-42dd-8b8a-e8b75e1c12dd"], "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"], "actionsAttributes": [ { "id": "74b6f9e8-de85-417b-9abd-5040019f8f5b", "name": "Update card fields", "actionType": "update_card", "referenceId": "63637099-d172-4196-b46a-1864ed61e685", "metadata": { "destinationPhaseId": "", "pipeId": "306422123", "tableId": null, "emailTemplateId": null, "allowTemplateModifications": null, "emailTemplate": null, "pipe": { "id": "306422123", "name": "Sample Pipe", "deletedAt": null }, "phase": null, "fieldsAttributes": [ { "fieldId": "421679209", "inputMode": "fill_with_ai", "value": "" } ] } }, { "id": "0e73ad94-496c-4fa1-99e2-089f880ed6ca", "name": "Move card", "actionType": "move_card", "referenceId": "88eb26bc-c838-41a7-a8f7-4f6c3df337a4", "metadata": { "destinationPhaseId": "338796241", "pipeId": "306422123", "tableId": null, "emailTemplateId": null, "allowTemplateModifications": null, "emailTemplate": null, "pipe": { "id": "306422123", "name": "Sample Pipe", "deletedAt": null }, "phase": { "id": "338796241", "name": "Done", "deletedAt": null }, "fieldsAttributes": [] } } ], "capabilitiesAttributes": null } } } ] } } } ``` ### Response explained **Agent fields:** | Field | Description | | --------------- | --------------------------------------------------------------------------- | | `uuid` | Unique identifier for the agent. | | `name` | Display name. | | `instruction` | Agent-level system instruction, applies to all behaviors unless overridden. | | `repoUuid` | UUID of the pipe or table the agent belongs to. | | `dataSourceIds` | UUIDs of knowledge bases configured for this agent. | | `disabledAt` | `null` when the agent is active; a timestamp when disabled. | | `createdAt` | When the agent was created. | | `updatedAt` | When the agent was last updated. | **Behavior fields:** | Field | Description | | ----------- | --------------------------------------------------------------------------------------- | | `id` | Numeric automation ID for this behavior. Used as the behavior `id` in update mutations. | | `name` | Display name of the behavior. | | `active` | Whether the behavior is currently enabled. | | `event_id` | Trigger event identifier. Same values as regular automations (e.g., `"card_moved"`). | | `action_id` | Always `"ai_behavior"`. | **eventParams fields:** | Field | Description | | --------------------- | -------------------------------------------------------------------------------------------- | | `to_phase_id` | Phase ID for `card_moved` and `all_children_in_phase` events. | | `fromPhaseId` | Phase ID for `card_left_phase`. | | `inPhaseId` | Phase ID for `card_inbox_received_email`. | | `triggerFieldIds` | Field IDs for `field_updated`. | | `kindOfSla` | SLA state for `sla_based` (`"late"`, `"expired"`, `"overdue"`). | | `triggerAutomationId` | Automation ID for `http_response_received`. | | `phase` | Resolved phase object for the configured phase ID. Includes `uuid`, `name`, and `deletedAt`. | **condition fields:** | Field | Description | | ----------------------- | ----------------------------------------------------------------------------------------------- | | `expressions_structure` | Logical grouping of expression IDs. Empty array means no condition filter is applied. | | `expressions` | Array of condition expressions. Each has `field_address`, `operation`, `value`, `structure_id`. | **actionParams.aiBehaviorParams fields:** | Field | Description | | ------------------------ | ------------------------------------------------------------------------------------------------ | | `dataSourceIds` | Knowledge base UUIDs for this behavior. Overrides the agent-level `dataSourceIds` when set. | | `instruction` | The AI prompt. May contain `%{field:ID}` (field references) and `%{action:UUID}` (action calls). | | `referencedFieldIds` | Field IDs and slugs referenced in the instruction via `%{field:...}`. | | `actionsAttributes` | Array of actions the AI can perform. See below. | | `capabilitiesAttributes` | Array of enabled capabilities, or `null` if none are configured. | **actionsAttributes item fields:** | Field | Description | | ------------- | ------------------------------------------------------------------------------------------------------ | | `id` | UUID identifying this action instance. Pass as `id` in update mutations to update the action in place. | | `name` | Display name. | | `actionType` | `"create_card"`, `"update_card"`, `"move_card"`, or `"send_email_template"`. | | `referenceId` | UUID used to call this action from the instruction via `%{action:REFERENCE_ID}`. | | `metadata` | Action configuration. See below. | **metadata fields:** | Field | Description | | ---------------------------- | ----------------------------------------------------------------------------------------------- | | `destinationPhaseId` | Target phase ID for `move_card`. | | `pipeId` | Pipe ID context for the action. | | `tableId` | Table ID context (when applicable). | | `emailTemplateId` | Email template ID for `send_email_template`. | | `allowTemplateModifications` | Whether the AI can modify the email template content. | | `pipe` | Resolved pipe object (`id`, `name`, `deletedAt`). | | `phase` | Resolved phase object (`id`, `name`, `deletedAt`). `null` when not applicable. | | `emailTemplate` | Resolved email template object. `null` when not applicable. | | `fieldsAttributes` | Field mappings for `update_card` and `create_card`. Each item: `fieldId`, `inputMode`, `value`. | ## See also * [Retrieve AI Agents](https://developers.pipefy.com/reference/ai-agents-query) * [Create AI Agent](https://developers.pipefy.com/reference/create-ai-agent) * [Update AI Agent](https://developers.pipefy.com/reference/update-ai-agent) * [Conditions](https://developers.pipefy.com/reference/conditions) * [Automation Events Parameters](https://developers.pipefy.com/reference/events-params)