> For the complete documentation index, see [llms.txt](https://docs.ojin.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ojin.ai/apps/overview/configure.md).

# Create & Configure

Set up your Human Agent in the Ojin dashboard. Pick a mode, configure appearance and behaviour, and publish it.

## Prerequisites

1. An Ojin account. An API key is only needed if you will manage agents from your own backend rather than the dashboard, [get your API key](/getting-started/authentication.md)

## Creating an Agent

Head to the [Ojin dashboard](https://ojin.ai/dashboard) and create a new agent. Give it a name and pick your mode:

* **Ojin Agent**: Ojin handles everything: the conversational pipeline and avatar rendering. You just configure the personality and appearance.
* **Third-Party Agent**: you bring your own speech-to-speech provider (ElevenLabs Agents or OpenAI Realtime). Ojin adds the visual avatar.

### Starting from a Preset

If you choose Ojin Agent mode, you can start from a preset, a ready-made template that pre-fills the face, voice, system prompt, and behaviour for common use cases like Customer Support, Sales Assistant, or Receptionist. You can customize everything after creation.

Alternatively, start blank and configure each field yourself.

## Editing and saving

Edit an agent's name and description in the header of its configure page. Text appears as you type and stays visible when you click away. A name is required. Leaving the name blank shows **Name is required** when you leave the field.

Valid changes save automatically one second after your last edit. The status beside the agent's name shows the save progress:

* **Unsaved changes**: edits are waiting for autosave.
* **Saving…**: a save is running or waiting for an earlier save to finish.
* **Saved**: the latest valid changes have finished saving.
* **Couldn't save**: a save failed. Your text remains editable so you can correct it and try again.

You can keep editing while a save runs. Your latest edits remain visible while changes save in order. The dashboard sends valid pending edits when you switch agents or move to another dashboard page. Wait for **Saved** before closing or reloading the browser.

## Configuring an Ojin Agent

### System Prompt

Write a prompt that defines how the agent behaves: its personality, tone, and any instructions for the conversation. This works the same as a system prompt for any LLM. For documents and reference material the agent should answer from, use [Knowledge](/apps/overview/knowledge.md) rather than pasting them into the prompt.

#### Expressions

Under the system prompt you can set how the agent uses voice cues such as laughs, sighs and whispers. The agent's voice performs them, and they never appear in the chat transcript or the captions. They apply when the agent speaks through ElevenLabs.

* **Expressions** sets how often the agent uses them: Off, Subtle, Balanced (the default) or Expressive. Off means the agent speaks without laughs, sighs or other cues.
* **Laughter, Whispering, Sighs and breaths, Tone shifts, Crying** turn each kind on or off. When a kind is off, the agent never does it. It is removed before the voice is generated, so it cannot slip through.
* **Delivery note** is one short rule, up to 300 characters. Example: "Never laugh while the user describes a problem."

Changes apply to the next session. You do not need to edit the system prompt.

### Face

Pick a visual appearance for your agent. The face is powered by one of Ojin's face models, [Human Presence](/models/human-presence.md) or [Human Portrait](/models/human-portrait.md), which generate lifelike personas from a single reference image. Browse the available face configurations in the dashboard and select the one that best fits your agent's personality.

Production keeps the existing face selector. The searchable face field and live-switch behavior below are enabled only in the local/staging trial.

In the local/staging trial, search by name and scroll to load more organization faces and templates. To add a face, choose **New face** or drop a JPEG, PNG, or WebP image on the face thumbnail or picker; the create dialog lets you name it before saving.

Changing between Human Presence and Human Portrait in the local/staging trial keeps the selected portrait. When Ojin creates a face configuration for the new model, it carries over the portrait and settings that model accepts; other settings use that model's defaults. If you switch back to a model already used in the current configure session, Ojin reuses its configuration. If the target model or a compatible configuration cannot be loaded or applied, the current saved face stays selected and the picker shows feedback.

Changing a face model does not reallocate an active call. During a local/staging preview call, you can still choose a face, but the model picker is disabled until the call ends. A connected local/staging preview updates in place only when its host and allocated face model support live switching; otherwise, the saved face is used the next time the agent connects. During a supported refresh while a preview call is connected, the preview keeps its size. The current face blurs for 160 ms, then the requested portrait eases in over 200 ms, and the cover stays until the new video frame is confirmed. If the refresh fails, or the requested portrait cannot be loaded, the last usable face returns and the widget shows retry guidance. An idle face change, when the preview is not in a call, swaps straight to the new portrait with no cover, blur, or loading indicator. If that idle change fails during the refresh, the retry message shows and the previous portrait stays. Reduced motion skips the live blur, the portrait ease, and the cover reveal, shows the requested portrait immediately, and follows a change to that setting during the switch. After a failed live switch, the retry guidance stays once the cover lifts and the previous face is back. Production keeps its existing face-selection and preview-refresh behavior.

### Captions

Choose the caption treatment shown over the avatar while it speaks:

* **Off**: do not show captions
* **Conversation**: calm captions with active-word emphasis
* **TikTok**: kinetic one-to-four-word beats with active-word emphasis
* **YouTube**: bold, uppercase karaoke captions
* **Arthouse**: restrained cinematic subtitles
* **Journalist**: an editorial caption pill with an active-word underline

The dashboard also lets you choose dark or light text, an accent colour, text size, and no background or a solid background. Arthouse always uses its yellow text without a background. The widget uses the style's matching typeface and animation automatically.

Caption settings belong to the agent creator. Viewers cannot override or turn them off. The widget temporarily hides captions while its chat panel is open. New agents start with captions off until their creator chooses a style.

### Voice

Select a TTS voice for the agent's speech output. The voice determines how the agent sounds when it responds.

Ojin Agents speak through ElevenLabs. The default model is `eleven_v4_turbo`, which performs audio tags: the agent's language model can open a sentence with a delivery cue such as `[laughs]` or `[whispers]`, and the voice performs it. You do not need to write anything about tags in your system prompt. Ojin adds the instructions, and the tags never appear in the chat transcript or the captions.

To put one agent on a different ElevenLabs model, set `elevenlabs_model` in the agent's `advanced_overrides` (for example `eleven_flash_v2_5` for the classic text-to-speech path, which does not perform tags). An `eleven_v3` model needs a voice selected for the agent, and that voice cannot be a professional voice. An `eleven_v4` model uses the agent's voice, or the default voice when the agent has none.

### Behaviour

Configure how the agent interacts:

* **Starts conversation**: whether the agent speaks first or waits for the user
* **Greeting**: the first thing the agent says when a session starts. Either spoken verbatim, or composed from a style reference
* **Farewell**: what the agent says when the session ends
* **Inactivity nudge**: a message the agent sends if the user stays silent, with the delay in seconds
* **Max conversation length**: how long a conversation may run, in seconds
* **Allow interruption**: whether the user can talk over the agent

The voice you pick also sets the agent's language (English, German, French, Spanish, Arabic or Japanese).

### Knowledge

Tick the collections of your organization's knowledge the agent answers from, either in its prompt or by searching them during the conversation. See [**Knowledge**](/apps/overview/knowledge.md) for adding knowledge, collections, limits, and what callers can ask the agent to repeat.

### Tools (Function Calling)

Give the agent tools it can call during a conversation, to look something up, update your UI, or notify a backend. Add and configure tools here, choosing how each one's calls are delivered (to a webhook or to the embedding page). See [**Tools & Events**](/apps/overview/tools.md) for the delivery modes and how to handle calls.

### Advanced Settings

* **Max response length**: the token ceiling for a single agent reply (64 to 4096, default 384)

Developer accounts also get an overrides field for pipeline settings that are not exposed in the UI.

### Session length

Set **Max conversation length** in seconds under Behaviour. A dashboard-created agent defaults to 360 seconds (6 minutes), and the hard session cap sits 60 seconds above whatever you set. The allowed range is 1 to 86400 seconds. When the cap is reached, the session ends automatically.

## Configuring a Third-Party Agent

### Face

Same as Ojin Agent. Pick a visual appearance using [Human Presence](/models/human-presence.md) or [Human Portrait](/models/human-portrait.md). Regardless of which provider powers the conversation, Ojin renders the avatar.

### Provider

Select your speech-to-speech provider from the dropdown:

* **ElevenLabs Agents**: enter your ElevenLabs API key and your ElevenLabs agent ID (both required). To fill the ElevenLabs agent's `{{placeholders}}` for each chat, see [Dynamic Variables for ElevenLabs Agents](/apps/overview/widget-integration.md#dynamic-variables-for-elevenlabs-agents).
* **OpenAI Realtime**: enter your OpenAI API key. Voice, instructions, model and turn-detection mode are optional.

**Hume** is also supported, but only for organisations that have been enabled for it. If your organisation has not, Hume does not appear in the dropdown. Ask support if you need it.

{% hint style="warning" %}
Your provider API key is encrypted at rest and never displayed after you save it. To rotate a key, enter the new one in the dashboard. It takes effect for new sessions immediately.
{% endhint %}

## Publishing your agent

When your agent is configured, publish it from the **Publish** tab in the [dashboard](https://ojin.ai/dashboard). An agent is either published or unpublished. The system validates that all required fields are filled before allowing it to go live:

* **Ojin Agent** requires: a name, instructions (the system prompt), a voice and its voice provider, and a face
* **Third-Party Agent** requires: a name, a provider, and that provider's required credentials (the API key, plus the agent ID for ElevenLabs Agents)

A face is strongly recommended for a third-party agent but is not enforced at publish time.

If anything is missing, the dashboard tells you which fields need attention.

## Concurrency

The **max concurrency** setting caps how many sessions your agent runs at once. New agents are **unbounded** by default (`max_concurrency` is `-1`). Set a positive value between 1 and 100 to cap it. The field is set through the API rather than the dashboard.

When all slots are in use, new connection attempts get a `429` whose `error` is `concurrency_limit`, with a `retry_after_seconds` hint.

## Next Steps

* [**Tools & Events**](/apps/overview/tools.md): give the agent function-calling tools and react to it from your page
* [**Widget Integration**](/apps/overview/widget-integration.md): add the agent to your web page
* [**Session API Reference**](/apps/overview/api-reference.md): for custom integrations


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ojin.ai/apps/overview/configure.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.