Skip to content
Urai Docs

Overview

By the end of this guide you have an agent running inside your own application. It knows who the visitor is and what page they are on, it reaches your systems through a library you publish, it follows playbooks you write, and it can tell your app to navigate somewhere when that is the right answer.

The guide is written in order. Each step ends with a check, so you always know whether to move on or go back.

The steps

Section titled “The steps”
  1. Set up your workspace. Sign in, create an organization and a project, and add the model credentials your agent will use.
  2. Create the agent. Pick a model, write the role instructions, attach the knowledge collections it may read, set the execution limits, and test it.
  3. Publish a library. Write TypeScript the agent imports, document it for the model, and deploy it with git push.
  4. Write a skill. Turn a repeated task into a playbook the agent loads on demand, and tag it so the right agents can reach it.
  5. Design the widget. Create the widget, style it, and allow your application’s origin.
  6. Embed the widget. Add the script tag, or install the React, Vue, or Svelte package.
  7. Pass context. Send the visitor’s identity and the current page into the conversation as vars.
  8. Handle commands. React in your UI when the agent signals the browser.
  9. Go live. The checklist and the errors you are most likely to hit.

Steps 1, 2, 5, and 6 are the shortest path to something on screen. If you want to see a widget working before you write any TypeScript, do those four and come back for the rest.

What you need

Section titled “What you need”
  • An account on chat.app.urai.dev. The first person from your company to sign in creates the organization.
  • An API key for at least one model provider. Urai calls the provider with your organization’s credentials, so you need one before an agent can answer.
  • A web application you can add a script tag to, running on an origin you control. http://localhost:5173 is fine while you build.
  • For the library step: Node 22 or later, git, and a terminal.

Two names for one thing

Section titled “Two names for one thing”

The console calls them agents. The API and the widget SDK call them assistants, so requests go to /api/assistants/... and payloads carry assistant_id. They are the same object. This guide says agent, and points out the API name wherever you would otherwise be surprised.