An AI music agent workflow: compile, validate, generate and listen

Give a music agent a small, explicit job. It can turn a brief into a structured draft, check contradictions, prepare a provider-specific request and record the outcome. Those are separate steps. A text model writing a music prompt has not generated or evaluated the audio.

Start with a local command that makes no API call

Clone the MusicPrompt repository, enter its musicprompt application directory, and use Node 20 or newer. The following commands produce an instrumental blueprint, a compiled prompt and diagnostics:

node scripts/agent.mjs init --mode instrumental --title "Morning walk" > blueprint.json
node scripts/agent.mjs compile --input blueprint.json > prompt.json
node scripts/agent.mjs lint --input blueprint.json
node scripts/agent.mjs catalog > contract.json

compile and lint also accept an exported musicprompt-project file. Exit code 2 means a blocking diagnostic remains; an agent should fix it before asking for audio. The downloadable contract describes the accepted choices. It is MusicPrompt’s contract, not a Suno API schema.

Add one text-model request when useful

Set MUSICPROMPT_API_KEY, MUSICPROMPT_BASE_URL and MUSICPROMPT_MODEL in your process environment. Keep credentials out of command arguments, project files and task logs. Then run one request:

node scripts/agent.mjs draft --input blueprint.json --task style --instruction "Keep the piano in front; use a sparse warm background" --locale en > suggested-project.json

This command may incur provider charges. It writes a new importable project without changing the input file. style changes sound choices and exclusions; lyrics changes words and structure; draft and revise can change the full creative draft. Identity, version history, credentials and platform controls are outside the model’s edit contract.

The CLI uses Chat Completions with a bounded output request. OpenAI-compatible services differ: the BYOK guide explains JSON and token-parameter options. The returned JSON is validated even when a provider claims JSON support.

Hand audio generation to an official interface

For Suno, this workflow exports text for the documented web creation flow; it does not invent or invoke a Suno API. If an agent needs an official programmable music interface, consult a provider’s current API documentation.

One documented option is the ElevenLabs Music API quickstart, which describes a paid API, a CLI and composition plans. After installing and authenticating the official CLI as that guide explains, its documented command shape can request a short track:

elevenlabs music compose --prompt "Quiet instrumental piano with a soft pad and space for narration" --music-length-ms 10000 --model-id music_v2 --output music.mp3

This is a provider example, not a command executed or audio-tested by MusicPrompt. Check the current API model ID before running it; a web announcement such as Music v2.5 does not establish an API parameter. Start with a single short request and an explicit spending limit. Do not automatically retry a timeout: the provider may already have processed it.

Keep the evidence loop small

Save the brief, exact request, provider/model, timestamp, output filename and error state in an attempt record. An HTTP success is not evidence of musical quality. Have a listener identify one timestamped issue, then let the agent propose one change and preserve the earlier version.

A useful first automation is therefore: compile → lint → review the request → generate once → listen → log one observation. Avoid building an unattended batch until that single loop produces evidence you can inspect. The listening journal supplies the human part of the loop.