unmute

One voice agent spec. Compiled to the runtime you pick.

Unmute is a command line compiler for voice agents. You write a small package of
YAML and Markdown that says who the agent is, which models it uses, which tools
it can call, what it saves as the call goes on, and how the work is broken into
steps. Unmute turns that into a real Python project for the orchestrator you
picked, and refuses to compile the mistakes you would otherwise find on a live
call.

The project it writes is yours. Pinned dependencies, a Dockerfile, a runbook, and
no dependency on Unmute at runtime. Unmute compiles ahead of time and gets out of
the way. It is never in the call path.

[!TIP]
The Quickstart goes from nothing
to a voice you can talk to in your browser. The full guide lives at
unmute.ai.

Quickstart

brew install slng-ai/tap/unmute              # macOS
go install github.com/slng-ai/unmute@latest  # anywhere with Go 1.26+

unmute init my-agent      # agent.yaml, instructions.md, targets.yaml, tools/, .env.example
cd my-agent
cp .env.example .env      # then fill in OPENAI_API_KEY and SLNG_API_KEY
unmute validate
unmute dev                # compile, run the container, open the browser

Allow the microphone and say hello. The agent speaks first, because agent.yaml
says so.

Windows uses Scoop, Linux takes the archive from the
releases page, and every release
also carries a signed checksums.txt and one SBOM per archive.
Installation covers all four
ways, plus the one thing running an agent needs: Docker with Compose for the
LiveKit browser loop, or uv for Pipecat.

An agent is a file

This is a whole agent.

# agent.yaml
version: 1
name: my-agent
entry_agent: assistant

agents:
  assistant:
    instructions: instructions.md
    think: assistant_model
    speak: assistant_voice
    tools:
      - end_call

secrets:
  - OPENAI_API_KEY
  - SLNG_API_KEY

models:
  think:
    assistant_model:
      provider: openai
      model: gpt-5.6-terra
      params:
        # A reasoning model answering with function tools on chat completions
        # needs this exact value, or OpenAI returns 400 on every turn.
        reasoning_effort: "none"
  speak:
    assistant_voice:
      provider: slng
      model: "deepgram/aura:2"
      voice: "aura-2-thalia-en"
      params:
        # Speech goes through the SLNG gateway nearest your callers.
        world_part: eu-north
  listen:
    transcriber:
      provider: slng
      model: "deepgram/nova:3"
      params:
        world_part: eu-north
  turn:
    detector:
      provider: local
      model: silero

tools:
  - end_call

conversation:
  greeting:
    speaks_first: agent
    text: "Hi, how can I help?"

channels:
  web:
    kind: realtime_audio

capacity:
  peak_sessions: 10
  max_sessions: 20
  avg_session_duration: 5m

Three things to notice:

• The prompt is a Markdown file next to it, not a quoted string buried in YAML.
• Every model is named once and then referenced by name. Point assistant_model
  at a different model and every agent using it follows.
• Nothing here mentions Pipecat or LiveKit. That choice lives in its own file.

# targets.yaml
targets:
  pipecat:
    provider: pipecat
    version: "1.10.0"

  livekit:
    provider: livekit
    version: "1.8.1"
    sdk_language: python
    models:
      detector:
        provider: livekit
        model: turn-detector-mini

One agent, two targets, and unmute compile writes both projects. Where a
runtime cannot run a model as defined, it overrides that single entry by name,
the way LiveKit does with the turn detector above. The agent itself does not
change.

Three targets

pipecat, livekit and slng are the only values provider accepts. A code
target gives you something to host. The hosted target has nothing to host, and
no unmute dev.

What compile writes

One directory per target, under build/.

build/livekit/
├── agent.py             # the agent
├── tools/               # your local Python handlers, copied
├── dev_metrics.py       # per-turn timings, read by unmute dev
├── pyproject.toml       # pinned dependencies
├── Dockerfile
├── .dockerignore
├── compose.dev.yaml
├── .env.example         # exactly the variables you supply
├── README.md            # the runbook for this build
└── compile-report.json

Pipecat gets the same shape with bot.py as its entry point. Neither project
imports Unmute.

Treat build/ as output. Edit the package and compile again. Anything you change
inside build/ is overwritten on the next compile.

What else the file holds

The agent at the top of this page is the floor. Everything below is written in
the same agent.yaml, next to what you have already read, and every piece of it
is checked before a call happens rather than during one. The snippets are from
customer-intake and
salon-concierge.

Values with a type

A variable says what it holds. The model is told the format, and the value is
checked where it enters, not where it is used.

shapes:
  - name: CustomerRecord
    description: The record the intake desk opened for this caller.
    fields:
      - record_id: Id
      - opened_on: Date
      - enquiry: Literal["new_customer", "existing_customer", "complaint", "other"]

variables:
  contact:
    type: NameEmail
    description: >-
      Who the caller is and where their confirmation goes, the name and the
      email address held as two separate parts.

  caller_email:
    type: EmailStr
    default: ""
    description: The caller's email address on its own, with no name around it.

  callback_time:
    type: Time | None
    description: >-
      A good time of day to ring the caller back, on the 24 hour clock. Leave it
      out when the caller has not named one.

  notes:
    type: list[str]
    description: >-
      Anything the caller added that no other field holds, one short entry per
      thing they said.

