> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pyai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build and run Agents

> Build and manage the same voice agent through the console or API, then run it on the Omni realtime runtime.

**Agents** is the product for building, testing and running voice agents.
**Omni** is its realtime runtime. Use the visual builder, the API, or both to
manage the same saved agent. The builder remains **Live Beta**; features,
limits and production behavior may change during beta.

<CardGroup cols={2}>
  <Card title="Build in the console" href="https://console.pyai.com/agents?signup=1&path=agent&utm_source=docs.pyai.com&utm_medium=docs">
    Describe the job, choose a voice, add knowledge and test your agent.
  </Card>

  <Card title="Build with the API" href="/guides/create-agents-api">
    Create a saved profile with POST /v1/agents, then connect to /v1/omni.
  </Card>
</CardGroup>

<Note>
  Sandbox keys never bill. Live calls require available credit, and managed
  telephony is metered separately. See the
  [pricing page](https://pyai.com/pricing) for current runtime and managed
  Agents terms.
</Note>

## Console workflow

<Steps>
  <Step title="Open the Agent builder">
    Go to [Launch an Agent](https://console.pyai.com/agents?signup=1\&path=agent\&utm_source=docs.pyai.com\&utm_medium=docs).
    Sign up or sign in. The path is preserved through authentication.
  </Step>

  <Step title="Business and job">
    Start with the business name, then choose a starting role such as receptionist,
    support, scheduling or lead qualification. Edit the suggested job description
    to match your business. Use Custom role for your own workflow.
  </Step>

  <Step title="Knowledge and voice">
    Upload files, add website links, paste reference notes or attach existing
    organization knowledge bases directly in the creator. This step is optional.
    Existing KBs show source processing and failure counts. New files and links
    are staged until creation; remove them here to exclude them. Local files
    need to be reattached if you close the creator.

    Choose voice, speaking perspective and suggested capabilities. Capabilities
    still need configured tools before they can execute real business actions.
  </Step>

  <Step title="Review the editable brief">
    Edit the greeting and six instruction sections: identity and purpose,
    conversation flow, knowledge rules, actions and handoff, speaking style and
    boundaries. Voice delivery guidance is sent separately from business rules.
    Knowledge documents remain reference material and are not copied into the prompt.

    The starting templates are versioned. Use **Preview refreshed template** to
    inspect a replacement before applying it; **Keep my edits** preserves your
    current brief. Creation saves the reviewed instructions without a background
    rewrite. Click **Create & test** when ready.
  </Step>

  <Step title="Test before going live">
    Check any setup warnings first. Knowledge may still be processing after
    creation; wait for indexing before testing answers that rely on it.
    Run the browser greeting test. Confirm that the opening line, voice, and
    first response match your instructions. Confirm consent behavior when
    recording is enabled. Browser tests have no phone leg and cannot prove
    transfer, DTMF, hold, collect, or hangup behavior.
  </Step>

  <Step title="Put it on your website">
    Open **Website & phone**. The wizard drafts a Call Now snippet and
    publishes it when you added a public site URL (localhost is always
    included so you can preview). Add any remaining origins, publish if
    needed, and paste the script tag. Guide:
    [Add your Agent to a website](/guides/website-voice-widget).
  </Step>

  <Step title="Connect a phone number">
    Assign an available managed number or connect a supported carrier route.
    Availability and regulatory onboarding vary by country. Agents usage and
    managed telephony are metered separately when PyAI carries the phone leg;
    see the [pricing page](https://pyai.com/pricing) for current terms.
  </Step>
</Steps>

<Warning>
  Managed call-control execution is not available yet. An Agent can decide to
  emit `transfer_to_human`, `send_dtmf`, `play_hold`, `collect`, or `end_call`,
  but those carrier actions work today only when your own Twilio, FreeSWITCH, or
  SIP transport handles the corresponding Omni control frame. Do not enable a
  call-control tool on a managed number until the console marks managed execution
  available for that tool.
</Warning>

## Move between the console and API

The [Agents workspace](https://console.pyai.com/agents) has **Your agents**,
**Realtime playground** and **Build with API**. A saved agent's **API integration**
tab provides read, update and realtime connection examples for that agent.
You can share the editor URL, including its selected tab, with a teammate who
has access to the same organization and project.

Use a key from your console project when creating an agent through the API.
The profile then appears under **Your agents** in that project. Edits through
either interface update the same profile; new sessions load the latest saved
configuration. Inline `configure` fields can override saved settings for one call.

For direct application connections, use
`wss://api.pyai.com/v1/omni?format=pcm16&rate=24000&session_label=<agent_id>`.
Saved profiles remain optional: omit `session_label` and send inline configuration
when you want to manage each session entirely in code. Existing Omni clients
keep their current endpoint, scope and wire protocol.

## Need implementation help?

[Talk to AtomsAI](https://atomsai.com/contact?utm_source=pyai_docs\&utm_medium=product_referral\&utm_campaign=agent_implementation\&utm_content=getting_started),
our AI services business, for white-glove setup, bespoke integrations and ongoing
agent improvement. Services are optional, scoped and quoted separately from PyAI usage.

## Next steps

<CardGroup cols={2}>
  <Card title="Website widget" href="/guides/website-voice-widget">Publish a Call Now button with one script tag.</Card>
  <Card title="Create agents via API" href="/guides/create-agents-api">The same profile, from code.</Card>
  <Card title="Knowledge bases" href="/guides/knowledge-bases">Hosted files, URLs, and pasted text.</Card>
  <Card title="Omni tools" href="/guides/omni-tools">Hosted, server, or client tools.</Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.