Avatar Agent Builder Documentation
Introduction
Avatar Agent Builder is a platform for building and installing 2D and 3D avatar agents on websites through an intuitive node-based editor. Without coding knowledge, users can connect nodes to control speech recognition, AI responses, speech synthesis, and avatar rendering in one flow.
System architecture
On the frontend, a React-based UI provides the node editor canvas and property panels. Users can build agent pipelines visually by operating nodes.
The node system consists of a node registry, node executor, and parameter validators. It owns node definitions, execution, and input validation.
The API integration layer centralizes clients for STT, LLM with RAG, TTS, avatar control, vector stores, and embed generation, then manages external API communication.
Supported external APIs include OpenAI, Aivis Cloud, ElevenLabs, Azure Speech, Google Cloud, and other providers that can be combined by use case.
The data layer uses Supabase (Postgres + RLS), Cloudflare R2, D1, and Vectorize. API keys are encrypted before storage. Supabase Auth handles authentication, and the Cloudflare Worker acts as the backend-for-frontend.
Basic usage
1. Select a template
Prepared agent templates are shown in the left panel of the editor. Choose the template that fits your use case.
- 2D avatar template - an agent using illustrations, images, or Live2D characters
- 3D avatar template - an agent using realtime animated 3D models
After selecting a template, the required nodes are placed on the canvas automatically.
2. Configure nodes
Click each node on the canvas to edit details in the property panel on the right. The main node types are listed below.
- STT node - receives microphone input and converts speech to text, including OpenAI Whisper, Azure, and Google Cloud support
- LLM node - receives text input and generates AI responses. Enabling RAG allows answers grounded in your own documents.
- TTS node - converts text to speech, including Aivis Cloud, ElevenLabs, and Azure support
- Avatar node - controls avatar display, animation, lip sync, and related behavior
- Vector store node - handles document embedding and search for RAG
Nodes can be connected with drag and drop. Connecting an output port to another node input defines the data flow.
3. Run the agent
When configuration is complete, click the Run button at the top of the screen. Nodes execute in order, and the preview area shows the agent behavior. If errors occur, the relevant node is highlighted so you can fix it in the property panel.
4. Get the code snippet
After verifying behavior, click the code snippet button next to Run. The HTML snippet required for website embedding is displayed. Use the copy button to copy it to the clipboard.
<!-- 生成されるスニペットのイメージ -->
<script src="https://cdn.example.com/avatar-agent.js"
data-agent-id="YOUR_AGENT_ID"
data-theme="light">
</script>
<div id="avatar-agent-root"></div>5. Paste it into your website
Paste the copied snippet into the HTML source of the web page where you want the agent to appear. We recommend placing it immediately before the</body>tag. Save and publish the page to show the agent.
<!-- 例: ページ末尾への挿入 -->
...
<script src="https://cdn.example.com/avatar-agent.js"
data-agent-id="YOUR_AGENT_ID">
</script>
<div id="avatar-agent-root"></div>
</body>
</html>API key setup
To use external APIs, register each service API key in advance. Open the API management tab in settings and enter the API key for the service you want to use. Registered keys are encrypted and stored securely, then used automatically when the agent runs.
Stripe billing
Professional / Team purchases are made from the Pricing page with Stripe Checkout. After purchase, you can review subscription status on the Subscription page and open Billing Portal to manage payment methods and invoices.
The Cloudflare Worker requires `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `STRIPE_PRICE_ID_PROFESSIONAL`, and `STRIPE_PRICE_ID_TEAM`. Webhooks use `/api/billing/webhook`.
See `docs/stripe-billing.md` for detailed setup steps.
Using RAG
When RAG is enabled on an LLM node, responses can reference your own documents and internal data. Add a vector store node and upload files such as PDFs or text documents. Uploaded data is stored in Cloudflare Vectorize and searched automatically during conversations.
FAQ
Q. Can I use it for free?
Available node counts and API call counts differ by plan. See the pricing page for details.
Q. Can I install the same agent on multiple websites?
Yes. Paste the same snippet into multiple pages to use the same agent on any site.
Q. Does it work on mobile browsers?
Yes. When microphone input is used, the browser must grant microphone access.
Q. Can I customize the avatar design?
2D templates can use custom images or Live2D models, and 3D templates can use glTF/VRM models. Upload them from the avatar node property panel.
Support
If you have questions, contact support from the support page or the official Discord server.