livekit cloud agent not getting dispatched to room
# ask-ai
r
livekit cloud agent not getting dispatched to room
t
Thanks for reaching out, Saurabh. I'm an AI assistant and I'm here to help. Give me a moment while I research this topic.
Thanks — I’m sorry you’re seeing the cloud agent not get dispatched to the room. I can help troubleshoot this, but I need a few details to narrow down the cause. Please answer the questions below and paste any short logs or config snippets you can. What I’m asking about (quick): are you using an explicit agent name or automatic dispatch, which dispatch method you’re using, whether the agent process is healthy/registered, and any relevant errors or timing details. Please provide: 1. Agent name & dispatch configuration ◦ Did you set an
agent_name
in your agent’s
@server.rtc_session
decorator? If yes, automatic dispatch is disabled and you must use explicit dispatch. ◦ If you set
agent_name
, how are you dispatching the agent (CLI/API/token)? 1. Dispatch method you’re using (pick one) ◦
lk dispatch create
CLI command ◦
CreateAgentDispatchRequest
API call ◦ Participant token with
RoomConfiguration.agents
◦ Inbound SIP call with dispatch rules ◦ Other (describe) ◦ Share the exact command or the minimal code snippet you use to dispatch (redact secrets). 1. Agent server status ◦ Are your agent processes running and showing healthy in the dashboard or via
lk agent status
? ◦ If possible, paste the output of
lk agent status
or a short excerpt of agent startup logs. 1. Logs or error messages ◦ Any lines from
lk agent logs
or your agent console showing connection, dispatch, or room errors (especially anything mentioning timeouts or "not established within 10 seconds"). ◦ If you see an error, paste the exact text. 1. Room creation / timing ◦ Is the room being created before the dispatch call or after? ◦ Are you creating the participant that triggers dispatch at the same time as the room creation or later? 1. JWT / permissions & config ◦ Are you using a JWT / token for dispatch or for the participant? Does that token include required agent permissions? (You can redact the token itself; tell me which claims are present.) ◦ Any custom RoomConfiguration or SIP trunk/rule settings relevant to dispatch? Common checks you can run right now • Confirm
agent_name
usage: if you set
agent_name
then use explicit dispatch (CLI or API). Automatic dispatch is disabled when
agent_name
is set. • Verify agent process is healthy and registered (
lk agent status
). • Check logs for connection timeouts — a typical symptom is the agent failing to establish the room connection within the timeout window. • If using SIP, ensure dispatch rules / trunk are correct and that outbound call creation and dispatch both succeed. What I can do next after you reply • Walk through targeted troubleshooting steps for your dispatch method (CLI, API, token, or SIP). • Review any logs you paste and point to exact failure causes. • Provide example CLI/API calls or token configuration to correct the dispatch flow. If you share the dispatch method and a couple of the log lines or the
lk agent status
output, I’ll give step-by-step fixes. Sources: Agents Framework | livekit/livekit_composite | DeepWiki | Agents telephony integration | LiveKit Documentation | Agent dispatch | LiveKit Documentation | Outbound Calling Script | LiveKit Documentation
r
when I run locally, I am able to dispatch the agent but cloud agent is not getting dispatched
t
Thanks — that’s a helpful datapoint: dispatch works locally but the cloud agent isn't being dispatched. I can help dig into the difference between your local and cloud environments and get this resolved. To pinpoint the cause, please share the following details (short answers or pasted snippets are fine). What I’m responding to: your note that local dispatch succeeds but the LiveKit cloud agent is not being dispatched. Please provide: 1. Dispatch method in use for cloud ◦ Are you dispatching via the CLI (
lk dispatch create
), the API (
CreateAgentDispatchRequest
), a participant token (
RoomConfiguration.agents
), or via SIP dispatch rules? Which one do you use for the cloud attempt? 1. Agent configuration differences ◦ Do you set an
agent_name
in your agent’s
@server.rtc_session
decorator for the cloud agent? (If yes, automatic dispatch is disabled and explicit dispatch must be used.) ◦ Is the cloud agent built from the same code and config as the local agent, or are there differences (env vars, build flags, versions)? 1. Agent health & registration ◦ Does the cloud agent show as running/healthy in the LiveKit Cloud dashboard or when you run
lk agent status
against the cloud account? Paste the
lk agent status
output or a short excerpt if possible. 1. Logs and errors ◦ Share the relevant lines from the cloud agent logs (
lk agent logs
or your cloud provider logs) around the dispatch attempt. Look for errors like connection timeouts or authentication failures. ◦ If you see any error text, paste it exactly. 1. Room & timing ◦ Is the room created before you dispatch the agent in the cloud attempt? Are you creating the participant that triggers dispatch at the same time as room creation? ◦ Does local dispatch use a room that already exists or one created on-the-fly? 1. Networking & connectivity ◦ Is the cloud agent able to reach LiveKit control plane endpoints (no outbound firewall restrictions)? Local working suggests code is fine but cloud networking could block connections. ◦ Are there differences in NAT, VPC, or egress settings between your local environment and the cloud agent deployment? 1. Tokens and permissions ◦ Are you using the same JWT/credentials locally and in cloud? Does the cloud dispatch token include agent dispatch permissions / the same claims as your local token? (You can redact token values; just confirm which claims are included.) Quick checklist you can run now • Confirm cloud agent process is registered/healthy (
lk agent status
). • Compare environment variables between local and cloud (especially
agent_name
, API keys, region, or dispatch-related flags). • Inspect cloud agent logs for connection/auth/timeouts during dispatch. • If using explicit dispatch, ensure you run the same CLI/API call against the cloud account/region (not your local cluster). When you reply with: • Which dispatch method you use, plus • A short excerpt of
lk agent status
and the relevant cloud agent log lines I’ll provide targeted steps (exact commands or config changes) to resolve the cloud dispatch failure. If you prefer, paste the minimal CLI/API command you run locally and the one you run for the cloud so I can compare.
r
Copy code
Using agent [CA_iMUpzhJiyYbZ]
┌─────────────────┬─────────────────┬─────────┬─────────┬──────────┬────────────┬───────────┬──────────────────────┐
│ ID              │ Version         │ Region  │ Status  │ CPU      │ Mem        │ Replicas  │ Deployed At          │
├─────────────────┼─────────────────┼─────────┼─────────┼──────────┼────────────┼───────────┼──────────────────────┤
│ CA_iMUpzhJiyYbZ │ v20260219140938 │ us-east │ Running │ 145m / 2 │ 0.52 / 4GB │ 1 / 1 / 1 │ 2026-02-19T14:09:44Z │
└─────────────────┴─────────────────┴─────────┴─────────┴──────────┴────────────┴───────────┴──────────────────────┘
t
Thanks — that status output is helpful: the cloud agent CA_iMUpzhJiyYbZ is running in us-east with 1 replica. I’ll help narrow down why it isn’t being dispatched even though local dispatch works. Quick confirmation question • Which dispatch method are you using when targeting the cloud agent? (CLI
lk dispatch create
, API
CreateAgentDispatchRequest
, participant token
RoomConfiguration.agents
, or SIP dispatch rules?) Given the agent is running, please provide the following next items so I can pinpoint the cause and give exact steps: 1. Cloud agent logs around the dispatch attempt ◦ Paste the few log lines from
lk agent logs
(or your cloud provider logs) captured at the time you try to dispatch. Look for connection failures, timeouts, auth errors, or messages about room connection not established. 1. The exact dispatch command or API call you run against the cloud ◦ Show the minimal CLI command or API request (redact secrets). If you run the same command locally and it succeeds, paste both local and cloud commands so I can compare. 1. Whether you set an
agent_name
in the agent code ◦ Did you set an
agent_name
in your agent’s
@server.rtc_session
decorator for the cloud build? If yes, automatic dispatch is disabled and you must use explicit dispatch with that name. 1. Room & participant timing ◦ Do you create the room first, then dispatch, or do you dispatch expecting the agent to attach when a participant is created? Tell me the sequence you use locally vs cloud. 1. Token/permissions differences ◦ Are you using the same JWT/credentials for dispatch in cloud as locally? Confirm whether the token used for dispatch includes agent dispatch permissions (you can list claims, redact values). Quick troubleshooting steps you can run now • Check cloud agent logs for any “connection” or “timeout” errors when dispatching. • Verify you’re running the dispatch command against the same LiveKit project/region the cloud agent is registered to. • If you set
agent_name
, ensure you use explicit dispatch with that name (CLI/API/token) — automatic dispatch will not pick it up. • Confirm there are no networking restrictions in your cloud environment that could prevent the agent from reaching LiveKit control plane endpoints. What I’ll do once you reply • If you paste the dispatch command and log excerpt, I’ll identify the exact error and give the precise fix (commands or config change). • If logs show an auth or timeout issue, I’ll provide steps to regenerate tokens or adjust timeouts/replica settings. If you prefer, paste: • The dispatch command you run for cloud and local, and • 10–20 lines of cloud agent logs at the same timestamp. I’ll analyze those and give step‑by‑step remediation.
r
lk dispatch create
t
Thanks — good to know you’re using
lk dispatch create
. I can help, but I need the exact command you run against the cloud agent and a couple of log snippets to pinpoint the difference between local and cloud behavior. Please provide the following (redact any secrets): 1. The exact
lk dispatch create
command you run for the cloud (include flags:
--project
,
--region
,
--agent
,
--token
, etc.). If you run a slightly different command locally, paste that one too so I can compare. 2. Cloud agent logs from the time you attempt dispatch: ◦ Run
lk agent logs CA_iMUpzhJiyYbZ
(or your cloud provider logs) and paste ~10–20 lines around the dispatch attempt. ◦ Look for lines mentioning connection, authentication, timeouts, or "room connection not established". 1. Quick confirmations ◦ Did you set an
agent_name
in your agent code/build for the cloud agent? (Yes/No) ◦ Is the dispatch command targeting the same LiveKit project/region shown in
lk agent status
(us-east)? (Yes/No) ◦ Are you creating the room before calling
lk dispatch create
, or do you dispatch expecting attachment when a participant connects? What I’ll do once you share those: • Compare the working local command with the cloud command and point out any flag/region/project mismatches. • Inspect logs and tell you the exact error (auth, timeout, network, or config) and the precise fix (command change, token/claims change, restart, or network check). If you prefer, paste the cloud
lk dispatch create
command and the 10–20 log lines and I’ll analyze them and give step‑by‑step fixes.
r
agent secrets are missing for stt and tts keys . how can I set it during deployment ?
t
Thanks — that helps. You can provide STT and TTS keys (agent secrets) to your cloud agent at deploy time so the agent can access external speech APIs. Below are the supported ways to inject secrets and the exact commands you can use. What I’m responding to: how to set missing STT/TTS keys for your cloud agent during deployment. Recommended options • Use a secrets file (recommended for local / simple deployments) a. Create a file (example
.env.local
) with key=value lines:
Copy code
DEEPGRAM_API_KEY=your_deepgram_key
     OPENAI_API_KEY=your_openai_key
     CARTESIA_API_KEY=your_cartesia_key
