Create 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 pipe/table where you want to create the agent.
3. Feature Toggle: The organization must have AI Agents feature enabled via toggle.
4. Repo UUID: Identify the pipe/table UUID where the agent will be created.

Step 1: Find Your Repo UUID

See our Get resource IDs page for how to find the pipe UUID.

Step 2: Create an AI Agent

Basic example

Inputs

• agent.name: Display name of the agent (required).
• agent.repoUuid: UUID of the pipe/table the agent belongs to (required).
• agent.instruction: Custom instruction for the agent (optional).
• agent.dataSourceIds: List of data source IDs (knowledge base) for the agent (optional).
• agent.behaviors: List of behaviors (automations) for the agent (optional).
• agent.disabledAt: Timestamp to disable the agent (optional).

mutation {
  createAiAgent(input: {
    agent: {
      name: "Customer Support Agent"
      repoUuid: "pipe-uuid-123"
      instruction: "Help customers with their inquiries and provide accurate information"
      dataSourceIds: ["ds-1", "ds-2"]
    }
  }) {
    agent {
      uuid
      name
      instruction
      repoUuid
      dataSourceIds
      createdAt
      updatedAt
    }
  }
}

Response:

{
  "data": {
    "createAiAgent": {
      "agent": {
        "uuid": "agent-uuid-123",
        "name": "Customer Support Agent",
        "instruction": "Help customers with their inquiries and provide accurate information",
        "repoUuid": "pipe-uuid-123",
        "dataSourceIds": ["ds-1", "ds-2"],
        "createdAt": "2025-01-20T10:00:00Z",
        "updatedAt": "2025-01-20T10:00:00Z"
      }
    }
  }
}

Response explained

• agent.uuid: Created agent unique identifier.
• agent.name: Display name of the agent.
• agent.instruction: Custom instruction for the agent.
• agent.repoUuid: UUID of the pipe/table the agent belongs to.
• agent.dataSourceIds: List of data source IDs (knowledge base) for the agent.
• agent.createdAt: When the agent was created.
• agent.updatedAt: When the agent was last updated (same as createdAt for new agents).

Example with behaviors

You can also create an agent with behaviors (automations):

mutation {
  createAiAgent(input: {
    agent: {
      name: "Document Processing Agent"
      repoUuid: "pipe-uuid-123"
      instruction: "Process and categorize documents"
      dataSourceIds: ["ds-1"]
      behaviors: [
        {
          # Automation input structure
          # Refer to automation creation documentation for details
        }
      ]
    }
  }) {
    agent {
      uuid
      name
      instruction
      behaviors {
        id
        name
      }
    }
  }
}

Error handling

If the agent creation fails (e.g., invalid input, permission denied, or repo not found), you'll receive an error response:

{
  "data": {
    "createAiAgent": null
  },
  "errors": [
    {
      "message": "Record Not Saved - Validation failed: Name can't be blank",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "createAiAgent"
      ]
    }
  ]
}

Error response explained

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

Tips

• Data sources: Data source IDs refer to knowledge bases that the agent can use for context.
• Behaviors: Behaviors are automations that define what actions the agent can perform. Refer to automation creation documentation for details on behavior structure.