# Unmute

> A declarative standard for voice agents. Describe the agent once, compile it to SLNG, LiveKit, Pipecat, or Twilio.

> ## Agent Instructions
> Unmute compiles to exactly four targets. Pipecat and LiveKit are code targets: compile writes a Python project you run. SLNG is a hosted target: compile writes a deployment body and SLNG runs the agent, so it has no `unmute dev`. Twilio compiles to a small Python app that Twilio ConversationRelay calls; you host it, and it has no `unmute dev` either. Those four are the only values `provider` accepts in `targets.yaml`. Deepgram and ElevenLabs appear in these docs as model vendors, which is not the same thing as a target, and `slng` is both.
> The Go structs in `internal/spec` and `internal/ir` are the schema truth. Check a field against them, or run `unmute validate`, rather than against what you remember.

- [Unmute](https://unmute.ai/index.md): A declarative standard for voice agents. Describe the agent once, compile it to SLNG, LiveKit, Pipecat, or Twilio.
- [Installation](https://unmute.ai/start/installation.md): Install Unmute on macOS, Windows, or Linux and check the one Quickstart prerequisite.
- [Quickstart](https://unmute.ai/start/quickstart.md): Scaffold an agent, add two keys, and talk to it in your browser.
- [Coding agents](https://unmute.ai/start/coding-agents.md): Optional setup for supported coding assistants, followed by one checked voice-agent build.
- [How Unmute works](https://unmute.ai/start/how-unmute-works.md): The four stages between your package and what each target runs.
- [Your first agent](https://unmute.ai/build/your-first-agent.md): The smallest real agent: a prompt, four models, and one file that says who is answering.
- [How a package fits together](https://unmute.ai/build/how-a-package-fits-together.md): One rule explains the whole file: an agent owns what it can do, and writes each one where it uses it.
- [Variables](https://unmute.ai/build/variables.md): Declare a value once in state.py, fill it during the call, and read it only where it is needed.
- [Credentials](https://unmute.ai/build/credentials.md): Give the agent an API key without putting one in your package.
- [Pre-fetch](https://unmute.ai/build/prefetch.md): Run a lookup before the call starts, when you already have everything it needs.
- [Tools](https://unmute.ai/build/tools/overview.md): What a tool is, the eight ways one can run, how each target treats them, and how you attach one to an agent.
- [Webhook tools](https://unmute.ai/build/tools/webhook.md): Call your own API: a URL from the environment, a path that renders per call, and values the model never sees.
- [Python tools](https://unmute.ai/build/tools/python.md): A handler of your own in the package: what it receives, what it returns, and where it is copied.
- [MCP servers](https://unmute.ai/build/tools/mcp.md): Point the agent at a remote MCP server and let it offer that server's tools.
- [Prebuilt tools](https://unmute.ai/build/tools/prebuilt.md): The capabilities the platform already has: a closed registry of four, and the settings you can pin on each.
- [Hosted tools](https://unmute.ai/build/tools/hosted.md): Reference a tool your SLNG organisation already has by its exact name: no hash, no mirror, no pull required for SLNG.
- [Knowledge bases](https://unmute.ai/build/tools/knowledge.md): Point a tool at a folder of your own documents, and the agent answers from them instead of guessing.
- [Orchestration](https://unmute.ai/build/orchestration/overview.md): Three ways to split one agent into parts, and where each is taught.
- [Your first task](https://unmute.ai/build/orchestration/first-task.md): Add one task to the agent you already have, one key at a time, until it knows for itself when its work is done.
- [Tasks](https://unmute.ai/build/orchestration/tasks.md): Run one step of a call with its own prompt and tools, save typed values, and return control.
- [Flows](https://unmute.ai/build/orchestration/task-groups.md): Run several tasks in a fixed order.
- [Handoffs](https://unmute.ai/build/orchestration/handoffs.md): Move the caller to an agent with different instructions and tools.
- [Choosing a structure](https://unmute.ai/build/orchestration/choosing-a-structure.md): Tools, tasks, flows, or a second agent. Which split to reach for, and when.
- [Architecture](https://unmute.ai/build/architecture/overview.md): Choose a pipeline, switch an existing agent, and check that its models and bindings agree.
- [Cascade](https://unmute.ai/build/architecture/cascade.md): Build an agent with separate listening, reasoning, and speaking models, then extend it with tasks and state.
- [Realtime](https://unmute.ai/build/architecture/realtime.md): Run one model for spoken conversation, then choose turn detection, tools, and an optional separate voice.
- [Live](https://unmute.ai/build/architecture/live.md): Run an OpenAI live voice agent and give it a reasoning backend for tools and knowledge.
- [Designing declared state](https://unmute.ai/best-practices/state-design.md): Choose facts that help the next task, keep requested changes separate from saved outcomes, and avoid repeated questions.
- [Reduce context sharing step by step](https://unmute.ai/best-practices/context-scope.md): Start with conversation continuity, then let each task read only the facts it needs.
- [Making a task actually run](https://unmute.ai/best-practices/step-scoping.md): A task the model can skip is a task that never writes a saved value. What to give a task so it gets entered, and what to take away from its owner.
- [Writing prompts for a voice](https://unmute.ai/best-practices/prompt-writing.md): A text to speech voice reads what you write, exactly as you write it. The rules that follow from that, and the one that a model will read out loud if you break it.
- [Checking what the agent did](https://unmute.ai/best-practices/verifying-behaviour.md): A transcript tells you what the caller heard. It does not tell you what the agent recorded, and the two disagree more often than you would expect.
- [The dev loop](https://unmute.ai/dev/overview.md): What unmute dev actually does, how to pick a target, and where the logs are.
- [Tracing](https://unmute.ai/tracing/overview.md): See what happened inside a call: what the caller said, what the model decided, and which tools ran.
- [Coval](https://unmute.ai/tracing/coval.md): Send spans to Coval so each trace is attached to the simulation that produced the call.
- [Langfuse](https://unmute.ai/tracing/langfuse.md): Send spans to Langfuse to watch live calls and debug one conversation at a time.
- [Logfire](https://unmute.ai/tracing/logfire.md): Send spans to Pydantic Logfire to watch live calls and query them with SQL.
- [Optimizing your agent](https://unmute.ai/optimization/overview.md): Settings that speed up a call, why each one matters, and how to write them in agent.yaml.
- [Context Router](https://unmute.ai/optimization/context-router.md): The optimization layer for thinking: repeated turns come back from a cache instead of calling your model.
- [SLNG Execution Layer](https://unmute.ai/optimization/execution-layer.md): A scaffolded package binds SLNG speech models by design, and those models run on SLNG's Execution Layer.
- [Reading the latency numbers](https://unmute.ai/optimization/latency.md): Where the time goes in a voice turn, and what each number under a turn means.
- [What to fetch before the call](https://unmute.ai/optimization/prefetch.md): How to decide which lookups belong before the greeting, and the traps in moving them there.
- [Setting how long the agent waits](https://unmute.ai/optimization/turn-taking.md): pace and endpointing_delay: the two settings that decide how long a caller waits before the agent answers.
- [Regional infrastructure](https://unmute.ai/optimization/regional-infrastructure.md): Keep STT, LLM, and TTS services close to your users, with separate settings for model gateways, workers, and media.
- [Going live](https://unmute.ai/deploy/going-live.md): Create a package, choose a host, and deploy it with the right configuration and credentials.
- [Deploy to SLNG](https://unmute.ai/deploy/slng.md): Deploy a package to SLNG, update the existing agent, and manage its credentials.
- [Go live on LiveKit Cloud](https://unmute.ai/deploy/livekit-cloud.md): Create a LiveKit Cloud agent from your package, then update its code and runtime secrets.
- [Go live on Pipecat Cloud](https://unmute.ai/deploy/pipecat-cloud.md): Compile your package, choose an organization, deploy it, and update its code or secrets.
- [Phone calls](https://unmute.ai/telephony/overview.md): How a phone call reaches your agent, which routes exist, and what the transport decides.
- [Outbound calls](https://unmute.ai/telephony/outbound-calls.md): Make the agent dial out, and give it the values it needs before the phone rings.
- [Inbound calls](https://unmute.ai/telephony/inbound-calls.md): Take a real call from your own phone number, once your agent is deployed.
- [Get your Twilio details](https://unmute.ai/telephony/twilio.md): Which value in the Twilio console fills which name in your connection file, per route, and what each route needs set up before it works.
- [LiveKit over Twilio](https://unmute.ai/telephony/livekit-twilio.md): A caller dials your Twilio number and your agent picks up. This is the four steps that make that happen, in the order you do them.
- [Pipecat over Twilio](https://unmute.ai/telephony/pipecat-twilio.md): A caller dials your Twilio number and your agent picks up. This is the three steps that make that happen, in the order you do them.
- [Take a call with Twilio ConversationRelay](https://unmute.ai/telephony/twilio-conversation-relay.md): Create an agent, host its FastAPI app, and connect a Twilio number for your first call.
- [Human transfers](https://unmute.ai/transfers/overview.md): Handing the caller to a person: cold, warm, and why the route decides which you get.
- [Transfers on LiveKit](https://unmute.ai/transfers/livekit.md): The only route with both cold and warm transfer, over a Twilio SIP trunk.
- [Transfers on Pipecat over Twilio](https://unmute.ai/transfers/pipecat-twilio.md): Cold transfer through your own Twilio number, with no server of yours in the call path.
- [Targets](https://unmute.ai/targets/overview.md): What a target is, what targets.yaml holds, and how one package compiles to two runtimes.
- [The SLNG deployment body](https://unmute.ai/targets/slng.md): What unmute compile writes for a slng target, what SLNG runs for you, and what the package may not ask for.
- [The LiveKit project](https://unmute.ai/targets/livekit.md): What unmute compile writes for a LiveKit target, and how to run it without Unmute.
- [The Pipecat project](https://unmute.ai/targets/pipecat.md): What unmute compile writes for a Pipecat target, and how to run it without Unmute.
- [The Twilio target](https://unmute.ai/targets/twilio.md): Configuration, hosting requirements, and advanced options for your ConversationRelay application.
- [Speech to text](https://unmute.ai/models/stt.md): The listen binding: every key it takes, the vendors each target can construct, and how one SLNG key reaches many models.
- [Text to speech](https://unmute.ai/models/tts.md): The speak binding: every key it takes, the vendors each target can construct, and how one SLNG key reaches many voices.
- [Reasoning model](https://unmute.ai/models/llm.md): The think binding: every key it takes, the vendors each target can construct, and what happens when yours is not listed.
- [Live model](https://unmute.ai/models/live.md): Configure the OpenAI live model, its voice, and the backend that runs tools.
- [Turn detection](https://unmute.ai/models/turn-detection.md): The turn binding: every key it takes, and how each target decides the caller has finished speaking.
- [Agent configuration](https://unmute.ai/reference/agent-yaml.md): Every block of the agent file, and the tool files beside it.
- [Migrate an older package](https://unmute.ai/reference/migrate.md): Rewrite an agent.yaml written for unmute 0.8 or older to the current, typed contract.
- [Manifest](https://unmute.ai/reference/manifest.md): Keep agents and coding assistants within your company's approved choices.
- [Targets configuration](https://unmute.ai/reference/targets-yaml.md): Every field of a target, plus the connection files it points at.
- [Connection configuration](https://unmute.ai/reference/connections-yaml.md): One file, one phone route: the transport, the carrier, and the environment names that route needs.
- [Variables reference](https://unmute.ai/reference/variables.md): state.py, sources, where a variable can be used, and how it reaches a tool.
- [Secrets](https://unmute.ai/reference/secrets.md): Names only, never values: how a credential reaches the agent and its tools.
- [CLI reference](https://unmute.ai/reference/cli/overview.md): The command tree, exit codes, warnings, version, and shell completion.
- [unmute init](https://unmute.ai/reference/cli/init.md): Create an agent package: the starter scaffold, or guided setup under a saved contract.
- [unmute manifest](https://unmute.ai/reference/cli/manifest.md): Save company rules once, then use them to build an agent.
- [unmute validate](https://unmute.ai/reference/cli/validate.md): Check a package against its targets before you compile or run it.
- [unmute pull](https://unmute.ai/reference/cli/pull.md): Optional, and only for a livekit or pipecat build: fetch a hosted tool's definition into your package so that compile can trust it offline. SLNG needs none of this.
- [unmute compile](https://unmute.ai/reference/cli/compile.md): Write the compiled project for each target, and read the report written next to it.
- [unmute deploy](https://unmute.ai/reference/cli/deploy.md): Validate, compile and push a package to SLNG in one command, or point a Twilio number at a twilio target you host.
- [unmute dev](https://unmute.ai/reference/cli/dev.md): Every flag, with defaults, and what the command does not do.
- [unmute resources](https://unmute.ai/reference/cli/resources.md): See the tools, MCP servers and phone numbers your SLNG organisation offers.
- [unmute skill](https://unmute.ai/reference/cli/skill.md): Give your coding assistant the workflow to build and check an Unmute agent.
- [Community](https://unmute.ai/community/overview.md): Where to ask a question, where to file an issue, and how to contribute to Unmute.
- [Contributing](https://unmute.ai/community/contributing.md): What a pull request to Unmute needs: the issue, an example that uses your feature, a video, a README and updated docs.
- [Changelog](https://unmute.ai/changelog.md): What changed in each release of the Unmute CLI, newest first.
- [Unmute Core](https://unmute.ai/core/index.md): The Python library that runs a voice agent's behaviour the same way on LiveKit and Pipecat.
- [Why Unmute Core](https://unmute.ai/core/start/why-unmute-core.md): What the library adds to a LiveKit or Pipecat agent, and when you need it.
- [Install Unmute Core](https://unmute.ai/core/start/installation.md): Add unmute-core and a framework extra to a project from PyPI.
- [Unmute Core quickstart](https://unmute.ai/core/start/quickstart.md): Run the smallest unmute-core agent on LiveKit or Pipecat: a salon receptionist that keeps the caller's phone number.
- [Build a salon agent](https://unmute.ai/core/tutorial/overview.md): Build one phone agent for a hair salon, one piece at a time, on LiveKit or Pipecat.
- [Answer the phone](https://unmute.ai/core/tutorial/answer-the-phone.md): Build the smallest salon agent: a prompt, a greeting and a call you can talk to.
- [Remember the caller](https://unmute.ai/core/tutorial/remember-the-caller.md): Give the salon agent a typed call state, so it keeps the caller's number and refuses one that cannot be right.
- [Check the diary](https://unmute.ai/core/tutorial/check-the-diary.md): Give the salon agent a typed tool that reads the diary, and say a line while it runs.
- [Book step by step](https://unmute.ai/core/tutorial/book-step-by-step.md): Turn booking into a task and a group, so the agent verifies the caller and asks before it writes to the diary.
- [Hand off complaints](https://unmute.ai/core/tutorial/hand-off-complaints.md): Add a complaint specialist agent, and a handoff tool that moves the caller to it and back.
- [Know the time before hello](https://unmute.ai/core/tutorial/know-the-time.md): Read today's date on the salon's clock and the caller's number before the greeting, with Prefetch.
- [Quiet callers and long calls](https://unmute.ai/core/tutorial/quiet-callers.md): Set the turn pace, nudge a caller who goes quiet, end a long call, and let the agent hang up when the caller says goodbye.
- [See every call](https://unmute.ai/core/tutorial/see-every-call.md): Send one trace for each salon call to Langfuse, with the same shape on LiveKit and Pipecat.
- [What you built](https://unmute.ai/core/tutorial/what-you-built.md): Map your salon agent to the full example in the repository, run it on LiveKit and Pipecat, and find the guide for each piece.
- [Add one piece to your agent](https://unmute.ai/core/frameworks/standalone.md): Use one part of unmute-core on a plain LiveKit Agent or a plain Pipecat pipeline.
- [LiveKit](https://unmute.ai/core/frameworks/livekit.md): UnmuteAgent runs tools, tasks, the model call and telemetry on a LiveKit AgentSession.
- [Pipecat](https://unmute.ai/core/frameworks/pipecat.md): UnmuteFlows runs tools, tasks, the model call and telemetry in a Pipecat pipeline.
- [State](https://unmute.ai/core/build/state.md): Typed call values, confirmation, prompt placeholders and the save_values tool, on any Pydantic model.
- [Tools in code](https://unmute.ai/core/build/tools.md): Give the model tools to call: Python functions, webhooks and built-ins that work the same on LiveKit and Pipecat.
- [Knowledge](https://unmute.ai/core/build/knowledge.md): Search a folder of documents from a tool, so the agent answers from your own text.
- [Tasks in code](https://unmute.ai/core/build/tasks.md): Define tasks and task groups that save values step by step, with the same rules on LiveKit and Pipecat.
- [Your first task in code](https://unmute.ai/core/build/tasks/first-task.md): Define one task, check it with TaskPlan and run it on LiveKit and Pipecat.
- [Task groups in code](https://unmute.ai/core/build/tasks/groups.md): Run several tasks in order as one flow, and decide what happens when the flow finishes.
- [How a task step ends](https://unmute.ai/core/build/tasks/how-a-step-ends.md): The finish check, the held finish, going back to an earlier step and the retry after an empty reply.
- [Held saves](https://unmute.ai/core/build/tasks/held-saves.md): What happens when a step tries to save before the caller spoke in it, and how the call end settles the save.
- [Reply and confirm in code](https://unmute.ai/core/build/tasks/confirm-in-code.md): Say fixed lines for a tool result, ask the caller before a closing tool runs, and open a step with a tool.
- [What the model reads in a task](https://unmute.ai/core/build/tasks/what-the-model-reads.md): What a step hears of the call, the small results a task sends to the model, and the limits on placeholder names.
- [The call's life](https://unmute.ai/core/build/call-lifecycle.md): What happens around a call: start values, the greeting, checks, tools on events, a failure and the end.
- [Prefetch](https://unmute.ai/core/build/prefetch.md): Fill the call state before the greeting: the clock, the call's numbers, and lookups.
- [Turn taking](https://unmute.ai/core/build/turn-taking.md): Set how fast the agent takes its turn, what speech over a line does, and what happens when the caller goes quiet.
- [Handoffs in code](https://unmute.ai/core/build/handoffs.md): Give the call to another main agent, with a line said first and a choice of what the next agent hears.
- [Hooks](https://unmute.ai/core/build/hooks.md): Run your code before, around and after each prompt, model request and tool call, and on call events.
- [Example agents](https://unmute.ai/core/examples/overview.md): Four working voice agents on unmute-core, each a different shape of call, each on LiveKit and Pipecat.
- [Type the agent's path](https://unmute.ai/core/examples/typed-path.md): Let the model understand the caller, and let typed tools and code decide, save and speak. Fewer tokens, the same call every time.
- [Nosh, a tools-only finder](https://unmute.ai/core/examples/nosh.md): One agent and three typed tools find a restaurant near the caller. Code speaks every result, so each caller turn costs one model request.
- [Kestrel, a claim intake line](https://unmute.ai/core/examples/kestrel.md): A task group finds the caller's policy, then code asks every question of a car accident report and reads the whole claim back before filing it.
- [Wasla, an outbound payment reminder](https://unmute.ai/core/examples/wasla.md): An outbound call that verifies the person first, says nothing about the account before, and records one outcome only on the holder's yes.
- [Faro, a bilingual language tutor](https://unmute.ai/core/examples/faro.md): Two agents, one per explanation language, share one set of typed tools. The model grades each answer, and code teaches, records progress and says the next exercise.
- [The model call](https://unmute.ai/core/models/model-call.md): ModelCall, the one interface every model request goes through, and the classes that implement it.
- [SLNG speech and the Context Router](https://unmute.ai/core/models/slng.md): Use SLNG speech-to-text, text-to-speech and the Context Router with a native LiveKit or Pipecat agent.
- [Realtime and live models](https://unmute.ai/core/models/realtime.md): Run an agent on a model that hears the caller, thinks and speaks over one connection.
- [Phone calls in code](https://unmute.ai/core/telephony.md): Take calls in, place calls out, and transfer a caller to a person, the same way on LiveKit and Pipecat.
- [Telemetry](https://unmute.ai/core/observe/telemetry.md): Send every call's spans to Langfuse, Logfire, Coval or Datadog. Turn it on once, then pick where the spans go.
- [AgentSpec reference](https://unmute.ai/core/reference/agent-spec.md): Every field of AgentSpec, the one description of an agent that runs the same on LiveKit and Pipecat.
- [LiveKit adapter reference](https://unmute.ai/core/reference/livekit.md): Every argument of UnmuteAgent, the model classes and the call helpers on LiveKit, and the rules they follow.
- [Model call reference](https://unmute.ai/core/reference/model-call.md): ModelCall, ModelRequest, the events, placeholders, NativeModelCall, OpenAIModelCall and every FallbackModelCall argument.
- [SLNG reference](https://unmute.ai/core/reference/slng.md): Every RouterModelCall argument, the headers and body fields each request carries, the router config, Gemini thought signatures, and the router's errors.
- [Call lifecycle reference](https://unmute.ai/core/reference/call-lifecycle.md): Every argument of CallHooks, Greeting, EventTool and save_call_start, the order of a call, and each rule for the greeting, failures and the end.
- [Handoffs reference](https://unmute.ai/core/reference/handoffs.md): Every argument of HandoffContext and the two hand_off calls, the history rules, the helpers, and how each framework runs a handoff.
- [Hooks reference](https://unmute.ai/core/reference/hooks.md): Every hook point, event and argument, the rules each point follows, and where a hook does not reach.
- [Pipecat adapter reference](https://unmute.ai/core/reference/pipecat.md): Every argument of UnmuteFlows, the model service, the call helpers, observers, tools and voices on Pipecat, and the rules they follow.
- [Prefetch reference](https://unmute.ai/core/reference/prefetch.md): Every argument of Prefetch, Clock, CallValue, Lookup and call_info, the checks at build time, and how a run spends its budget.
- [Settings](https://unmute.ai/core/reference/settings.md): Every environment variable the library reads, and how to check them all at startup.
- [State reference](https://unmute.ai/core/reference/state.md): Every CallState argument, save and confirmation rule, prompt reading, value type and error, and State from type text.
- [Turn taking reference](https://unmute.ai/core/reference/turn-taking.md): Every turn pace window, interruption rule, idle nudge and call limit argument, and how each framework applies them.
- [Telemetry reference](https://unmute.ai/core/reference/telemetry.md): Every Telemetry helper, sink argument, span and attribute, and how each vendor's names are added.
- [Dev records](https://unmute.ai/core/reference/dev-records.md): Record what one call did, for the local dev page that unmute dev shows.
- [Phone calls reference](https://unmute.ai/core/reference/telephony.md): Every argument of Transfer, the phone lines, dialling and voicemail, and how a transfer runs on each route.
- [Tools reference](https://unmute.ai/core/reference/tools.md): Every tool option, rule and edge case: inputs and outputs, announce lines, saved results, locked arguments, webhooks, built-ins and your own kind of tool.
- [Tasks reference](https://unmute.ai/core/reference/tasks.md): Every argument of the task spec classes, TaskPlan, CallTasks and StepRun.


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