Iframe Agent Specs - MuleRun Docs

Iframe Agent creation is currently restricted by a whitelist access policy. Please contact the team staff to request access.

🔍 Introduction

iframe is a standard protocol for embedding one website into another.
Iframes are particularly useful for enabling third-party agents with existing web applications to seamlessly onboard onto the MuleRun platform.
MuleRun supports Iframe Agents as one of its primary agent integration methods, allowing external developers to host and manage their agent logic independently while being securely embedded within MuleRun.

🏗️ System Architecture

Component Summary

Component	Description
Agent Configuration Params	The param details when you create an Iframe agent from Creator Studio iframe agent template
Iframe URL Protocol	The URL(s) that MuleRun opens when a user starts or resumes a session. Parameters are passed via query string for authentication and context. Separate URLs can be configured for starting and sharing sessions.
Metering API	A MuleRun platform API that allows agent creators to report usage costs for a given session. Enables fine-grained billing based on resource consumption.
Metering Get Reports API	A MuleRun platform API that allows agent creators to get the usage costs for a given session and its current session status.

📈 Agent Configuration Params

Configuration Param	Usage	Default
Start Session Url	The Iframe url that starts a new session on creator’s website
Share Session Url	The Iframe url that starts a new shared session(playback) on creator’s website
Agent Key	The key used for generating signature AND calling metering api, this key should not be expose to any 3rd party
Max Age	The maximum age of the session, in minutes	2880
Start Session Refresh Interval	The time interval between every two re-generations of start session full url(in minutes). when set to 0, it means the start session url will be created only once.	0

🔌 Iframe URL Protocol

Behavior Overview

When a new session starts, MuleRun redirects the user to the Start Session URL, including all required parameters.
On page refresh or re-entry into the session, the Start Session URL is loaded again with updated parameters.
When a session ends (either terminated or time out), a Share Session URL may be triggered. The user may choose to view or share the session playback.
When a visitor accesses the shared playback of a session, the Share Session URL is opened.

URL Schema Design

https://{start-session-url}?
  userId={user_id}&
  sessionId={session_id}&
  agentId={agent_id}&
  time={unix_timestamp}&
  signature={hmac_signature}&
  origin={platform_origin}&
  nonce={nonce}

Note: All parameters are URL-encoded during transmission. During signature verification, they must be URL-decoded, parsed into a dictionary, sorted, and serialized as JSON before HMAC calculation.

Routing Example

Your agent’s endpoint: https://third-party-url.com/session/

Parameter Definitions

Parameter	Type	Example
`userId`	string (64 chars)	`3e5215afce4ef92284c336110cc6dd3d0107971687396cbb3dbbbc625bc3807d`
`sessionId`	string (36 chars, UUID)	`7469a916-d0c6-4161-bd33-1ebac5c834c4`
`agentId`	string (36 chars, UUID)	`924751e0-196e-4b22-bdbd-f0a9ac6a4e39`
`time` (UTC)	string (integer timestamp)	`1755667994`
`origin`	string	`mulerun.com`
`nonce`	string (36 chars, UUID)	`bd3ff1f9-d5f3-4019-848a-7c74bba0b73a`
`signature`	string (64 chars, SHA-256 HMAC hex)	`2ae8a94f29beda81f59beca248824fcd91484c5f5744432a47ce2cea0a5c9a6f`

Example URL

https://third-party-url.com/session?
  userId=377860de68ec786a091beb5d62836797bac4cf98074bd74af56bcec863696146&
  sessionId=25404aaa-b407-4da7-9eb5-8ea6cbcfc9ee&
  agentId=924751e0-196e-4b22-bdbd-f0a9ac6a4e39&
  time=1755671232&
  origin=mulerun.com&
  nonce=bd3ff1f9-d5f3-4019-848a-7c74bba0b73a&
  signature=dd4f2b82b054ce4324175c83ea9219772caa08863ba76e47cc7f03c57a65ce76

Signature Generation (Python Example)

import json
from datetime import datetime, timezone
import hmac
from hashlib import sha256

nonce = "bd3ff1f9-d5f3-4019-848a-7c74bba0b73a"
request_params = {
    "userId": user_sha_id,
    "sessionId": str(session_id),
    "agentId": "924751e0-196e-4b22-bdbd-f0a9ac6a4e39",
    "time": str(int(datetime.now(timezone.utc).timestamp())),
    "origin": "mulerun.com",
    "nonce": nonce,
}

# Ensure parameters are sorted by key before serialization
sorted_json = json.dumps(request_params, separators=(',', ':'), sort_keys=True)
signature = hmac.new(agent_key.encode(), json.dumps(request_param, sort_keys=True, separators=(',', ':')).encode(), sha256).hexdigest()

request_params["signature"] = signature

✅ Important: Use json.dumps(..., sort_keys=True) to ensure consistent serialization order.

Signature Verification (Python Example)

from urllib.parse import parse_qs
import hmac
from hashlib import sha256
import json

