Parlant: a Python harness that keeps customer-facing LLM agents on policy, and what it ties you to

Parlant is built for customers who are confused, impatient or hostile

Parlant draws a hard line between an AI assistant and a customer-facing agent, and its design follows from that line. An assistant serves a cooperative, informed user who corrects it as it goes, and a mistake costs a retry. A customer-facing agent talks to someone who may be confused, impatient or hostile, with nobody watching the conversation, and a mistake can mean financial losses, brand damage and lost customer relationships. Such an agent often has to stick to specific operating procedures and stay on policy at all times, sometimes with exact wording, and its behavior has to be explainable.

Parlant calls itself an interaction control harness for controlled, consistent and predictable LLM interactions. The engine's job is to keep the agent on your rules in every conversation, including when a customer changes the subject, mixes topics, or turns out to be on a different plan than they think. Around that engine, Parlant supplies the pieces such an agent needs: a chat widget, human handoff, testing, hosting and analytics.

You describe behavior and a coding agent writes the policy

The intended workflow is that you do not write most of the agent by hand. You describe how the agent should behave, and your local coding agent implements it as Parlant policies. Parlant's own example: you tell the coding agent to answer questions about a new Pro plan from a FAQ, to mention Pro once when a Basic customer hits their project limit, and never to pitch it to Pro customers. The coding agent adds a policy and uses each customer's plan variable to decide when Pro is relevant. You then ask it to test with two simulated personas, open both test sessions on the Dashboard, check the outcome and push.

To orient a coding agent, Parlant publishes llms.txt at parlant.io, and the repository root carries an llms.txt and an AGENTS.md as well. The quickstart at parlant.io/docs/quickstart/installation hands you a prompt that has the coding agent install Parlant and set up an example or your own agent step by step. This means the quality of the result depends partly on the coding agent you bring.

Local development still needs a Dashboard project token

If you prefer to write the code yourself, the setup is three lines. Parlant's default model provider is OpenRouter, so you set its key, and you also set a token for a project on the hosted Dashboard:

pip install parlant
export OPENROUTER_API_KEY="<YOUR_API_KEY>"
export PARLANT_DASHBOARD_PROJECT_TOKEN="<YOUR_PROJECT_TOKEN>"

The token comes from a Local development project you create at dashboard.parlant.io. After you start your script, you click Check connection and Open project in the Dashboard, then start a New session from the Overview page to talk to the agent. The consequence is that even a laptop-only prototype depends on a Parlant account and the hosted Dashboard being reachable. Teams with policies against sending session data to a third-party service should look at what the Dashboard receives before starting. Going live follows the same path: the deployment guide points to the Dashboard's managed hosting, and the chat widget puts the agent on your site.

Tools are plain async functions that return a ToolResult

Business logic enters a Parlant agent through tools. A tool is an async Python function decorated with p.tool, with a docstring the model sees, typed arguments, and a p.ToolResult as its return value. Parlant's starter example looks up an order:

@p.tool
async def check_order_status(order_id: str) -> p.ToolResult:
    """Look up an order's current status."""
    status = ORDERS.get(order_id)
    if status is None:
        return p.ToolResult(data=f"There's no order {order_id}. Ask the customer to check the number.")
    return p.ToolResult(data=f"Order {order_id} is {status}.")

The missing-order branch is the interesting part. Instead of raising an error, the tool returns text telling the agent what to do next, and in the Dashboard session the agent then asks the customer to check the number. Run the file with python main.py. Because the agent runs on your own code, a tool can call any system you can reach, and you can use any model you choose.

Scaffolds and providers set the starting point

For more than a single file, the parlant command line creates a project from a scaffold:

parlant init my-agent --scaffold retail-store

retail-store gives a working support agent. The other scaffolds are lead-gen, a website agent that qualifies visitors and books meetings, and basic, an empty project. The repository also ships examples/healthcare.py and examples/travel_voice_agent.py.

On models, OpenRouter is the default, and the base install keeps the OpenAI SDK as a dependency because it drives both the OpenAI and OpenRouter adapters, so OpenRouter never needs an extra. Parlant also supports Anthropic, Gemini, LiteLLM and custom providers, configured as described in docs/providers.md. Whichever you choose, you pay that provider directly, rather than a per-resolution fee charged by a closed customer-experience vendor.

The develop branch says 4.0.1 while the newest release tag is v3.3.2

Parlant's default branch is develop, not main, and the version numbers do not line up. pyproject.toml on develop declares version 4.0.1 and describes Parlant as a vibe-coding platform for chat agents that talk to customers. The newest GitHub releases are v3.3.2 from 28 April 2026, v3.3.1 from 14 April and v3.3.0 from 15 March. The repository itself is active, with the last push on 2 November 2026.

The practical consequence is that the GitHub releases page does not tell you what pip install parlant gives you today, and examples or docs written against the develop branch may assume behavior from a major version that the release tags do not show. Before you build on it, check the installed version, read CHANGELOG.md for that version, and pin it in your own requirements.

A large dependency set with deliberate pins

Parlant requires Python 3.10 or newer and below 3.15, so 3.15 environments are excluded by the package metadata. The base install pulls in a long list: FastAPI, fastmcp and mcp, the OpenAI SDK plus httpx and httpx2, boto3, numpy, networkx, nano-vectordb, aiosqlite, four OpenTelemetry packages, and maxminddb for local GeoIP lookups of session client locations with no network call.

Some versions are pinned on purpose, and the comments say why. aiopenapi3 is held below 0.9.0 because 0.9.0 hard-pins pydantic==2.11.9, which conflicts with consumers that need pydantic 2.12 or newer. openapi3-parser is pinned to exactly 1.1.21. httpx2 is a direct dependency because openai 3.0 moved its client onto HTTPX2, so timeouts passed to it must be httpx2 objects. If you add Parlant to an existing service rather than a fresh virtual environment, expect to resolve these pins against what you already run.

Editorial conclusion

Parlant fits a Python team building a support, sales or lead-generation chat agent that must follow fixed policies and sometimes exact wording, and that wants to pay model providers directly rather than a per-resolution fee. It is a poor fit for general assistant-style agents, or for teams that cannot create an account on the Parlant Dashboard for local development. Before adopting it, confirm your Python version is between 3.10 and 3.14, check which version pip installs against CHANGELOG.md, and test that its dependency pins coexist with your existing environment.

Frequently asked questions

Official sources

1. emcie-co/parlant on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases