How to Embed 3D On-Chain Agents on Your Site

This guide walks through embedding a three.ws 3D agent on any website — from creating the agent to dropping the <agent-3d> snippet into your HTML and configuring the page integration.

Step 1 — Create your agent in Widget Studio

Go to three.ws/widget-studio and create an agent. You'll configure:

• Avatar. Choose from the three.ws gallery or upload a custom GLB file.
• Persona. Name, personality description, and system prompt for the LLM.
• LLM brain. Claude, GPT, or another supported model.
• Voice. TTS provider and voice selection.
• Skills. What tools and capabilities the agent has access to.
• Allowed origins. The domains that are permitted to embed this agent — required for the action bridge to work.

Step 2 — Copy the embed snippet

After saving, the Studio gives you an embed snippet that looks like this:

<script src="https://three.ws/agent.js"></script>
<agent-3d agent-id="your-agent-id"></agent-3d>

That's the minimum. The script registers the custom element and the tag renders the agent. Add it anywhere in your HTML — the agent loads asynchronously and won't block the rest of your page.

Step 3 — Place the tag

The <agent-3d> element behaves like any inline block element. By default it renders at a sensible size in the flow of your page. Common placements:

Fixed corner widget (most common)

<style>
  agent-3d {
    position: fixed;
    bottom: 24px;
    right: 24px;
    width: 280px;
    height: 400px;
    z-index: 999;
  }
</style>
<agent-3d agent-id="your-agent-id"></agent-3d>

Inline in a section

<section class="hero">
  <div class="hero-copy">
    <h1>Your headline</h1>
    <p>Your description</p>
  </div>
  <agent-3d agent-id="your-agent-id" style="width:360px;height:520px;"></agent-3d>
</section>

Step 4 — Wire page events (optional)

The agent can receive events from your page and send events back. Use the postMessage action bridge:

Send an event to the agent

const agent = document.querySelector('agent-3d');
agent.postMessage({ type: 'event', name: 'cart-updated', data: { items: 3 } });

Listen for events from the agent

window.addEventListener('message', (e) => {
  if (e.data?.source === 'agent-3d') {
    console.log('Agent event:', e.data);
  }
});

Set emotion or animation from JavaScript

agent.postMessage({ type: 'set-emotion', emotion: 'excited' });
agent.postMessage({ type: 'play-animation', clip: 'wave' });

Step 5 — Configure mode and size

The <agent-3d> element accepts attributes for common configuration without JavaScript:

<agent-3d
  agent-id="your-agent-id"
  mode="minimal"
  theme="dark"
  start-open="false"
></agent-3d>

• mode — full (default, chat + 3D), minimal (3D only, no chat panel)
• theme — dark or light
• start-open — whether the chat panel opens automatically on load

Common issues

• Agent renders but action bridge doesn't work. Add your domain to the allowed origins list in the Widget Studio.
• Agent doesn't render at all. Check that your browser supports WebGL (all modern browsers do). Check the console for errors.
• Agent is the wrong size. Size it with CSS on the agent-3d element selector — it respects width and height like a replaced element.

Links

• Widget Studio: three.ws/widget-studio
• Full docs: three.ws/docs
• Web component reference: three.ws/docs/agent-3d

← All posts