How to Run an AI Music Generation Agent with OE Runtime

Generate original music tracks from text descriptions automatically. OE Runtime connects to Suno, crafts optimised music prompts, and returns the audio URL — from a background track to a full composition, all from a YAML file.

The Agent YAML

Create a file called agent.yaml inside a music-generation/ directory:

name: Music Creator
description: Generate original music tracks from text descriptions
instructions: |
  You are a music generation agent. Create original music using the Suno connector via kie.ai.
  Music generation is asynchronous — after submitting, poll for completion before returning the result.
  Complete all steps fully before writing your report.
steps:
  - name: Design Music Prompt
    content: |
      Craft a detailed music prompt for an upbeat corporate background track.
      Specify: genre (corporate pop), mood (energetic, optimistic), tempo (120 BPM),
      instruments (acoustic guitar, light drums, piano), no vocals.
  - name: Generate Track
    content: |
      Submit the music prompt to the Suno connector.
      POST /generate with body:
      {
        "prompt": "<detailed music prompt from previous step>",
        "model": "V4_5",
        "instrumental": true,
        "customMode": false
      }
      Save the taskId from the response: data.taskId.
      Then poll GET /generate/<taskId> every 10 seconds until data.status is "complete".
      Once complete, extract and save the audio URL from the response.
  - name: Report
    content: |
      Summarize the result:
      - Prompt used for generation
      - Track title returned by Suno
      - Audio URL
      - Generation time taken
connectors:
  - connection_name: Suno
    connection_type: suno

The Config File

Create oe-config.json in the same directory:

{
  "llm": {
    "provider": "openai",
    "model": "gpt-4o",
    "apiKey": "YOUR_OPENAI_API_KEY"
  },
  "server": {
    "enabled": false,
    "port": 3333,
    "apiKey": "your-secret-api-key"
  },
  "connectors": [
    {
      "connection_name": "Suno",
      "connection_type": "suno",
      "bearerToken": "YOUR_KIE_AI_API_KEY",
      "baseUrl": "https://api.kie.ai/api/v1"
    }
  ]
}

Get your API key from kie.ai (the Suno API provider). The agent uses model V4_5 and polls the generation task until the track is complete before returning the audio URL. Music generation is asynchronous — polling typically takes 30–90 seconds.

Download OE Runtime

Run the Agent

Windows

oe-runtime-win.exe music-generation/agent.yaml --config music-generation/oe-config.json

macOS

chmod +x oe-runtime-macos

oe-runtime-macos music-generation/agent.yaml --config music-generation/oe-config.json

Linux

chmod +x oe-runtime-linux

oe-runtime-linux music-generation/agent.yaml --config music-generation/oe-config.json

Running as an API Server

Add --serve to start OE Runtime as an HTTP server on port 3333:

oe-runtime-win.exe --serve --config music-generation/oe-config.json

Then send a request:

curl -X POST http://localhost:3333/run \
  -H "Content-Type: application/json" \
  -d '{"yaml": "music-generation/agent.yaml", "params": {}}'

Or import the Postman collection (download above) to test all endpoints visually.

Use Cases

• Background music for videos — Generate royalty-free background tracks for product videos, explainer content, ads, and social media clips without licensing costs. Describe the mood, tempo, and style and the agent produces a custom track tailored to your specific content rather than relying on generic stock music libraries.
• Podcast intro and outro music — Create unique, branded intro and outro music for podcasts that matches your show's tone and audience. A single prompt describing your podcast's style produces a professional-sounding track that you own outright, with no subscription fee.
• Game audio and sound design — Generate ambient music, battle themes, exploration tracks, and menu music for indie games from simple text descriptions. The agent can produce multiple variations quickly, letting your development team iterate on the musical direction without hiring a composer.
• Corporate presentations and events — Produce custom background music for company events, conference presentations, trade show booths, and internal town halls. Tailor each track to the event's energy — upbeat for a product launch, calm for a strategy session.
• E-learning and training content — Generate appropriate background music for online courses, training videos, and instructional content that aids focus without distraction. Research suggests that the right background music improves information retention — the agent lets you customise this for every module.
• Retail and hospitality atmosphere — Create customised in-store or in-venue background playlists that match your brand's personality and the time of day. Rather than licensing expensive curated playlists, generate tracks in the exact style, tempo, and mood your environment calls for.
• App and software onboarding — Add ambient sound design and musical moments to your application's onboarding flow to make the user experience more engaging. Generate short musical stings for success states, loading screens, and completion milestones that match your product's visual identity.
• Content creator tooling — Build music generation into your content creation pipeline so that every piece of content gets a matching, original soundtrack automatically. Run the agent as an API server and call it from your video editing tool or CMS whenever a new piece of content is published.