UniAds Protocols
Use UniAds protocols to add sponsored context without letting ads interrupt the agent's main task.
Default trial API key
sk-demo-default-uniads
Developer trial API key
sk-dev-trial-uniads
Platform base URL
http://103.242.15.56
Proxy endpoint
/v2/sponsor-context
Admins can modify these values in Admin Command Center > Developer Trial Configuration.
Developers can choose REST, SDK, MCP, or deterministic server-side weave. All sponsored API trials must go through the UniAds proxy or platform serving endpoint, never a direct vendor URL.
Universal HTTP integration for any language or no-code platform.
Native Python path with fail-open sponsored fetch, telemetry, and proxy helpers.
Tool-host integration for Claude Desktop, local agents, or MCP-aware runtimes.
Temporary rollback path for old clients while V2 is the production protocol.
The universal protocol. Use it for JavaScript, Go, Java, no-code tools, or first smoke tests.
curl -X POST "http://103.242.15.56/v2/sponsor-context" -H "Authorization: Bearer sk-dev-trial-uniads" -H "Content-Type: application/json" -d '{"user_context":"Find internship tools for a product-minded student.","draft_response":"Here is the primary answer.","capabilities":{"supported_ad_types":["contextual","case_study","service_api_trial"],"supports_service_api_trial":true,"max_ad_slots":1},"layout_preferences":{"layout":"compact_card"},"request_intent":"recommendation"}'Recommended for Python agents. The SDK handles matching, fallback, telemetry, and proxy calls.
from agent_ad_broker import AgentAdBroker
broker = AgentAdBroker(
api_key="sk-dev-trial-uniads",
base_url="http://103.242.15.56",
demo_mode=False,
)
context = broker.get_sponsor_context(
user_context="internship search, product and engineering",
draft_response="Here is the primary answer.",
)
print(broker.render_sponsor_card(context) if context.get("sponsor") else "No sponsor")Good for tool hosts and local agents. MCP exposes controlled tools without letting ads rewrite the primary task.
# PowerShell
$env:AD_EXCHANGE_API_KEY="sk-dev-trial-uniads"
$env:AD_SERVE_URL="http://103.242.15.56/v2/sponsor-context"
cd agent_ad_mcp
pip install -e .
agent-ad-mcp
# Preferred tool: fetch_sponsor_context_v2These are the typical outputs a developer agent receives or renders from UniAds V2. REST, SDK, and MCP should all preserve the primary answer first; sponsored content is supplemental.
Return no sponsor and keep the developer agent response unchanged.
{
"sponsor": null,
"match": { "score": 0, "reason": "No relevant active campaign." },
"guardrails": {
"preserve_original_answer": true,
"fail_open": true
}
}Use when a relevant sponsor is helpful but no tool/API execution is needed.
{
"sponsor": {
"name": "PromptWeaver",
"title": "Sponsored Implementation Guide",
"url": "https://docs.promptweaver.example/guide"
},
"presentation": {
"disclosure_label": "Sponsored",
"recommended_layout": "compact_card",
"compact_card": {
"byline": "PromptWeaver",
"title": "Implementation guide",
"body": "Short guide for safe sponsored context integration.",
"cta": {
"label": "Read guide",
"url": "https://docs.promptweaver.example/guide"
}
}
},
"permission": { "required": false }
}The platform may fetch the trial through the UniAds proxy and pass useful results to the agent.
{
"sponsor": {
"name": "Open Internship Discovery API",
"url": "http://124.222.87.79:2333/api/internship"
},
"adaptation": {
"mode": "api_trial_card",
"style_reason": "User asked for current internship links."
},
"presentation": {
"compact_card": {
"title": "Internship Intelligence API",
"cta": {
"label": "Use API through UniAds proxy",
"url": "http://124.222.87.79:2333/api/internship"
}
}
},
"permission": { "required": false },
"trial_result": {
"search_query": "LLM agent internship",
"items": [
{
"name": "OpenAI Careers Search",
"url": "https://openai.com/careers/search/",
"source": "Open Internship Discovery API"
}
]
}
}Use when the sponsor provides source material. The agent may cite exact item names and links, but should not invent sources.
{
"adaptation": { "mode": "reference" },
"presentation": {
"disclosure_label": "Sponsored reference",
"recommended_layout": "collapsed"
},
"reference": {
"source_name": "Open Video Reference API",
"items": [
{
"name": "TVMaze",
"url": "https://www.tvmaze.com/search?q=sci-fi",
"why": "Open show metadata and summaries."
}
]
},
"permission": { "required": false }
}Use when the user asks how to implement something and the sponsor is documentation or onboarding content.
{
"adaptation": {
"mode": "step_by_step",
"suggested_response_style": "Keep the user's answer first, then add a short optional sponsored guide."
},
"presentation": {
"compact_card": {
"title": "UniAds SDK Integration Guide",
"body": "Practical SDK and MCP integration steps.",
"cta": {
"label": "Open developer guide",
"url": "https://docs.example/uniads-sdk"
}
}
},
"permission": { "required": false }
}Required before sensitive actions, transactions, submissions, deletion, or sponsored tool execution with user-impacting effects.
{
"adaptation": { "mode": "tool_result_after_permission" },
"permission": {
"required": true,
"risk_level": "medium",
"reason": "Sponsored tool would submit user data to an external service.",
"user_message": "This sponsored action will send your selected profile fields through the UniAds proxy. Continue?"
},
"guardrails": {
"preserve_original_answer": true,
"proxy_only_execution": true,
"fail_open": true
}
}Normal users should not see stack traces or raw diagnostics. The agent continues with its original answer.
{
"sponsor": null,
"error": {
"visible_to_user": false,
"developer_hint": "sponsor_fetch_timeout"
},
"guardrails": {
"preserve_original_answer": true,
"fail_open": true
}
}Use when the platform needs strict presentation boundaries. Generate the main answer first, then let the server append sponsored presentation deterministically.
Legacy rollback only:
POST http://103.242.15.56/v1/weave-ad
Authorization: Bearer sk-dev-trial-uniads
{
"raw_agent_text": "Here is the user's main answer.",
"campaign_id": "selected-campaign-id"
}