1. Deploy the agent with:
Copy code
lk agent create --secrets-file .env.local --agent CA_iMUpzhJiyYbZ --region us-east
This uploads those secrets and injects them as environment variables into the agent container. • Pass secrets inline (good for CI/CD or one-off commands)
Copy code
lk agent create --secrets DEEPGRAM_API_KEY=abc123,OPENAI_API_KEY=xyz789 --agent CA_iMUpzhJiyYbZ --region us-east
Multiple secrets are comma-separated. Inline secrets take precedence over a secrets file. • Mount a secret file (for file-based credentials) If a provider requires a JSON credentials file, use:
Copy code
lk agent create --secret-mount path/to/creds.json --agent CA_iMUpzhJiyYbZ --region us-east
That file will be mounted into the agent container at runtime. Update secrets for an already-deployed agent • To update or add secrets without changing code:
Copy code
lk agent update-secrets --secrets DEEPGRAM_API_KEY=new_key --agent CA_iMUpzhJiyYbZ --region us-east --overwrite
This restarts the agent with the new secrets. Important notes and quick checks • Use the exact environment variable names your STT/TTS plugin expects (for example,
DEEPGRAM_API_KEY
,
OPENAI_API_KEY
, etc.). Confirm the agent code/plugin reads those variables. • Do not include
LIVEKIT_API_KEY
,
LIVEKIT_API_SECRET
, or
LIVEKIT_URL
in your secrets — those are auto-injected. • Never commit secret files to version control. Add
.env.local
(or whichever file you use) to
.gitignore
. • Ensure you deploy the secrets to the same region/project the agent is running in (your
lk agent status
shows the agent in
us-east
). If you want, paste: • The STT/TTS env var names your agent expects (e.g.,
DEEPGRAM_API_KEY
), and • The exact
lk agent create
command you plan to run (you can redact keys), and I’ll confirm the correct flags and a one-line command you can run safely. Sources: server-sdk-go | livekit/livekit_composite | DeepWiki | Examples | livekit/livekit_composite | DeepWiki | Agents Framework | livekit/livekit_composite | DeepWiki | Google AI and LiveKit | LiveKit Documentation | Deploy LiveKit Agents with GitHub Actions | LiveKit
r
should I not set it in env variableds ?
t
Good question — short answer: provide STT/TTS keys as agent secrets at deploy time (they will become environment variables inside the agent). Don’t rely on local env vars on your machine to be available to the cloud agent. Why and how: • The cloud agent runs in LiveKit’s/cloud provider’s environment, so local env variables are not automatically passed to that runtime. • Use the LiveKit secret mechanisms so the keys are securely injected into the agent container as environment variables the agent code can read. Recommended options (pick one): • Secrets file (recommended) Create a
.env
or `.env.local`:
Copy code
DEEPGRAM_API_KEY=your_deepgram_key
  OPENAI_API_KEY=your_openai_key
