> ## Documentation Index > Fetch the complete documentation index at: https://docs.maia.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create an AI Agent Task > Creates a new AI agent task and starts async execution. Poll the messages endpoint to retrieve results. ## OpenAPI ````yaml /openapi/public-api-endpoint-reference.yaml post /v1/ai/agents/tasks openapi: 3.1.0 info: title: Maia Public REST API version: '1.0' servers: - description: EU1 url: https://eu1.api.matillion.com/dpc - description: US1 url: https://us1.api.matillion.com/dpc security: - bearerAuth: [] tags: - description: Manage Schedules name: Schedules - description: Manage Connections name: Connections - description: Operations for managing Project Variables name: Project Variables - description: Manage Pipelines name: Pipelines - description: Review pipelines against quality rules name: Pipeline Quality Review - description: Execute tests within a project name: Test Execution - description: Manage your AI agent tasks name: AI Agent Tasks - description: SCIM endpoints for user/group permission management name: Directory Integration - description: Publish shared pipeline artifacts name: Shared Pipeline Artifacts - description: Manage Repositories name: Repositories - description: Report on Credit Consumption name: Consumption - description: Manage Artifacts name: Artifacts - description: Operations for data lineage and governance name: Data Lineage - description: Manage Streaming Pipelines name: Streaming Pipelines - description: Execute a pipeline name: Pipeline Execution - description: '' name: Environments - description: '' name: Projects - description: Manage Agents name: Agents - description: Operations for managing Environment-level Overrides of Project Variables name: Project Variable Environment Overrides - description: Query audit events name: Audit Events - description: Connector Profiles name: Connectors paths: /v1/ai/agents/tasks: post: tags: - AI Agent Tasks summary: Create an AI Agent Task description: >- Creates a new AI agent task and starts async execution. Poll the messages endpoint to retrieve results. operationId: createTask requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateTaskRequest' required: true responses: '201': content: application/json: examples: Created agent task: description: Example response for a successfully created agent task value: taskId: 550e8400-e29b-41d4-a716-446655440000 status: RUNNING agentName: data_engineer_agent createdAt: '2024-01-15T10:30:00.000Z' schema: $ref: '#/components/schemas/CreateTaskResponse' description: Agent task created successfully '400': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' description: Invalid request body '401': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' description: Missing or invalid authentication token '403': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' description: Insufficient permissions to create an agent task '404': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' description: Resource not found '502': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' description: Upstream service error '504': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' description: Upstream service timeout components: schemas: CreateTaskRequest: type: object properties: agentConfig: description: Configuration specifying the agent type and its parameters oneOf: - $ref: '#/components/schemas/DataEngineerAgentConfig' grantedPermissions: type: - array - 'null' description: >- Permissions pre-granted to the agent for this task. Each entry must be unique items: $ref: '#/components/schemas/AllowedTool' message: type: string description: The instruction or question to send to the agent example: Build a pipeline to load sales data from S3 into Snowflake minLength: 1 required: - agentConfig - message CreateTaskResponse: type: object properties: agentName: type: string description: The name of the agent handling the task example: data_engineer_agent createdAt: type: string format: date-time description: The date and time the task was created example: '2024-01-15T10:30:00.000Z' status: type: string description: The current status of the task enum: - RUNNING - STOPPED - STOPPING - ERRORED example: RUNNING taskId: type: string format: uuid description: The unique identifier of the created task example: 550e8400-e29b-41d4-a716-446655440000 ProblemDetail: type: object properties: detail: type: string instance: type: string status: type: integer format: int32 title: type: string type: type: string format: uri violations: type: array items: type: string DataEngineerAgentConfig: allOf: - $ref: '#/components/schemas/AgentConfig' - type: object properties: environmentName: type: string description: The name of the environment to use for execution example: development minLength: 1 generateBranch: type: boolean description: >- Whether the agent should auto-generate a new branch for its changes example: true graphId: type: - string - 'null' description: The ID of the pipeline graph the agent will work on example: my-pipeline mode: type: string description: >- The execution mode. ACT allows the agent to make changes; PLAN produces a plan only enum: - PLAN - ACT example: ACT name: type: string description: The agent type identifier. Must be "data_engineer_agent" example: data_engineer_agent minLength: 1 projectId: type: string format: uuid description: The ID of the project the agent will work within example: 550e8400-e29b-41d4-a716-446655440001 sourceBranchName: type: string description: The branch the agent will read from example: main minLength: 1 targetBranchName: type: - string - 'null' description: >- The branch the agent will write changes to. Required unless generateBranch is true example: feature/my-pipeline workingDirectory: type: - string - 'null' description: The working directory within the project for the agent example: /pipelines required: - environmentName - mode - name - projectId - sourceBranchName AllowedTool: type: object properties: toolName: type: string description: The name of the tool to allow example: execute_sql minLength: 1 required: - toolName AgentConfig: discriminator: propertyName: name properties: name: type: string required: - name securitySchemes: bearerAuth: bearerFormat: JWT description: a valid bearer token scheme: bearer type: http ````