D-ID Agent

The D-ID Agent component embeds a conversational AI avatar, a chatbot with a face and a voice, inside your project. The visitor speaks to it, and the agent can act on your project in return: change screen, read your data, run any action you have configured.

How the AI agent and your project fit together

Most components wait for your project to tell them what to do. This one also works the other way around, and that is the idea worth holding on to before anything else.

The division of work is simple:

• D-ID owns the conversation. The agent listens, understands, decides what to say, and says it with the face and voice you chose in D-ID Studio. The examples below use a museum guide, but the same pattern fits a product catalogue, a training app, or a reception kiosk.
• PandaSuite owns the application. Your screens, your collections, your Datastore, your actions.

The agent is driven by an AI model, and the hinge between the two worlds is a Client Tool. On D-ID, a Client Tool is a capability you promise the agent: a name, a description, and a list of arguments. The agent does not know how the tool works. It only knows that when the conversation calls for it, it may ask for the tool to be run, with arguments filled in from what the visitor said.

In PandaSuite, that promise becomes an event of the component. The agent calls the tool, the event fires with the tool’s arguments, and the actions you attached to that event run. If the agent expects something back, one of those actions answers it.

So a complete round trip looks like this:

Everything below is a way of setting up one part of that loop.

Add and configure the component

Click Components and add the D-ID Agent component to your screen. It is a visual component: it displays the official D-ID interface, avatar and controls included, in the area you give it.

Step 1: Enter your API key

In the Properties panel, paste your API key. You will find it in your D-ID account, under Settings > API Key.

Step 2: Pick your agent

Click Refresh next to the Agent property. The component asks D-ID for the agents of your key and fills the drop-down list. Pick the one you want.

Click Refresh again whenever you create a new agent in D-ID Studio, so the list catches up.

If the list stays empty, the key does not belong to the account that owns the agent. Check it in your D-ID account and press Refresh again.

Step 3: Synchronize

Double-click the component to open it, then press Sync.

You are now inside the component. Sync, the client tools and the agent prompt live here. The Properties panel and the Actions panel stay outside: use the breadcrumb at the top of the workspace to come back out. You will move between the two several times.

Synchronizing is the moment the component learns what your agent can do. In one pass, it:

• refreshes the list of your agents, the way Refresh does, and stops if the selected one is no longer there,
• reads the agent’s Client Tools and declares each one as an event of the component,
• reads the agent’s prompt into the Agent prompt field,
• creates, or reuses, the D-ID Client Key that lets your published project talk to the agent,
• uses the agent’s thumbnail as the component’s image when it can read it, so you recognize it on the workspace.

You should now see the agent’s name at the top of the component, the date of the last synchronization, and the list of its client tools with their arguments.

Let the AI agent act on your project

A Client Tool is an event

After a synchronization, each of the agent’s client tools appears in the Actions panel of the component, exactly like a native trigger event. Attach whatever actions you want to it.

The tool’s arguments travel with the event. Inside any action of that list, open the data binding window and choose From the selected event: the arguments are there, under their own names, ready to be bound. An argument whose name would clash with a reserved one appears under an alias, which the tool’s card spells out.

Example. A Museum Explorer app has a tool search_exhibits(query). A visitor says “do you have anything about volcanoes?”, the agent calls search_exhibits with query set to volcanoes, and the search_exhibits event fires in your project carrying that word. You attach an action that runs a Search, and you bind its Search Term with

.

That gets the search running, but the agent still hears nothing about volcanoes. Telling it what you found is a separate step, and the next section.

Answer the agent with Return a value

Some tool calls are questions. The agent asks, waits, and speaks what it gets back.

To answer, add the Return a value action to the event’s action list and fill its Response parameter. Bind it to anything your project can produce: a collection, a field of a Datastore, the result of a search, a plain constant.

A list holds at most one Return a value: once you have added it, Studio stops offering it for that list. Place it wherever you like in the list. It answers the call, and the actions after it still run, so you can answer quickly and keep working.

If an event has no Return a value, the agent receives a plain ok once the action list has finished, unless one of those actions failed, in which case the agent is told the call failed. That is the right answer for a tool that does something rather than reporting something, such as changing screen.

Name your tools in the agent prompt

This is the step that surprises people, so it is worth stating plainly: a tool that nothing in the prompt points to stays unused. A perfectly synchronized tool, with perfect actions behind it, waits until the instructions give the agent a reason to reach for it.