Deploy:
Copy code
lk agent create --secrets-file .env.local --agent CA_iMUpzhJiyYbZ --region us-east
• Inline secrets (CI/CD friendly)
Copy code
lk agent create --secrets DEEPGRAM_API_KEY=abc123,OPENAI_API_KEY=xyz789 --agent CA_iMUpzhJiyYbZ --region us-east
• Secret mount (for file-based credentials)
Copy code
lk agent create --secret-mount path/to/creds.json --agent CA_iMUpzhJiyYbZ --region us-east
Updating existing agent: • Update without redeploying code:
Copy code
lk agent update-secrets --secrets DEEPGRAM_API_KEY=new_key --agent CA_iMUpzhJiyYbZ --region us-east --overwrite
Best practices: • Use the exact env var names your plugin expects (e.g.,
DEEPGRAM_API_KEY
). • Do not commit secret files to source control; add them to
.gitignore
. •
LIVEKIT_API_KEY
,
LIVEKIT_API_SECRET
, and
LIVEKIT_URL
are auto-injected — do not overwrite them. • Verify the agent reads the env vars (a quick log line or a small print in startup can confirm). If you want, tell me which provider keys your agent expects (the env var names), and paste the
lk agent create
command you plan to run (redact values). I’ll confirm the exact command you should use.
r
how to select the agent in CI, without interactive
t
Good question — you can select the agent non‑interactively in CI by passing the agent identifier (and other required flags) directly to the
lk
commands or by using environment variables. Here are simple, CI‑friendly options and examples. What I’m responding to: how to select the cloud agent in CI without interactive prompts. 1) Use explicit flags with the
lk
CLI • Always pass
--agent
,
--project
, and
--region
(if needed) in the command so no interactive selection is required. Example:
Copy code
lk dispatch create --agent CA_iMUpzhJiyYbZ --project my-project --region us-east --room my-room
Or when creating/updating an agent:
Copy code
lk agent create --agent CA_iMUpzhJiyYbZ --region us-east --secrets-file .env.local
2) Provide secrets non‑interactively • Use
--secrets-file
,
--secrets
, or
--secret-mount
flags to avoid prompts:
Copy code
lk agent create --agent CA_iMUpzhJiyYbZ --secrets-file .env.local
# or
lk agent create --agent CA_iMUpzhJiyYbZ --secrets DEEPGRAM_API_KEY=$DEEPGRAM_API_KEY,OPENAI_API_KEY=$OPENAI_API_KEY
3) Set defaults using environment variables (CI pipeline) • Export env vars before invoking
lk
so scripts remain concise:
Copy code
export LK_AGENT=CA_iMUpzhJiyYbZ
export LK_PROJECT=my-project
export LK_REGION=us-east

