configure frame on every call. Open Omni with session_label={agent_id}. Inline configure fields still win for that session.
Agents is one product with UI and API access. The console and REST API write
the same saved profile; Omni runs its realtime calls. You can
build in the console, use code, or switch between them.
Use a key from the project you have selected in the console. Agents created with
that key appear under Your agents in that project. Instant sandbox keys
create separate sandbox projects; they do not automatically belong to an
existing console project.
Which API to use
The required agent and runtime scope is
omni:session. Additional knowledge
management and tool-registration operations have their own scopes. The existing
endpoint names are retained for compatibility; no client migration is required
for the unified Agents workspace.
Create the profile
Scope:omni:session.
agent_id (agent_...). List and read the same objects
at GET /v1/agents and GET /v1/agents/{id}. Partial updates use
POST /v1/agents/{id}; present fields are changed, null clears a field, and
omitted fields remain unchanged. GET /v1/agents lists active profiles across
the key’s organization; the console list is filtered to the selected project.
Open the saved agent’s API integration tab to get examples with its ID.
role activates PyAI’s role operating standard beneath your persona; your
persona remains authoritative for identity and business policy.
voice_instruct controls delivery on instruct-capable voice tiers. If omitted
or reset to null, managed Agents use PyAI’s natural conversational pace.
Add custom vocabulary
vocabulary is an optional Agent-owned list for distinctive names, brands,
products, or short phrases. A non-empty list is the opt-in. PyAI sanitizes the
list with the same rules used by Hear and keeps at most five effective terms.
Set vocabulary to [] or null to turn it off.
The sanitized list is fixed when a new Omni session starts and remains fixed
across a transport reconnect. Organization vocabulary from
/v1/hear/vocabulary is never applied to Omni. There is no inline Omni
vocabulary override in this release. Update the Agent before starting a new
session when the list needs to change.
Use a short, specific list. Custom vocabulary can improve rendering of known
entities while making unrelated words worse. See
Format Hear transcripts for the measured
curated-evaluation result and its word-error-rate tradeoff.
Bind a hosted knowledge base
Scope:kb:manage to create the base and documents, omni:session to bind.
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 withPOST /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.v1, 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.