agent_key = "your-agent-key"  # Shared secret between MuleRun and Agent
query_string = "userId=...&signature=..."

# Parse query string
query_dict = {k: v[0] if len(v) == 1 else v for k, v in parse_qs(query_string).items()}
received_signature = query_dict.pop("signature")

# Recreate canonical string for HMAC
sorted_payload = json.dumps(query_dict, separators=(',', ':'), sort_keys=True)
calculated_hmac = hmac.new(
    agent_key.encode(),
    sorted_payload.encode(),
    sha256
).hexdigest()

# Secure comparison
if hmac.compare_digest(calculated_hmac, received_signature):
    # Valid request
    pass
else:
    # Invalid or tampered request
    raise Exception("Invalid signature")

🔐 The agent_key is your Agent Key that you can copy from your agent info in Creator Studio. It should be not be exposed to any 3rd party.

🔒 Security Considerations

To ensure secure and trusted communication, the following mechanisms are implemented:

Mechanism	Purpose
User ID Hashing	Raw user identifiers are hashed (e.g., SHA-256) to protect user privacy.
HMAC Signature	Prevents tampering of query parameters. Ensures authenticity of the request.
Timestamp Validation	Requests must be within a valid time window (e.g., ±5 minutes) to prevent replay attacks.
Origin Domain Whitelisting	Only specified domains are allowed to receive iframe requests. Prevents unauthorized embedding.
Nonce Usage	Unique per-request identifier to prevent replay attacks and ensure freshness.

✅ Recommended Validation Logic:

📊 Metering APIs

MuleRun provides two APIs for managing session metering and billing:

Metering Report API

Used by agents to report usage costs for a session. This API supports idempotent metering with automatic deduplication to prevent double billing. Endpoint: POST https://api.mulerun.com/sessions/metering Key Features:

Report usage costs in increments of 0.0001 credits
Idempotency support via meteringId to prevent duplicate billing
Ability to mark reports as final to terminate sessions
Grace period for late reports after session termination

View Full API Documentation →

Metering Get Reports API

Query usage costs for a given session and retrieve its current status. Useful for verifying reports were received and debugging billing issues. Endpoint: GET https://api.mulerun.com/sessions/metering/{sessionId} Returns:

Current session status (running, completed, or error)
Count of successfully processed reports
Whether final report was received
List of all metering records with their IDs

View Full API Documentation →

🧪 Testing and Debugging

MuleRun provides dedicated tools and test agents to help you validate your iframe integration before going live.

Reference Implementation

Equity Investment Research Agent is an excellent example of iframe agent integration:

Live agent: https://mulerun.com/agents/consensusai-agent-924751e0-196e-4b22-bdbd-f0a9ac6a4e39
This agent demonstrates best practices for UI adaptation and metering API integration

Test Agent

MuleRun provides a dedicated test agent for iframe integration debugging: Test Agent URL: https://mulerun.com/agents/kabutack-agent-633d0ca3-abf3-4a20-9162-f381562940d9 Test Credentials:

Activation Code: 85HK66
Metering API Token: mtr_v1_7U5KFH3JPd_Ly0NPC9KtDVqDK-mnDPH2HxG7-VMF2-I

Required Parameters: The test agent requires specific input parameters at startup. Refer to the Agent Configuration Params section above for parameter definitions:

App Key: You can specify any value for testing purposes

🔄 Development Workflow

Follow this step-by-step workflow to integrate and test your iframe agent:

1. Adapt Your UI

Modify your web application’s interface to work within an iframe context. Remove unnecessary elements and ensure a clean, focused user experience.

2. Test with Test Agent

Use the test agent to validate your UI changes:

Start a session with the test agent
Point it to your development URL
Verify that all UI elements render correctly
Test user flows and interactions

3. Integrate Metering API

Implement the Metering Report API to track usage:

Add metering calls at appropriate points in your application
Use unique meteringId values to ensure idempotency
Implement proper error handling and retry logic

4. Validate Billing

Test your metering integration end-to-end:

Use the test agent with the provided Metering API token
Perform actions that should trigger billing
Verify charges are reported correctly using the Metering Get Reports API
Check that you (as a test user) are actually being charged

🎨 UI Integration Guidelines

When integrating your application as an iframe agent, you must adapt your UI to provide a focused, embedded experience.

Required UI Modifications

Remove or hide the following elements from your iframe interface:

Session/Chat History
- Past conversation lists
- Session navigation controls
Project/Workspace Management
- Project lists or switchers
- Workspace selection
Resource Management
- File browsers
- Asset managers
User Account Elements
- User profile display
- Account settings
- Preferences/configuration panels
Session Control
- “New session” buttons
- Session switching/navigation
- Links to other sessions
Feedback Mechanisms
- Rating prompts
- Feedback forms
- Review requests
External Navigation
- Pricing pages
- Links to other websites
- Marketing content
- External redirects

Content Guidelines

Creators must ensure their embedded content:

Contains no terrorist-related material
Contains no child sexual abuse material (CSAM)
Complies with MuleRun’s content policies
Maintains appropriate content for all users