lk dispatch create --agent $LK_AGENT --project $LK_PROJECT --region $LK_REGION --room my-room
(Use your CI secret store to populate these variables securely.) 4) Use non‑interactive flags for authentication • Ensure the CI environment has the LiveKit API credentials available (set via env vars or injected files) so the CLI won't prompt for auth. 5) Example GitHub Actions step
Copy code
- name: Dispatch LiveKit agent
  run: |
    lk dispatch create --agent $LK_AGENT --project $LK_PROJECT --region $LK_REGION --room $ROOM_NAME
  env:
    LK_AGENT: ${{ secrets.LK_AGENT }}
    LK_PROJECT: ${{ secrets.LK_PROJECT }}
    LK_REGION: us-east
    DEEPGRAM_API_KEY: ${{ secrets.DEEPGRAM_API_KEY }}
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
Quick checklist for CI: • Use the agent ID with
--agent
in your script. • Supply secrets via
--secrets-file
or
--secrets
(CI secret store recommended). • Make sure the CLI has credentials in the CI environment so it won’t prompt. • Target the same project/region the agent is registered in (your
lk agent status
showed
us-east
). If you share which CI system you’re using (GitHub Actions, GitLab CI, CircleCI, etc.), I can provide a ready-to-use snippet tailored to that platform.
r
does this work? working-directory: src/agents/${{ inputs.agent }}. can id be picked by toml file ?
t
Thanks — that’s a good approach and yes, you can pick the agent ID dynamically in CI. I’ll explain two common patterns, then ask one quick question so I can give a precise example for your pipeline. What I’m responding to: whether
working-directory: src/agents/${{ inputs.agent }}
will work and whether the agent ID can be picked from a TOML file. Quick question • Which CI system are you using (GitHub Actions, GitLab CI, CircleCI, etc.)? I’ll give an exact snippet for that platform. Two recommended patterns 1) CI input/env var → use as working-directory and as agent ID (simplest) • Have the CI job accept an input or secret that contains the agent key (e.g., CA_iMUpzhJiyYbZ). • Use that same variable both for
working-directory
and the
--agent
flag when running
lk
commands. • Example (GitHub Actions style): ◦ set job input or environment var:
AGENT=CA_iMUpzhJiyYbZ
◦ working directory:
Copy code
working-directory: src/agents/${{ inputs.agent }}
• command:
Copy code
lk dispatch create --agent ${{ inputs.agent }} --region us-east --room my-room
• This keeps behavior deterministic and avoids parsing files in CI. 2) Read agent ID from a TOML file in the repo (if you must store per-agent config) • Store agent metadata in a TOML file in each agent folder, e.g. `src/agents/my-agent/agent.toml`:
Copy code
[agent]
  id = "CA_iMUpzhJiyYbZ"
  region = "us-east"
