--- title: "AI" description: "Describe what should happen with your files, and an AI model takes care of it." canonical_url: "https://cloudconvert.com/docs/operations/ai" --- # AI > Describe what should happen with your files, and an AI model takes care of it. AI operations let an AI model work on your files. `ai/agent` tasks are currently in beta. Their behavior and the parameters and results described here may still change, and the agent can make mistakes. ## AI Agent With an `ai/agent` task, you describe in plain language what should be done with your files. The agent then creates the required tasks inside the same [job](https://cloudconvert.com/docs/raw/api-reference/jobs.md), step by step. To use it, [create a job](https://cloudconvert.com/docs/raw/api-reference/jobs.md#create-job) with an import task, an `ai/agent` task which uses it as `input`, and an export task which uses the `ai/agent` task as `input`. The agent does not see the content of your files. It works with the prompt, the file names and the results of the tasks it has created, such as metadata. For example, it can extract the metadata of a file first, and decide based on the number of pages which conversions are needed. If a task fails, the agent tries to correct the cause. If it cannot, the `ai/agent` task fails. The tasks created by the agent are regular tasks of the job. They are listed when [showing the job](https://cloudconvert.com/docs/raw/api-reference/jobs.md#show-job) and have their `parent_task_id` set to the ID of the `ai/agent` task. One `ai/agent` task can create up to 50 tasks. The agent imports from and exports to the locations named in your prompt or in the other tasks of the job only, with the credentials given there. `export/url` tasks and exports to your connected cloud storages are always possible. The `engine` of the task is the AI model. If it is not set, the default model is used. `ai/agent` tasks are available within jobs only. The `ai/agent` task itself does not consume credits; the tasks created by the agent consume credits as usual. A job runs one `ai/agent` task at a time. An `ai/agent` task which is added while another one of the job is waiting or processing is rejected with the code `AGENT_ALREADY_RUNNING`; an `ai/agent` task which uses the result of another one as `input` waits for it. Creating jobs and adding tasks with an `ai/agent` task is limited to 6 requests per minute and 60 per hour; further requests are answered with the HTTP status `429` and the code `AI_RATE_LIMIT_EXCEEDED`. AI can be turned off for your account or your team in the [AI settings](https://cloudconvert.com/dashboard/ai) of the dashboard. Jobs with an `ai/agent` task are then rejected, and `ai/agent` tasks which are scheduled anyway, such as retries, fail with the code `AI_DISABLED`. `AI_DISABLED` is also used while AI is temporarily unavailable for all accounts. The same settings let you turn off the storage of your AI requests for improving our AI features. #### Result Tasks which use the `ai/agent` task as `input`, such as export tasks, get the output files of the tasks the agent has created. If the agent finishes without output files, for example because it answered a question, these tasks are cancelled with the code `AGENT_NO_OUTPUT`. Set `ignore_error` on the export task if this should not fail the job. The `message` of the finished `ai/agent` task is a short summary by the agent. If you asked a question about your files, it is the answer. The `result` of the task contains: - `output_tasks`: the IDs of the tasks whose output files are the result. - `steps`: the steps the agent has taken. - `suggestions`: up to three follow-up requests the agent suggests, worded as a user would type them. They are set when the task has failed, too. - `question`: `true` if the agent needs something only you can give, such as the file to work on, a password or the target format. The `message` is the question then, and the task finishes without output files. Answer it with a follow-up `ai/agent` task in the same job. If the agent cannot fulfil the request, the `ai/agent` task fails. The code `AGENT_DECLINED` means that the request asks for something CloudConvert cannot do, for example a conversion which is not supported; the `message` says why. The code `AGENT_FAILED` means that tasks the agent created have failed and it could not correct the cause, or that it could not proceed otherwise. #### Example Prompts - `Convert to PDF/A-2b.` - `Make this video smaller, at most 30 MB.` - `Convert all files to PDF and merge them into one PDF, in alphabetical order of the file names.` - `Create a PNG thumbnail of the first page with a width of 400 pixels.` - `Add the text "Confidential" as watermark to every page.` - `Convert the first page to PNG with a resolution of 2000x2000. If there are more pages, convert the pages after the first one to PNG with a maximum resolution of 1000x1000.` - `Extract the ZIP archive and convert all images in it to WebP.` - `How many pages does this PDF have?` #### Task Parameters ### ai/agent task parameters - `operation` _string_ required: Value is `ai/agent`. - `input` _string or array of task names_: The input task name(s) for this task. - `prompt` _string_ required: What the agent should do with the input files. The agent creates the required tasks in this job. - `engine` _string_: The AI model the agent uses. If not set, the default model is used. - `timeout` _integer_: Timeout in seconds after the task will be cancelled. ### Example job Raw request: ```json { "tasks": { "import-my-file": { "operation": "import/url", "url": "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf" }, "agent": { "operation": "ai/agent", "input": "import-my-file", "prompt": "Convert the first page to PNG with a resolution of 2000x2000. If there are more pages, convert the pages after the first one to PNG with a maximum resolution of 1000x1000." }, "export-the-result": { "operation": "export/url", "input": "agent" } } } ``` CLI: ```bash # Install the CloudConvert CLI: npm install -g cloudconvert-cli $ cloudconvert ai/agent \ --prompt='Convert the first page to PNG with a resolution of 2000x2000. If there are more pages, convert the pages after the first one to PNG with a maximum resolution of 1000x1000.' \ zombies.pdf ``` cURL: ```bash $ curl -X POST "https://api.cloudconvert.com/v2/jobs" \ -H "Authorization: Bearer API_KEY" \ -H "Content-type: application/json" \ -d '{ "tasks": { "import-my-file": { "operation": "import/url", "url": "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf" }, "agent": { "operation": "ai/agent", "input": "import-my-file", "prompt": "Convert the first page to PNG with a resolution of 2000x2000. If there are more pages, convert the pages after the first one to PNG with a maximum resolution of 1000x1000." }, "export-the-result": { "operation": "export/url", "input": "agent" } } }' ``` PHP: ```php use \CloudConvert\CloudConvert; use \CloudConvert\Models\Job; use \CloudConvert\Models\Task; $cloudconvert = new CloudConvert(['api_key' => 'API_KEY']); $job = (new Job()) ->addTask( (new Task('import/url', 'import-my-file')) ->set('url', 'https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf') ) ->addTask( (new Task('ai/agent', 'agent')) ->set('input', 'import-my-file') ->set('prompt', 'Convert the first page to PNG with a resolution of 2000x2000. If there are more pages, convert the pages after the first one to PNG with a maximum resolution of 1000x1000.') ) ->addTask( (new Task('export/url', 'export-the-result')) ->set('input', 'agent') ); $cloudconvert->jobs()->create($job); ``` Node.js: ```js import CloudConvert from 'cloudconvert'; const cloudConvert = new CloudConvert('api_key'); let job = await cloudConvert.jobs.create({ "tasks": { "import-my-file": { "operation": "import/url", "url": "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf" }, "agent": { "operation": "ai/agent", "input": "import-my-file", "prompt": "Convert the first page to PNG with a resolution of 2000x2000. If there are more pages, convert the pages after the first one to PNG with a maximum resolution of 1000x1000." }, "export-the-result": { "operation": "export/url", "input": "agent" } } }); ``` Python: ```python import cloudconvert cloudconvert.configure(api_key='API_KEY') cloudconvert.Job.create(payload={ 'tasks': { 'import-my-file': { 'operation': 'import/url', 'url': 'https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf' }, 'agent': { 'operation': 'ai/agent', 'input': 'import-my-file', 'prompt': 'Convert the first page to PNG with a resolution of 2000x2000. If there are more pages, convert the pages after the first one to PNG with a maximum resolution of 1000x1000.' }, 'export-the-result': { 'operation': 'export/url', 'input': 'agent' } } }) ``` Use the **Job Builder** to generate and try out ai/agent jobs. ## Sitemap See the full [sitemap](https://cloudconvert.com/docs/sitemap.md) for all pages.