Phone, Date, Time, Id and EmailStr are text with a checked shape.
NameEmail holds a name and an address as two separate parts, so a prompt can
use the name without reading the address out loud. You also have str, int,
float, bool, Literal[...], list[...], | None, and any shape you
declare yourself.

An address the model misheard is refused with the format, inside the same turn,
so the model fixes it rather than saving something wrong. The email check never
asks DNS: this runs while the caller is on the line, and a slow resolver would
hold them in silence.

A step takes one part of a result with a dotted path, and + appends instead of
replacing.

assign:
  - contact: result.contact
  - caller_email: result.contact.email
  - notes+: result.note

A step that ends on its own tool

One task out of an agent's tasks: list.

- name: manage_booking
  instructions: tasks/booking.md
  tools:
    - find_slots
    - save_booking
  finish:
    - tool: save_booking
      success:
        - status:
            - booked
            - moved
            - cancelled
  assign:
    - appointment: result.appointment
  context:
    history: messages

finish: names the tool calls that end the step, and the result value that
counts as success. The booking goes through and the step is over. No extra model
call to announce it, no second sentence, and none of those tools runs again in
that step, because a second booking that ran and was then refused is still a
second booking. The caller hears the owning agent reply once.

The success value has to be one the tool's own output declares in an enum:. A
field that cannot hold it is refused when you compile, with the file and the
line.

A group that skips work already done

task_groups:
  book:
    when: >-
      The caller wants to create, move or cancel a booking. Includes a change to
      an appointment just made.
    steps:
      - task: verify_customer
        skip_when_confirmed: customer_phone
      - manage_booking
    context_scope: shared
    then: return

Verification runs the first time and is skipped once the number is agreed.
skip_when_confirmed: has to name a value that this same step confirms, so the
two cannot drift apart. Entering the step again withdraws what it confirmed,
which is what a caller correcting their number needs.

Facts in the prompt before the caller speaks

prefetch:
  - name: today
    clock: now
    timezone: Europe/Madrid
    assign:
      - today_date: result.date

  - name: caller
    source: from_number
    assign:
      - caller_phone: result.value

Each entry runs before the greeting, on its own budget, and cannot raise. When
one skips, the variable keeps its default and the step that asks runs instead.
The zone sits on the entry, because a container's clock is UTC and would name
the wrong day for everybody who is not on it.

A value the model never retypes

# tools/create_customer_record.yaml
input:
  type: object
  properties:
    summary:
      type: string
      description: One sentence in the caller's own words saying what they rang about.
  required:
    - summary

inject:
  - phone: "{{caller_phone}}"
  - email: "{{caller_email}}"
  - name: "{{contact.name}}"

The model fills one argument. The other three come straight out of saved state
and are hidden from it, so a digit cannot change between the turn it was agreed
on and the turn it was written down.

A variable can also carry confirm: verify_contact. Until that step hears a
yes, the value renders in no prompt but that step's own, and any tool injecting
it refuses itself and names the step to run first.

Speech through the gateway nearest your callers

models:
  speak:
    voice:
      provider: slng
      model: "deepgram/aura:2"
      voice: "aura-2-thalia-en"
      params:
        world_part: eu-north
  listen:
    transcriber:
      provider: slng
      model: "deepgram/nova:3"
      params:
        world_part: eu-north

world_part picks one of 13 SLNG speech gateways, on each listen and speak
model separately. It becomes the host eu-north.api.slng.ai in the generated
project: slng_base_url= on LiveKit, base_url= on Pipecat.

The 13 are us-east, us-west, br, eu-west, eu-north, gb, za, il,
jp, sg, id, in and au. Leave world_part out and the existing default
URL stands. Reasoning through the SLNG Context Router reads the same key and the
same 13 values, so one word covers listening, thinking and speaking. Where the
worker itself runs is a separate choice, deployment_region in targets.yaml,
and it does not have to match: salon-concierge deploys to eu-central and
speaks through eu-north.

SLNG deployment uses these same 13 region names. The location of each service
is still chosen separately.

Turn taking you can hear

models:
  turn:
    detector:
      provider: local
      model: silero
      pace: patient

pace: is snappy, balanced or patient. It sets how long the agent waits
after the caller stops talking. A desk that asks people to spell an email
address out loud wants patient, because they pause between the characters.

What validate catches

unmute validate reads the package the way the compiler does, and names the
file, the line and often the column when something is wrong. It is offline and
needs no account. A few of the things it refuses:

• a finish: whose success value the tool's own output cannot hold
• a skip_when_confirmed: naming a value that step does not confirm
• a pre-fetch entry reading a value only a later entry assigns, naming both and
  which one to move
• a type: outside the grammar, with the column inside the expression
• a prompt placeholder naming a value the package does not declare, or a greeting
  naming one that is not settled before the first word