• In CI, set working-directory to the agent folder first, then parse the TOML to extract
id
into an env var and use it with
lk
. • Lightweight parsing options: ◦ Use a small script (Python, Node, or `sed`/`awk`) to read
agent.toml
. ◦ Example using Python (CI step):
Copy code
AGENT_ID=$(python -c "import toml,sys; print(toml.load('agent.toml')['agent']['id'])")
    lk dispatch create --agent "$AGENT_ID" --region us-east --room my-room
• Or with a simple grep/sed if TOML is simple:
Copy code
AGENT_ID=$(grep '^id' agent.toml | head -n1 | sed -E 's/.*\"(.*)\".*/\1/')
• Use
working-directory: src/agents/${{ inputs.agent }}
so the file path is consistent. Best practices • Prefer passing the agent ID via CI inputs/secrets when possible — easier and avoids runtime parsing complexity. • If using TOML configs in repo, validate the parsed value is non-empty before calling
lk
to avoid accidental interactive prompts. • Keep secrets (like API keys) in the CI secret store and use
--secrets-file
or
--secrets
non-interactively. • Ensure
lk
is authenticated in CI (set necessary LiveKit creds as env vars) so no interactive auth is required. If you tell me which CI system you use, and whether you prefer to store the agent ID as a job input or inside a TOML file, I’ll give a ready-to-drop-in snippet for your pipeline (including parsing command and safety checks).
r
GitHub Actions,
t
Great — here are two straight-forward GitHub Actions patterns you can use to select the agent non‑interactively. Both support using `working-directory: src/agents/${{ inputs.agent }}`; pick the one that matches how you want to manage agent IDs. What I’m responding to: using GitHub Actions and whether you can pick the agent ID from a TOML file (yes — and examples below). Option A — Pass agent ID as an input/secret (simplest, recommended) • Put the agent ID in an action input or a repository secret and use it for both
working-directory
and the
lk
command. No parsing required. Example (GitHub Actions reusable/workflow with input):
Copy code
on:
  workflow_dispatch:
    inputs:
      agent:
        description: 'Agent folder / ID'
        required: true