Example: Equity Investment Research Integration

Below are before/after examples showing how Equity Investment Research adapted their UI for iframe integration. Before Integration:

The original interface includes session history sidebar, user account menu, navigation controls, and other elements not suitable for iframe embedding. After Integration:

The iframe-optimized version focuses solely on the core agent interaction, removing all navigation, account management, and session control elements. Key Changes Made:

The diagram above highlights specific UI elements that were removed or modified for iframe compatibility.

🔐 Iframe Embedding Configuration

To allow MuleRun to embed your application, you must configure your web server to permit iframe embedding from MuleRun’s domain.

HTTP Headers Configuration

Configure the following HTTP security headers based on your server setup:

X-Frame-Options

The X-Frame-Options header controls which domains can embed your content in an iframe. Option 1: Allow MuleRun only (Recommended)

add_header X-Frame-Options "ALLOW-FROM https://mulerun.com";

Option 2: Allow all domains

add_header X-Frame-Options "ALLOWALL";

Content-Security-Policy (CSP)

Modern browsers prefer CSP’s frame-ancestors directive over X-Frame-Options. Option 1: Allow self and MuleRun (Recommended)

add_header Content-Security-Policy "frame-ancestors 'self' https://mulerun.com;" always;

Option 2: Allow all domains

add_header Content-Security-Policy "frame-ancestors *;" always;

Configuration Examples

Nginx

Add the following to your server block in your nginx configuration:

server {
    listen 443 ssl;
    server_name your-agent.example.com;

    # Allow MuleRun to embed your application
    add_header X-Frame-Options "ALLOW-FROM https://mulerun.com";
    add_header Content-Security-Policy "frame-ancestors 'self' https://mulerun.com;" always;

    # ... rest of your configuration
}

Apache

Add the following to your .htaccess or Apache configuration:

# Allow MuleRun to embed your application
Header always set X-Frame-Options "ALLOW-FROM https://mulerun.com"
Header always set Content-Security-Policy "frame-ancestors 'self' https://mulerun.com;"

Node.js (Express)

app.use((req, res, next) => {
  res.setHeader('X-Frame-Options', 'ALLOW-FROM https://mulerun.com');
  res.setHeader('Content-Security-Policy', "frame-ancestors 'self' https://mulerun.com;");
  next();
});

Testing Your Configuration

After configuring your headers, verify they’re set correctly:

curl -I https://your-agent.example.com | grep -i "frame\|content-security"

You should see output similar to:

X-Frame-Options: ALLOW-FROM https://mulerun.com
Content-Security-Policy: frame-ancestors 'self' https://mulerun.com;

Some browsers have deprecated X-Frame-Options in favor of CSP’s frame-ancestors. It’s recommended to set both headers for maximum compatibility.

📋 Pre-Launch Checklist

Before submitting your iframe agent for review, ensure you’ve completed the following:

Quickstart

Creator Studio

Agent

Tutorials

MuleRouter Pricing

Marketing

​🔍 Introduction

​🏗️ System Architecture

​Component Summary

​📈 Agent Configuration Params

​🔌 Iframe URL Protocol

​Behavior Overview

​URL Schema Design

​Routing Example

​Parameter Definitions

​Example URL

​Signature Generation (Python Example)

​Signature Verification (Python Example)

​🔒 Security Considerations

​📊 Metering APIs

​Metering Report API

​Metering Get Reports API

​🧪 Testing and Debugging

​Reference Implementation

​Test Agent

​🔄 Development Workflow

​1. Adapt Your UI

​2. Test with Test Agent

​3. Integrate Metering API

​4. Validate Billing

​🎨 UI Integration Guidelines

​Required UI Modifications

​Content Guidelines

​Example: Equity Investment Research Integration

​🔐 Iframe Embedding Configuration

​HTTP Headers Configuration

​X-Frame-Options

​Content-Security-Policy (CSP)

​Configuration Examples

​Nginx

​Apache

​Node.js (Express)

​Testing Your Configuration

​📋 Pre-Launch Checklist

🔍 Introduction

🏗️ System Architecture

Component Summary

📈 Agent Configuration Params

🔌 Iframe URL Protocol

Behavior Overview

URL Schema Design

Routing Example

Parameter Definitions

Example URL

Signature Generation (Python Example)

Signature Verification (Python Example)

🔒 Security Considerations

📊 Metering APIs

Metering Report API

Metering Get Reports API

🧪 Testing and Debugging

Reference Implementation

Test Agent

🔄 Development Workflow

1. Adapt Your UI

2. Test with Test Agent

3. Integrate Metering API

4. Validate Billing

🎨 UI Integration Guidelines

Required UI Modifications

Content Guidelines

Example: Equity Investment Research Integration

🔐 Iframe Embedding Configuration

HTTP Headers Configuration

X-Frame-Options

Content-Security-Policy (CSP)

Configuration Examples

Nginx

Apache

Node.js (Express)

Testing Your Configuration

📋 Pre-Launch Checklist