[josiasmontag]

What

ai/agent command (beta)

Adds the new ai/agent task: an AI agent processes files as described in plain language.

cloudconvert ai --prompt="How many pages does this PDF have?" input.pdf
cloudconvert ai --prompt="Make this video smaller, at most 30 MB." input.mp4
cloudconvert ai --prompt="Convert https://example.com/report.docx to PDF."

• Aliases: ai-agent, agent, ai. --prompt is required, --engine sets the model (cloudconvert parameters ai/agent --alternatives lists them).
• Files are optional, since the prompt can name the files to import. File arguments which match no files are rejected (No files found: …) instead of silently sending a prompt-only job.
• The export task of an agent job gets ignore_error: true: when the agent answers a question without output files, the API cancels the export with AGENT_NO_OUTPUT, which would otherwise fail the job. That cancellation message is not printed.
• The agent's message (its summary, or the answer to a question) is printed like other task messages, followed by its suggestions.
• Failed tasks created by the agent (parent_task_id set) are logged as info while the job runs, since the agent may correct them. The final summary of a failed job still lists them as errors.

--api-url / CLOUDCONVERT_API_URL

Sends the API calls to another endpoint, such as a local development server; overrides --sandbox. The SDK has the production and sandbox URLs built in, so this subclasses it, overriding call() and opening the socket on the socketio. host of the API URL (as for api.cloudconvert.com). socket.io-client is now a direct dependency for that; it was already installed through the SDK.

Testing

• npm run typecheck, npm test (49 tests, 10 new).
• Against a local API (https://api.cloudconvert.localhost): credits, parameters ai/agent --alternatives, a question job with an uploaded PDF (cancelled with Ctrl+C while queued), and a prompt-only job that imported a PDF from a URL and downloaded all 31 PNGs.

Notes for review

• ai/agent is not available on the production and sandbox APIs yet. Until it is, parameters ai/agent prints the whole operations catalog, because the API ignores unknown filter[operation] values. This should ship after the API.
• --api-url is not mentioned in the README; it shows up in --help.