Publish an agent to embed it on external sites. Visitors chat without signing in; your workspace pays for inference.
Publish from the web app
- Open your agent in Agents.
- Go to the Publish tab.
- Turn on Published.
When published:
- The agent is available at an embed URL:
https://app.inference.sh/embed/agents/{namespace}/{name} - You receive an iframe snippet to paste into your site.
- You pay for all inference costs when others use the embedded agent.
Save the agent before publishing — the Publish tab is available only after the agent exists.
A2A agent card (marketplace listings)
For Agent2Agent (A2A) discovery and partner marketplaces (for example GCP AI Agents Producer Portal), open the agent detail page and click a2a card in the header to copy the agent card JSON to your clipboard.
The card's url field is the agent's A2A service endpoint (https://api.inference.sh/agents/{namespace}/{name}/a2a); documentationUrl points at the workspace page. The same payload is available via GET /agents/{namespace}/{name}/card — see Agents API — Get A2A agent card and A2A protocol.
Publish via REST API
Automate publishing with the Publications API. Create, update, and delete publications with an API key that has the agents:write scope:
1# Publish an agent2curl -X POST https://api.inference.sh/publications \3 -H "Authorization: Bearer inf_your_key" \4 -H "Content-Type: application/json" \5 -d '{6 "resource_type": "agent",7 "resource_id": "agent_abc123"8 }'List existing publications with GET /publications?resource_type=agent&resource_id={agentId} (agents:read scope). Ownership is enforced server-side: you can only publish agents your workspace can write.
Allowed origins
Restrict which sites can load the embed in an iframe:
| Setting | Behavior |
|---|---|
| Empty | Any origin may embed (default) |
| Comma-separated URLs | Only matching Origin headers are accepted (for example https://example.com) |
* in the list | Explicit wildcard — same as empty |
The API checks the browser Origin header on embed requests. Mismatched origins receive 403 Forbidden (origin not allowed).
Custom theme
Optional branding for the embedded chat UI:
- Light mode colors: primary, secondary, background, text, border
- Dark mode colors (optional): same fields
Theme colors are returned by GET /embed/agents/{namespace}/{name} and applied to the hosted embed page.
Embed on your site
Copy the iframe snippet from the Publish tab:
1<iframe2 src="https://app.inference.sh/embed/agents/myteam/support-agent"3 width="400"4 height="600"5 style="border: none; border-radius: 12px;"6 allow="clipboard-write"7></iframe>Replace myteam/support-agent with your agent's namespace and name.
For custom integrations (your own UI, host-page context, programmatic chat), use the Embed API instead of the hosted iframe.
Host page context (optional)
When you build a custom embed UI, the host page can pass context into the iframe and receive actions back via postMessage.
Host → embed (send context after the iframe loads):
1iframe.contentWindow.postMessage({2 type: 'embed:context',3 payload: {4 url: window.location.href,5 userId: 'user_123',6 plan: 'pro',7 },8}, '*');Embed → host (readiness and actions):
| Message | Direction | Purpose |
|---|---|---|
embed:ready | embed → host | Iframe is listening for context |
embed:context | host → embed | Merge key/value context for the agent |
embed:action | embed → host | Agent invoked send_to_host (includes id, action, params) |
embed:action:result | host → embed | Response to an action (id, result) |
Host context tools (get_host_context, send_to_host) are deprecated and disabled: agents are no longer offered them, so the embed:action messages above are not sent. A replacement for passing host page context to embedded agents is planned.
→ Embed API — REST endpoints and SDK client setup
→ Internal tools — host context (deprecated)
Billing and limits
Embedded runs use the publisher's workspace for billing and entitlements. Anonymous visitors do not need API keys.
If the publisher's balance is insufficient, embed runs may return 402 Payment Required.