Install & run

Getting started

Get Free Community support

Join our Discord channel for support in getting your first agent up and running.

Get help on Discord

This page takes you from nothing to a working agent you can talk to. You install Parlant, create a project, either from a ready-made example or for your own agent, connect it to the Dashboard, and test a conversation. Your coding agent can do all of it with the prompt below; the steps are here so you can follow along or do them yourself.

What you'll learn

• How to install Parlant and create your first agent project
• How to test a conversation in the Dashboard
• How to change the agent's behavior and see the change reload
• What to check if something isn't working

Agent-ready quickstart

Let your coding agent do the whole setup with you. Copy the prompt and paste it into your coding agent.

Each step below starts with what happens in it. Your coding agent runs the commands and tells you when it needs you; the commands themselves are under Doing this yourself? if you're following along without it.

Requirements

• A coding agent, such as Claude Code, Codex, Cursor, or OpenHands, to run the setup with you.
• A model provider API key. Parlant uses OpenRouter by default, configured with an effective combination of models.
• Python 3.10–3.14 on your computer. Your coding agent can help you install it.
• Recommended: uv, a fast Python package manager. Again, your coding agent can help.

Installation

Your coding agent installs Parlant on your computer.

Doing this yourself?

pip install parlant

Project setup

Your coding agent asks what your agent should do, and suggests the scaffold that fits. There are three:

1. retail-store, a working support agent for a homeware store, with sample orders and shipments. It's also the best way to see how Parlant works, and the rest of this page follows it.
2. lead-gen, a website agent that answers visitors' questions, qualifies them, and books meetings with your sales team, with a sample CRM and calendar. The Lead generation playbook explains how it works.
3. basic, an empty project for any other agent.

Doing this yourself?

We recommend getting started with the retail-store scaffold for a working example you can run and explore. Copy and run this command in your terminal:

parlant init my-agent --scaffold retail-store
# Choose your preferred package manager when prompted.

For a lead-generation agent, use --scaffold lead-gen. To start any other agent, use the basic scaffold, an empty project structure:

parlant init my-agent --scaffold basic

And enter the newly created project directory:

cd my-agent

Feel free to look around, starting with main.py, which is the entry point for your agent server. config.py configures the server and its model provider; domains/ contains the example's policies, tools, and business services. The generated run.sh (or run.cmd on Windows) installs the project dependencies and starts the server using the package manager you chose.

Copy .env.example to a new file named .env in this directory. On macOS or Linux:

cp .env.example .env

The generated project loads this file when it starts. In development, the retail-store example uses sample orders and shipments, so you don't need a store backend to try it. These are demonstration services, not a connection to your business systems.

Configuring Your LLM Provider

Your coding agent asks which model provider you want to use. The default is OpenRouter, which reaches models from many providers with a single key. You add your provider's API key to the project's .env file, and your coding agent shows you where.

Doing this yourself?

The default provider for Parlant is OpenRouter, which comes preconfigured for a cost/performance balance.

To get started, fill in your API key in .env:

OPENROUTER_API_KEY=your-api-key

You can also set the key in the terminal where you run the server:

export OPENROUTER_API_KEY="<YOUR_API_KEY>"

Using a different provider?

Parlant supports a number of other providers out of the box, including Anthropic, OpenAI, Google, and LiteLLM. You can also combine providers and models in your agents. Model routing covers routing each kind of work to a different model.

The easiest way to get started with a different provider is to set the models parameter on your server to route all tasks to that provider, according to its preconfigured defaults. This is done by setting the "*" route key to the provider name.

You can find this in config.py's create_server() function:

return p.Server(
  ...,
  models={"*": "gemini"}
)

If you leave models out, the server defaults to {"*": "openrouter"}.

Supported providers:

Provider	Extra Package	Environment Variable
OpenAI	Built-in	OPENAI_API_KEY
OpenRouter	Built-in	OPENROUTER_API_KEY
Google Gemini	parlant[gemini]	GEMINI_API_KEY
Anthropic	parlant[anthropic]	ANTHROPIC_API_KEY
LiteLLM (100+ providers)	parlant[litellm]	The keys of the underlying providers you use

For providers that need an extra package, add the extra to the generated project's dependency declaration, keeping its existing version constraint. For Gemini, change parlant to parlant[gemini] in requirements.txt (pip), pyproject.toml (uv or Poetry), or the pip dependencies in environment.yml (Conda).

Then add the provider's key to .env:

GEMINI_API_KEY=your-api-key

The startup script installs the declared dependencies into the project's own environment. Installing the extra only alongside the CLI is not enough when your project uses a separate environment. For uv, you can also install the updated dependencies before starting with uv sync.

OpenRouter and LiteLLM are gateways to many models from many providers, so you can use them to reach practically any model. The main reason to use a dedicated provider is if you have credits on your account with them.

Connect to the Dashboard

Your local project is the code folder on your computer. A Dashboard project is the place where you test its agent and inspect its conversations and activity. A project token connects the two.

1. Open the Dashboard. Sign in, or create an account if you don't already have one, then choose your workspace.
2. Open the project selector, choose Create project, and select Local development.
3. Give the project a name, then continue to Connect your server.

Choose Local development for an agent that runs on your computer. The name identifies its Dashboard project, not the agent in your code.