• a world_part that is not a gateway, listing the ones that are
• a feature the chosen target cannot run, naming what to write instead

Warnings are the other half. A credential a package uses but never declares in
secrets:, an agent holding every tool of its own step so the step's assign:
never runs, a turn field that reaches nothing: each one names the thing to
change, goes to standard error, and still exits 0.

What goes in a package

Each of these has a page in the guide.

Every key of every package file is listed under
configuration.

Commands

validate, compile, dev, deploy and pull take the package directory as
an optional argument. From inside the package you run them bare; from anywhere
else you pass the path, as in unmute dev my-agent.

validate and compile work offline. SLNG deployment resolves hosted tools
by name with unmute deploy: no hash, mirror or pull step is needed. Only
LiveKit and Pipecat need unmute pull to fetch the hosted tools they run
themselves. deploy, pull and resources use your SLNG account.

Warnings go to standard error and still exit 0. Errors exit 1.

Coding agents

unmute skill install writes the Unmute skill into your repository, so Claude
Code, Cursor, Codex and the rest know how to author a package. The skill ships
inside the binary, so nothing is downloaded, and the files travel with the repo
so a team shares one skill. The docs are also readable as
llms.txt and
llms-full.txt, or one page at a
time by adding .md to its URL. See
Coding agents.

Templates

Ready-made agents live in their own repository:
slng-ai/unmute-templates.

Each folder there is one finished agent you can run, copy and change. The
repository README lists every template, what it shows, and which API keys it
needs.

git clone https://github.com/slng-ai/unmute-templates
cd unmute-templates

unmute validate single-prompt              # check the files
unmute compile single-prompt               # write the projects
unmute dev single-prompt --target pipecat  # talk to it in your browser

Copy the folder you like, change the name: line in its agent.yaml, and it
is yours.

To add a template, open a pull request on
slng-ai/unmute-templates, not
here. A good one is one folder showing one idea, it validates and compiles, it
carries a README saying what to listen for and which keys it needs, it adds a
row to that repository's table, and it holds no secrets.
CONTRIBUTING.md is the long version.

Templates are agents to start from. Examples below are packages to read: one
per feature of the compiler, held to every gate in this repository.

Examples

examples/ holds four packages.

• customer-intake is the small one: one agent,
  three tasks, one local tool. It takes a caller's number, name, email address,
  enquiry and callback time, saves each under its own type, and hands them to a
  tool the model cannot type over. Every type in the grammar appears once. Start
  here if the question is about types, saved values or injection.
• salon-concierge is the big one: two agents, four
  tasks, a task group that skips verification once the number is agreed, three
  steps that end on their own tool with finish:, handoffs in both directions, a
  cold manager transfer, tracing, and inbound phone on both code targets. Every
  tool is local Python, so nothing remote has to be up before the greeting.
• salon-concierge-single-prompt is
  the same salon with the structural features taken back out, so the one above
  can be read against something. Model, transport and turn taking are held
  identical, so a difference you hear is a difference the structure made.
• hotel-concierge is the hosted target's
  showcase: a concierge line whose tools are all references SLNG already holds,
  with template variables, an injected argument, a tool announcement, named MCP
  tools and a fallback. It produces no runnable project:
  unmute deploy compiles a deployment body and pushes it.

If you want a package to start from rather than one to read, run
unmute init my-agent.

Develop

make install  # builds and puts unmute on your PATH
make test     # go test -race ./... , pure Go, no Python needed
make lint
make fmt

make smoke proves the emitted Python is valid and needs Python installed, so it
is opt-in and never the pull request gate. make contracts re-fetches the
published SLNG conformance fixtures and needs network.

Contributing

Contributions are welcome, from anyone. Unmute is MIT licensed and every part of
it is open: the compiler, the three targets, the examples, the skill and the
docs site.

A pull request needs five things:

1. An issue, opened before you write the code. Search the
   open issues first, then open a
   bug report, an improvement or a feature request. Link it from the pull
   request.
2. An example package that uses your feature. Shaped like the ones in
   examples/, with your new key in its authored files and the
   code path running on a real call, so we can compile it, dial it and hear it.
3. A video of that example working.
4. A README for that example, saying which part of it is your feature.
5. Updated docs under docs-site/ that explain how the
   feature works, not only what the key is called.

CONTRIBUTING.md is the whole thing: what the example has to
exercise, where the package goes, what a public example has to pass, and every
check CI runs with its local command.

Say hello on Discord before you start something
large. It is the fastest way to find out whether somebody is already on it.

Resources

• Documentation covers everything above in order.
• Templates are ready-made
  agents to clone, run and copy.
• How Unmute works is the
  four compiler stages between your package and the generated project.
• Configuration reference is
  every key of every package file.
• Changelog says what changed in each
  release.
• docs/ARCHITECTURE.md explains the design and points
  at the load-bearing code.
• Issues for bugs and requests.
• Discord for questions, and for showing what
  you built.
• Contributing for how to send a change.

Unmute is MIT licensed. See LICENSE.