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 Suno.
  Describe genre, mood, tempo, and instruments clearly in your prompt.
  Music is generated asynchronously — poll for completion before returning the URL.
  Complete all steps fully before writing your report.
steps:
  - name: Design Music Prompt
    content: |
      Craft a detailed Suno music prompt for an upbeat corporate background track.
      Specify: genre (corporate pop), mood (energetic, optimistic), tempo (120 BPM),
      instruments (acoustic guitar, light drums, piano), duration (60 seconds), no vocals.
  - name: Generate Track
    content: |
      Submit the music prompt to Suno. Wait for generation to complete — poll every 10 seconds
      until status is "complete". Retrieve the audio URL and title once done.
  - name: Report
    content: |
      Summarize the result:
      - Prompt used for generation
      - Track title assigned by Suno
      - Audio URL
      - Duration and format
      - 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",
      "apiKey": "YOUR_SUNO_API_KEY",
      "model": "chirp-v3-5"
    }
  ]
}

Get your Suno API key from suno.com. The model field accepts chirp-v3-5 (default, highest quality) or chirp-v3-0. Music generation is asynchronous — the agent polls until the track is complete before returning the URL.

Download OE Runtime

Run the Agent

Windows

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

macOS

# Make executable (first time only)
chmod +x oe-runtime-macos

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

Linux

# Make executable (first time only)
chmod +x oe-runtime-linux

# Run the agent
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.