Naming the tool is the surest way, and the one to fall back on when the agent ignores a tool you expected it to use. Inviting the behaviour works too, when the tool’s own description is explicit enough: an agent told to navigate through the screens to illustrate its points will find a tool described as “Change the screen to illustrate what you are saying”. What never works is silence.

The Agent prompt field in the component shows the agent’s instructions as D-ID holds them, read at the last synchronization. Edit them there and press Save prompt: the text is saved on D-ID, for this agent.

Write the tools into the instructions in plain language, the way you would brief a new guide:

When a visitor asks what there is to see, call list_screens and describe the results. When they choose one, call change_screen with the matching screen so the app follows the conversation.

Create a Client Tool without leaving PandaSuite

You do not have to leave PandaSuite to give the agent a new capability. In the component, press New client tool. A panel opens with:

• Name: the name the agent will use. Letters, digits, _ and -, up to 64 characters. No spaces and no accents: write list_screens, not list screens.
• Description: what the tool does, in the agent’s own terms, from 1 to 500 characters. This is what the agent reads when it decides whether to call it.
• Arguments: one row per argument, each with a name, a type, a description and a Required checkbox. An argument name starts with a letter, then holds letters, digits or _. No - here, unlike the tool name.

Press Save changes. The tool is created on D-ID, attached to your agent, and declared as an event of the component in one go.

Four argument types are available, because an argument has to be something a language model can produce:

Type	What the agent sends	Typical use
String	text	a search query, a name, a free-form answer
Number	a number	a quantity, a year, a rating
Boolean	true or false	a yes or no
Page	a screen of your project	navigation, guided tours, “take me to the volcanoes”

Page is the interesting one. The argument arrives in your actions as a real screen, so you can bind it straight into Change screen. The agent still needs to know which screens exist: give a change_screen tool one argument of type Page, pair it with a list_screens tool that hands out the screens, and point the prompt at both.

Richer data belongs on the answer side, not the argument side. A tool returns a whole collection through Return a value without any of this.

Edit or remove a tool

Each tool in the list carries two buttons.

Edit reopens the panel on the existing definition. Saving rewrites the tool on D-ID, which matters when several agents of your account share it: they all get the new definition.

Remove deletes the tool on D-ID, for every agent that uses it, and deletes the event and its actions in your project. It asks for a second click before doing so.

Before any write, the component re-reads D-ID and refuses to overwrite something that changed there since your last synchronization. When that happens, press Sync and edit again.

A tool that is no longer on the agent is marked Not on the agent. Its event and its actions are kept, and you decide: Add to the agent puts it back, Remove drops it. Renaming a tool on D-ID never costs you your actions.

Drive the AI agent from your project

The conversation is not one-way. Use Interact with a component on the D-ID Agent component to reach:

Action	What it does
Speak	Makes the agent say a Text, which can be bound to your data
Play audio	Makes the agent play an audio file from an Audio URL
Interrupt	Stops the agent from speaking immediately
Microphone	Mute, Unmute or Toggle the visitor’s microphone
Speaker	Mute, Unmute or Toggle the agent’s audio output

Speak is how you make the agent say a text out loud: greet a visitor by name, read out a result, or comment on where the app just went. It speaks to the visitor in the agent’s own voice, so the text can come from anywhere in your project.

React to the conversation

Trigger events

Besides the client tools, the component fires these trigger events:

Event	Fires when	Carries
Session started	the connection to the agent is established
Session ended	the connection is closed, lost or fails	Reason: disconnected, closed or fail
Agent started speaking	the agent starts speaking
Agent stopped speaking	the agent stops speaking
Agent thinking	the agent starts generating a response
Error	D-ID reports an error, or an action could not run because the agent is not loaded yet	Code and Message

Exposed properties

The component exposes four values for data binding, under From a component. For most interfaces, the first two are all you need:

• Is connected: true while the session is live.
• Is talking: true while the agent is speaking.

Bind them to a listening indicator, to a pulse around the avatar, or to the visibility of a subtitle area. The two raw values are there when you want finer control:

• Connection state: new, connecting, connected, completed, disconnecting, disconnected, closed, fail. Both connected and completed mean the session is live: browsers differ on which one they end up reporting.
• Activity: IDLE, TALKING, LOADING, BUFFERING.

Component properties

