ElizaOS plugin for Operon — the open ad network for AI agents. Add quality-weighted sponsored placements to your agent's responses with zero prompt engineering.
The plugin runs a Provider that fires on every message. It sends the user's query to Operon's placement API, which runs a quality-weighted auction across registered advertisers. Context fields (category, asset, intent) are configurable via settings with empty defaults — the Operon server handles matching and returns blocked when nothing fits.
If a relevant, trustworthy service matches:
- The sponsored recommendation is injected into your agent's context
- Your agent naturally incorporates it into the response
- The placement is logged as an impression on the Operon server
If nothing matches, the agent responds normally. No degradation, no empty ad slots.
Under the hood, this plugin is a thin ElizaOS adapter on top of @operon/sdk. The SDK owns network, retries, the circuit breaker, the per-client UUID, and source attribution; this package just maps ElizaOS settings and message lifecycle into SDK calls.
npx @elizaos/cli plugins add @operon/plugin-publisher-sdkOr manually:
npm install @operon/plugin-publisher-sdkSet the following environment variables (or character settings):
| Setting | Required | Description |
|---|---|---|
OPERON_API_URL |
yes | Operon network endpoint, e.g. https://api.operon.so. Legacy alias OPERON_URL still works. |
OPERON_API_KEY |
no | Publisher API key from Operon. Omit to run in sandbox mode — the SDK mints a stable client UUID locally and the server treats traffic as sandbox. |
OPERON_PUBLISHER_NAME |
no | Publisher identifier (defaults to character name). |
OPERON_CATEGORY |
no | Category, e.g. defi. Legacy alias OPERON_DEFAULT_CATEGORY. |
OPERON_INTENT |
no | Intent, e.g. swap. Legacy alias OPERON_DEFAULT_INTENT. |
OPERON_ASSET |
no | Asset, e.g. ETH. |
OPERON_SOURCE |
no | Marketplace/skill attribution tag (first-touch wins; see @operon/sdk docs). |
OPERON_ALLOW_HTTP |
no | Set to "true" to allow plain HTTP (development only). |
OPERON_DEBUG |
no | Set to "true" to log connection details. |
import operonPublisherPlugin from "@operon/plugin-publisher-sdk";
export const character: Character = {
name: "MyResearchAgent",
plugins: [operonPublisherPlugin],
settings: {
secrets: {
OPERON_API_URL: process.env.OPERON_API_URL,
OPERON_API_KEY: process.env.OPERON_API_KEY, // optional
},
},
// ...
};{
"name": "MyResearchAgent",
"plugins": ["@operon/plugin-publisher-sdk"],
"settings": {
"secrets": {
"OPERON_API_URL": "https://api.operon.so",
"OPERON_API_KEY": "your-publisher-key"
}
}
}If OPERON_API_KEY is omitted, the plugin runs in sandbox mode:
- The SDK mints a UUID at
~/.operon/client.jsonon first call (override withOPERON_CLIENT_IDfor read-only filesystems). - Traffic is unauthenticated and is treated as sandbox by the server.
- Use this for local development before requesting a publisher key.
To register as a real publisher, install the SDK CLI and follow the prompts: npx @operon/sdk register.
When a sponsored placement fills:
[Sponsored] Relevant service available: Jupiter Aggregator
- Best-rate DEX aggregation across Solana
- Trust score: 82/100
When nothing matches, the response is clean — no mention of Operon or sponsorship.
The plugin sends the following to the Operon API on every message:
- User's message text — forwarded as the placement query and
placement_context - Publisher name — your agent's identifier
- Category, intent, asset — whatever you set via settings (empty by default)
X-Operon-Clientheader — stable UUID from~/.operon/client.json(or env override)X-Operon-Sourceheader — only whenOPERON_SOURCEis set
No wallet addresses, private keys, or credentials are extracted or sent separately, but any content in the user's message text will be included in the API request. Publishers should consider this when deciding whether to integrate the plugin.
See operon-otaku for a complete example of an ElizaOS agent with the Operon plugin integrated.