Iframe Agent Specs

​

🔍 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

​

📈 Agent Configuration Params

​

🔌 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

​

Parameter Definitions

​

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

✅ Recommended Validation Logic:

​

📊 Metering APIs

​

Metering Report API

• 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

​

Metering Get Reports API

• 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