4. Copy the project token and add it to your local .env:

PARLANT_DASHBOARD_PROJECT_TOKEN=your-project-token

Keep your local server running. A Local development project runs on your computer and connects to the Dashboard.

Use Copy token to put this project's token in your local .env. Keep it private; it is deliberately hidden in this screenshot.

Run your agent

Your coding agent starts your agent's server. Leave it running while you test.

Doing this yourself?

From the generated project directory, start the server:

macOS / Linux

./run.sh

Windows

run.cmd

Wait for the server to finish starting, and leave this terminal open. The example listens on port 8800 and runs its tool service on 8818; make sure those ports aren't already in use.

If you started the server before adding the token, stop it and run the startup script again so it reads the new environment.

Back on Connect your server, click Check connection. Once it shows Connected, continue to Sync project.

For a brand-new agent, there's nothing to sync yet. Click Open project to finish setup; new sessions will arrive as you create them. If your agent already has sessions, follow the sync options on that page instead.

Connected confirms that the Dashboard can reach your running server. Continue to sync after this check succeeds.

A new agent has no past conversations to import. Choose Open project to finish setup and start testing.

Testing your agent

On the Dashboard's Overview page, click New session. This opens a simulation: a test conversation with the same running agent, without needing to build a frontend first.

If you started from lead-gen, play a buyer: "We're refitting a 40-room hotel by spring." If you started from basic, try a conversation from your own use case. The questions and screenshots below follow the retail-store example.

Send your first message:

Where is my order 1234?

The example should look up the sample order and tell you that the ceramic table lamp has shipped, with an estimated Thursday arrival. Then ask:

Can I get the tracking number?

The sample shipment is with UPS, with tracking number 1Z999AA10123456784. The wording can vary; what matters is that the agent retrieves the order and answers the follow-up about that same shipment.

Expand Agent activity on a reply to inspect its tool calls when the trace is available. Return to Sessions to see the conversation, or Overview to check server health and your simulated-session count.

The agent remembers the shipment between messages and returns the sample UPS tracking number. This conversation uses the running local server.

Don't have access to the Dashboard?

You can still talk to your agent. Open http://localhost:8800 and start a session in the built-in chat page. It talks to the same local server, without the Dashboard's simulations and inspection tools.

Change the agent and test again

If you started from another scaffold, describe one small change you'll recognize easily, like a new greeting, and test it the same way. The steps below use the retail-store example.

Now ask your coding agent to add a real business rule: an express shipping offer for orders that haven't shipped yet. Copy this request into your coding agent:

Add a policy to Homeware Support: when a customer asks about an order that
hasn't shipped yet, give its status as usual, then offer to upgrade it to
express shipping for $9.99, which usually arrives within 2 business days of
shipping. If they accept, tell them our team will confirm the upgrade by email.
Don't offer it for orders that have already shipped. Save the change while the
server is running so we can test it in the Dashboard.

The rule only applies when it's relevant: to orders that are still being prepared. You don't need to write the policy code yourself.

Example policy your agent might add

Your coding agent can add a policy like this in main.py, after creating the agent and before installing its domains:

        await agent.create_policy(
            title="Express upgrade for unshipped orders",
            content=(
                "When a customer asks about an order that hasn't shipped yet, give its "
                "status as usual, then offer to upgrade it to express shipping for $9.99, "
                "which usually arrives within 2 business days of shipping. If they accept, "
                "tell them our team will confirm the upgrade by email. Never offer the "
                "upgrade for an order that has already shipped."
            ),
        )

Once your coding agent saves the change, Parlant notices Python source changes, shuts down cleanly, reloads the agent, and reconnects its Dashboard tunnel. You don't need to restart it by hand for this edit. Wait for the terminal to report that the server is ready again before sending another message; requests made during reload may be interrupted.

Create a new simulation and send:

Where is my order 5678?

Order 5678 is a wool throw blanket that's still being packed, so the agent should give its status and offer the $9.99 express upgrade. Then send:

What about order 1234? Can I get the tracking number?

That order has already shipped, so you should get its status and tracking number, with no upgrade offer. You've now tested the change through the reconnected server, not just changed a file on disk.

Keep the policy, or ask your coding agent to remove it. To keep building, describe the behavior you want and ask it to update the policies and connect the sample services to your own systems.

Source changes and environment changes

Hot reload watches Python source files. After changing .env, deliberately stop and restart the server so the new values are loaded. For production, disable hot reload and configure real services and authentication as described in Self-hosting.

If something isn't working

• The server fails to start: check the terminal error, your model provider key, the models mapping, and any required provider extra in the project's dependencies.
• The Dashboard can't connect: check that the server is running and that the project token in .env is the one from this Dashboard project. Restart after changing .env, then use Check connection again.
• The connection briefly drops after a code edit: wait for reload to finish and the server to reconnect before creating the next session.
• The conversation works but its row isn't listed yet: allow time for ingestion, then refresh the Sessions page. A persistent error needs investigation; don't delete your project or rotate its token just to retry ingestion.

Next steps

Your agent now runs locally, connects to the Dashboard, and reflects your code changes in fresh simulations. Time to take it live and integrate it into your live app or site. Get started on the next page.