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.

What You Need

• Node.js 18+ installed, or the OE Runtime binary from openenthrium.com/runtime
• An API key from OpenAI, Anthropic, or any supported LLM provider
• A Suno API key from kie.ai for AI music generation
• A text editor — nothing else

Create the Project Folder

Create a folder called music-generation/ and add these two files:

The Skill Files

Create SKILL.md inside a music-generation/ directory. This is the portable skill — it follows the agentskills.io format and runs unchanged on Claude, Cursor, Windsurf, or OE Runtime:

---
name: music-generation
description: Generate original music tracks from text descriptions
license: Apache-2.0
metadata:
  author: Open Enthrium
  version: "1.0"
---

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.

## Step 1: Design Music Prompt
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.

## Step 2: Generate Track
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.

## Step 3: Report
Summarize the result:
- Prompt used for generation
- Track title returned by Suno
- Audio URL
- Generation time taken

Create agent.yaml in the same directory to wire the skill to your connector:

name: Music Creator
description: Generate original music tracks from text descriptions
connectors:
  - connection_name: Suno
    connection_type: suno
skills:
  - path: ./
    trigger_type: auto

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

From the parent folder containing your skill directory:

1 npx recommended

npx -y @openenthrium/oe-runtime@latest ./music-generation

2 Windows

oe-runtime-win.exe ./music-generation

3 macOS

chmod +x oe-runtime-macos
./oe-runtime-macos ./music-generation

First run blocked? System Settings → Privacy & Security → Allow Anyway.

4 Linux

chmod +x oe-runtime-linux
./oe-runtime-linux ./music-generation

5 API Server integration

Add a "server" block to oe-config.json, then start with --serve:

{
  "llm": { ... },
  "server": { "enabled": true, "port": 3333, "apiKey": "your-secret-key" },
  "connectors": [ ... ]
}

npx -y @openenthrium/oe-runtime@latest --serve --config oe-config.json

Run with inline YAML:

curl -X POST http://localhost:3333/run \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-key" \
  -d '{"yaml": "...", "params": {}}'

Or run from a file on the server:

curl -X POST http://localhost:3333/run-file \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-key" \
  -d '{"file": "/path/to/agent.yaml", "params": {}}'

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.