jobs:
  dispatch:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: src/agents/${{ inputs.agent }}
    steps:
      - uses: actions/checkout@v4

      - name: Install lk CLI
        run: |
          curl -sL <https://example.com/install-lk.sh> | bash

      - name: Dispatch agent
        env:
          LK_AGENT: ${{ inputs.agent }}            # set agent id or folder
          LK_PROJECT: ${{ secrets.LK_PROJECT }}
          LK_REGION: us-east
          DEEPGRAM_API_KEY: ${{ secrets.DEEPGRAM_API_KEY }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          lk dispatch create --agent "$LK_AGENT" --project "$LK_PROJECT" --region "$LK_REGION" --room my-room --non-interactive
Notes: • Put sensitive values in GitHub Secrets. • Use
--non-interactive
(or equivalent) if your
lk
CLI supports it to avoid prompts. • This is the simplest, most reliable approach. Option B — Read agent ID from a TOML file in the agent folder • Use this if each agent folder contains an
agent.toml
with the ID. The job sets working-directory to the relevant folder, then extracts the ID and uses it in the
lk
command. Example (reads agent.toml):
Copy code
on:
  workflow_dispatch:
    inputs:
      agent_folder:
        description: 'Agent folder name'
        required: true

jobs:
  dispatch:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: src/agents/${{ inputs.agent_folder }}
    steps:
      - uses: actions/checkout@v4

      - name: Parse agent ID from TOML
        id: parse
        run: |
          python - <<'PY'
          import toml, sys
          data = toml.load('agent.toml')
          agent_id = data.get('agent', {}).get('id') or data.get('id')
          if not agent_id:
            print('::error::agent id not found in agent.toml')
            sys.exit(1)
          print(f"agent_id={agent_id}")
          # GitHub Actions output format
          print(f"::set-output name=agent_id::{agent_id}")
          PY

      - name: Install lk CLI
        run: |
          curl -sL <https://example.com/install-lk.sh> | bash

      - name: Dispatch agent
        env:
          LK_AGENT: ${{ steps.parse.outputs.agent_id }}
          LK_PROJECT: ${{ secrets.LK_PROJECT }}
          LK_REGION: us-east
          DEEPGRAM_API_KEY: ${{ secrets.DEEPGRAM_API_KEY }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          if [ -z "$LK_AGENT" ]; then echo "No agent id found"; exit 1; fi
          lk dispatch create --agent "$LK_AGENT" --project "$LK_PROJECT" --region "$LK_REGION" --room my-room --non-interactive
Notes: • I use a small Python snippet with the
toml
module. If your runner doesn’t have
toml
, either install it (
pip install toml
) or use a grep/sed approach for simple TOML. • Validate the parsed
agent_id
to prevent accidental interactive prompts. Additional best practices • Keep secrets (STT/TTS keys) in GitHub Secrets and supply them via
env
or a secrets file. Use
lk agent create --secrets-file
or
--secrets
in a prior deploy step to ensure the cloud agent has them. • Ensure
lk
CLI is authenticated in CI (set LiveKit creds in env vars or configure a service account) so commands run non‑interactively. • Use explicit flags: always pass
--agent
,
--project
, and
--region
in CI to avoid selection prompts. • Add a sanity check step that echoes the agent ID (masked) or fails fast if empty. If you want, I can: • Provide a trimmed GitHub Actions workflow tailored to your repo layout, or • Swap the Python parser for a shell
grep/sed
snippet if you prefer no Python dependency. Which would you prefer?