Connect a Pipecat Cloud agent

Set up with your coding agent

Open Agents → Connect an agent.
Choose Run simulations, Monitor production or Set up both, then Pipecat.
Copy the prompt, open your bot’s repository in a coding agent, and paste it.

The coding agent installs the Egma skills and the CLI, signs you in, and asks where your bot runs: on this machine, on Pipecat Cloud, or on your own servers. It then adds the SDK line, the keys and the connections, runs your first test suite, and sends you the run link. It asks you before it changes a secret set or deploys. To do the same by hand, follow the steps below. For a bot on your own servers, see Use a self-hosted starter. To test before you deploy, see Test a bot on this machine.

1. Prepare the bot

Install the SDK in your bot’s project:

uv add "egma[pipecat]"

With pip, run pip install "egma[pipecat]". The SDK needs Python 3.11 or newer and pipecat-ai 1.9, 1.10, or 1.11. Add await simulation(worker, runner_args) after you create the PipelineWorker and before runner.add_workers(worker). If your pipeline is built in a helper such as run_bot, pass runner_args from bot() into it:

from egma.pipecat import simulation
from pipecat.runner.types import RunnerArguments


async def run_bot(transport: BaseTransport, runner_args: RunnerArguments):
    ...
    worker = PipelineWorker(
        pipeline,
        params=PipelineParams(enable_metrics=True, enable_usage_metrics=True),
    )

    await simulation(worker, runner_args)

    runner = WorkerRunner(handle_sigint=False)
    await runner.add_workers(worker)
    await runner.run()


async def bot(runner_args: RunnerArguments):
    ...  # build the transport as before
    await run_bot(transport, runner_args)

This line is required for every Pipecat simulation, including tests without mock tools. When the start request carries no egma key, it does nothing and makes no network request.

Pipecat Python SDK

What the line does, how mock tools and Pipecat Flows behave, and when it raises NotReported.

Create a project API key from your initialized agent repository:

egma project api-key create --name "Pipecat bot"

Copy the key when the CLI prints it; it is shown only once. Give each place your bot runs its own key: this one is for Pipecat Cloud. If the bot will also send production conversations, add EGMA_AGENT_NAME too. Your bot needs these two settings:

Variable	Value
`EGMA_URL`	`https://app.egma.ai`, or the public URL of your self-hosted Egma instance.
`EGMA_API_KEY`	The project API key you just created.

Add them to the secret set named by secret_set in your pcc-deploy.toml:

pipecat cloud secrets set my-bot-secrets \
  EGMA_URL=https://app.egma.ai \
  EGMA_API_KEY="$EGMA_API_KEY"

Then redeploy the bot, for example with pipecat cloud deploy. The bot reads the new secrets and code only after the redeploy. A cold start adds a few seconds, and Egma waits up to 120 seconds for your bot. If your bot starts more slowly than that, keep one instance warm with min_agents = 1 under [scaling] in pcc-deploy.toml. Pipecat Cloud charges for a reserved instance.

2. Register the agent in Egma

Check egma/config.yaml. Reuse the existing Egma agent if it is already registered. Otherwise, run:

egma agent register --platform pipecat --name "Front desk"

Set EGMA_AGENT_ID to the Egma agent ID printed by the command.

3. Add voice and chat connections

Egma needs your Pipecat Cloud agent name, which is agent_name in pcc-deploy.toml, and a public API key of the Pipecat Cloud organization that deploys it. A public key starts with pk_. Create one in the Pipecat Cloud dashboard or with pipecat cloud organizations keys create. Egma never needs a private key (sk_). Load the public key from your secret store, then add a voice connection:

export EGMA_PIPECAT_PUBLIC_KEY="$PIPECAT_PUBLIC_KEY"

egma agent connection add \
  --agent "$EGMA_AGENT_ID" \
  --access pipecat-cloud \
  --modality voice \
  --pipecat-agent-name "$PIPECAT_AGENT_NAME" \
  --name "Pipecat voice"

Run the command again with --modality chat --name "Pipecat chat" to add a chat connection. Chat needs no extra code; see Chat connections and Env. For a key supplied by another process, add --credentials-stdin and send {"publicApiKey":"pk_..."} through standard input. Do not put the key in command-line arguments. Keep the connection ID as EGMA_CONNECTION_ID, then follow the test guide to write a test and start a run.

What happens in a simulation

Egma sends this start request to Pipecat Cloud:

POST https://api.pipecat.daily.co/v1/public/front-desk/start
Authorization: Bearer pk_...
Content-Type: application/json

{
  "createDailyRoom": true,
  "dailyRoomProperties": { "exp": 1790000000, "eject_at_room_exp": true },
  "body": {
    "tenant": "oak-street",
    "egma": { "simulation_id": "sim_01K5TB2H8Y4P7QCWF9XKMD6RZP", "modality": "voice" }
  }
}

body holds the test’s pipecat_body_params and Egma’s own egma key, which names the simulation and its modality (voice or chat). Your bot reads body at runner_args.body; the SDK reads the egma key.
The room expires two minutes after the simulation’s duration limit. Pipecat Cloud then removes a bot that is still in the room.
The persona joins the room as an RTVI client and sends client-ready. A bot that greets in on_client_ready, as Pipecat’s quickstart does, speaks first.
Egma waits up to 120 seconds for your bot to join, report to Egma, and publish audio (voice) or send RTVI bot-ready (chat). A warm bot starts at once.
When the conversation ends, the persona leaves the room. Stop your bot when its client disconnects, as the quickstart does in on_client_disconnected.

If Pipecat Cloud answers HTTP 429 because the agent has no free capacity, Egma tries again within the 120 seconds. See Troubleshooting for every failure message.

Get started

Core Philosophies

Platform

Integrations

Support

Connect a Pipecat Cloud agent

Set up with your coding agent

1. Prepare the bot

Pipecat Python SDK

2. Register the agent in Egma

3. Add voice and chat connections

What happens in a simulation

​Set up with your coding agent

​1. Prepare the bot

Pipecat Python SDK

​2. Register the agent in Egma

​3. Add voice and chat connections

​What happens in a simulation

Set up with your coding agent

1. Prepare the bot

2. Register the agent in Egma

3. Add voice and chat connections

What happens in a simulation