Skip to main content
An agent profile stores persona, voice, greeting, and recording consent so you do not send a full configure frame on every call. Open Omni with session_label={agent_id}. Inline configure fields still win for that session. You can skip this page and launch an Agent in the console instead. Both write the same profile.

Create the profile

Scope: omni:session.
The response includes id (agent_...). List and read the same objects at GET /v1/agents and GET /v1/agents/{id}.

Bind a hosted knowledge base

Scope: kb:manage to create the base and documents, omni:session to bind.
Poll documents until status is indexed before you treat the site as ready. See Knowledge bases. If you already run retrieval, keep kb_endpoint on the Omni configure frame instead. Sandbox keys from POST /v1/sandbox/keys omit kb:manage. Create a console key when you need hosted KB writes.

Bind tools

Register a server tool with POST /v1/tools, then PUT /v1/agents/{id}/tools. Hosted catalog tools bind by name (datetime, web_search, and the rest). Do not put endpoint or webhook_url on the Omni configure frame. That is rejected as unsupported_tool_transport. Details: Omni tools. Greeting and consent: Agent greetings.

Open a session

session_label is an opaque tag. When it matches an agent id, Omni loads that profile. The same label is echoed to a customer kb_endpoint if you use one. Auth: Sec-WebSocket-Protocol: pyai-key.$PYAI_API_KEY in browsers, or Authorization: Bearer on the server. Frame contract: Omni wire protocol.

Website or phone

The hosted Call Now button is a console publish: Add your Agent to a website. Phone numbers stay on Twilio or managed telephony in the console.

Next

Launch an Agent

Same profile, console workflow.

Knowledge bases

Hosted files, URLs, and pasted text.

Omni overview

Connect without a stored profile.

API reference

/v1/agents schemas.