Property	Description
API key	Your D-ID API key. Used in PandaSuite Studio only, never published.
Agent	The agent to embed. Press Refresh to list the agents of your key.
Custom domains	Your own origins where the published project runs, scheme included, for example https://kiosk.example. Use + Add for each one.
Auto connect	Connects to the agent as soon as the component is displayed, without waiting for the visitor to press the connect button.
Orientation	Vertical or Horizontal layout of the D-ID interface.
External ID	Optional visitor or session identifier passed to D-ID, to link the conversation to your own user. Read once when the component loads.

Publish your project

D-ID restricts an agent to the addresses it is allowed to run on. Synchronizing creates a Client Key that covers those addresses, or reuses one that already does.

The PandaSuite ones are handled for you: the PandaSuite Studio preview, the web viewer, and the local address used by the iOS and Android viewers. You only declare what PandaSuite cannot know.

If you publish on a custom domain, or embed your project in your own website, add that origin to Custom domains with + Add, then press Sync again so the key covers it.

A complete example: an AI avatar that guides the visitor

The goal: a visitor asks the avatar what there is to see, and the app follows the conversation.

Before you start: your API key is entered, an Agent is picked, you have pressed Sync once, and you are inside the component. The project holds a collection of exhibits and one screen per exhibit.

1. Create the tool that lists the exhibits.

In the component, press New client tool. Name it list_screens, describe it as “Lists the PandaSuite project screens”, and leave the Arguments list empty. Press Save changes.

2. Answer it.

Come back out with the breadcrumb, select the component, open Actions and click the + button. Your client tools are in the trigger list, alongside Session started. Choose list_screens, then add a single action: Return a value. Bind its Response parameter to the list of your project’s screens, under From project in the binding window, so the agent learns which screens it can ask for.

3. Create the tool that navigates.

Go back inside the component and press New client tool again. Name it change_screen, describe it as “Change the screen to illustrate what you are saying”, and add one argument: Screen, type Page, described as “The representation of a PandaSuite screen, obtained by the list_screens tool”, Required.

4. Make it navigate.

Back in Actions, on the change_screen trigger, add Change screen. Studio lists it as Go to screen once it is in place: same action, other name. Click the name of the destination parameter to open the binding window, then choose

. No Return a value is needed here: this tool acts, it does not report, so the plain ok the agent receives when the list has run is the right answer.

5. Tell the agent about both.

In Agent prompt, add a paragraph that names them, then press Save prompt:

You are a museum guide. When the visitor asks what there is to see, call list_screens and present the results in your own words. When the visitor picks one, call change_screen with the matching screen.

6. Test.

Preview the project, press the connect button on the avatar (or set Auto connect to Yes beforehand), and allow the microphone when the browser asks. Ask the avatar what there is to see. It should list your screens, and take you to the right one when you choose it.

If nothing happens, check the prompt first: it is the usual cause. To see whether a call lands at all, attach a temporary Change screen state action to the event, so you can watch it fire.

Best practices and limitations

• Describe tools for the agent, not for yourself. The name and the description are the only things the agent reads when it decides to call a tool. “Open the screen of an exhibit” earns a call; “nav handler v2” does not.
• Keep answers small. The answer reaches the agent as text, capped at 15 KiB. Anything longer is cut off silently, and a cut structured answer arrives broken. Return the handful of fields the agent needs to speak, not your whole database.
• One tool, one job. An agent chooses between tools by their descriptions. Two tools that overlap make that choice unreliable.
• The component reads its tools once, when it loads. A tool you add does not reach a project that is already running, and reconnecting does not help. Synchronize, then reload: restart the preview, or reload the page.
• The microphone is the browser’s decision. Browsers grant microphone access only on a secure https address, and only once the visitor allows it. Test the published project on its real address, not only in preview.
• Re-export an app published before this. Every viewer now carries answers back to the agent, but an app keeps running the viewer it was exported with. On an older export the event still fires and your actions still run, yet no tool call comes back to the agent, not even one without a Return a value that would simply have answered ok. Re-exporting is the fix.
• Avatar, voice, personality, greetings and knowledge stay on D-ID. Edit them in D-ID Studio and they take effect on the next connection, with no Sync needed. Sync brings back only the tools, the prompt and the agent’s picture.

See also

• Data binding to feed the agent’s answers from your project.
• Interactive actions for everything an event can trigger.
• Screens and Collection for the two things an agent most often needs to talk about.
• Custom components if you want to build a component that declares its own events the same way.