Parlant: Behavioral Control Layer for Customer-Facing AI Agents

What Problem Parlant Solves and Who It Is For

Building customer-facing AI agents with consistent behavior runs into two known problems. System prompts degrade at scale: the more instructions you add, the less reliably the model follows any of them. Routed graphs address prompt overload but break under the non-linear nature of real conversations, where a user can jump between topics unpredictably.

Parlant positions itself as a solution to both. The README describes its approach as "context engineering, optimized for conversational control," meaning the framework controls which instructions, knowledge, and tools reach the model at any given turn, rather than sending everything and hoping the model pays attention. The result is meant to keep agent behavior aligned with business rules across a wide range of conversation paths.

The target users are engineering teams at companies building B2C or sensitive B2B conversational agents where consistency, compliance, on-brand tone, and comprehensive traceability are requirements. The README explicitly positions it as an alternative to platforms like Ada, Decagon, and Sierra. The two example files in the repository, `examples/healthcare.py` and `examples/travel_voice_agent.py`, indicate the intended domains: regulated industries and voice-capable deployments.

The Contextual Matching Engine: How Parlant Filters Context

Instead of sending a large system prompt with the full conversation history to the model, Parlant's engine first assembles a focused context. On each turn, the engine matches only the guidelines, tools, and knowledge fragments that are relevant to the current conversational state, then sends that narrowed set to the model for response generation.

The architecture diagram in the README shows six input types flowing into the Contextual Matching Engine: Observations (event-driven conditions), Guidelines (conditional instructions), Journeys (structured SOPs with steps), Retrievers (domain knowledge), a Glossary (domain terminology), and Variables (stored memories). The engine resolves which of these are active for the current turn, calls any contextually associated tools, and then generates the message from the resulting focused context.

This design is the core claim of Parlant's approach: rather than filtering output after generation through guardrails, the filtering happens before generation by controlling what enters the context window. The README references research into model accuracy and consistency (citing an ArXiv paper on Attentive Reasoning Queries) as the basis for this structural approach to behavioral alignment.

Core Concepts: Guidelines, Observations, Journeys, and Retrievers

A Guideline is a conditional instruction: it activates when its associated condition is met and injects the corresponding instruction into the context. This is the alternative to adding every rule to a monolithic system prompt.

An Observation is a condition evaluated against the current conversational context. The README shows an example where an observation activates when a customer uses financial terminology like "DTI" or "amortization," and that observation associates specific tools and deeper response behavior. Observations decouple the condition-detection from the instruction-application.

Journeys are structured SOPs with explicit steps. They allow encoding multi-step conversational procedures (onboarding flows, compliance-required disclosure sequences) without manually routing between nodes.

Retrievers connect domain knowledge to the agent. The Glossary provides domain-specific terminology so the model uses the company's vocabulary consistently. Variables store memories across turns, such as a user's stated preferences earlier in the conversation.

All of these are defined in code, not prompts. The README states: "You define your agent's behavior in code (not prompts), and the engine dynamically narrows the context on each turn to only what's immediately relevant."

Installing Parlant and Creating a First Agent

Installing the package from PyPI:

pip install parlant

Parlant requires Python 3.10 or later, with an upper bound of less than 3.15 due to compatibility constraints with torch 2.8+ and the triton library, as documented in `pyproject.toml`.

The README includes a short code example showing the pattern for creating an agent and attaching an observation:

import parlant.sdk as p

async with p.Server():
    agent = await server.create_agent(
        name="Customer Support",
        description="Handles customer inquiries for an airline",
    )

The SDK uses an async context manager for the server. Observations and guidelines attach to the agent with await calls. The README does not show the full example inline (it is truncated), but references the 5-minute quickstart at parlant.io/docs/quickstart/installation for a complete walkthrough.

The pyproject.toml lists a substantial dependency set including FastAPI, OpenAI SDK, MCP (Model Context Protocol), nano-vectordb for embedded vector search, Jinja2, OpenTelemetry for tracing, and structlog for structured logging. This means Parlant ships with its own HTTP server, vector store, and telemetry stack rather than requiring external services for basic operation.

Maintenance Status, License, and Dependency Constraints

The last push to the repository was on 2026-07-12. The most recent releases were v3.3.2 on 2026-04-28, v3.3.1 on 2026-04-14, and v3.3.0 on 2026-03-15. The project is not archived. Activity has slowed relative to the earlier release cadence but the repository is not dormant.

The license is Apache-2.0, which permits commercial use and modification. A separate DCO.md file in the repository indicates the project uses a Developer Certificate of Origin for contributions.

The Python version constraint (less than 3.15) is an active maintenance consideration: it restricts which environments Parlant can run in and will need to be updated as newer Python versions release. The pinned `parlant-client` dependency at v3.2.0 is fetched directly from the GitHub repository rather than PyPI, which adds a build-time network dependency on GitHub availability.

The `griffe` package is pinned to less than 2.0 explicitly to work around a fastmcp incompatibility, with a comment in `pyproject.toml` noting this can be removed in future fastmcp updates. Teams running other packages that depend on griffe 2.0+ may encounter conflicts.

Where Parlant Is the Wrong Tool

Parlant is designed for conversational use cases. The README is explicit that it is not intended for workflow automation or low-level prompt optimization. Teams building data pipelines, document processing workflows, or agents that do not interact conversationally with end users should look elsewhere.

The framework's depth comes at a setup cost. Integrating observations, guidelines, journeys, and retrievers requires understanding the framework's own model before writing any business logic. Teams wanting a quick prototype or a single-purpose chatbot will find the overhead significant.

Parlant bundles its own vector store (nano-vectordb) and HTTP server (FastAPI). This simplifies initial deployment but makes it harder to substitute a managed vector database or a different server framework later without patching the library itself.

The upper Python version bound is an operational constraint. Organizations with standardized Python 3.15+ environments will not be able to run Parlant without maintaining a separate virtual environment at a lower Python version.

Parlant vs LangGraph: Conversational Control vs Workflow Graphs

LangGraph is an open source library from LangChain for building stateful, multi-actor workflows as directed graphs. It is designed for general workflow automation: branching logic, conditional edges, and cyclic agent flows. The README directly compares the two, stating that "Parlant focuses on conversational governance and behavioral control and consistency, while LangGraph is ideal for workflow automation."

The architectural difference is concrete. In LangGraph, developers define nodes and edges explicitly, and the flow is deterministic given a graph state. In Parlant, developers define conditions and instructions, and the framework decides at runtime which of those are active for a given conversational turn. LangGraph's determinism is a strength for structured multi-step tasks; it becomes a fragility when users diverge from the expected path. Parlant's dynamic matching is designed precisely for that divergence.

For teams building a customer support or compliance-sensitive agent where the conversation can take any path within defined behavioral boundaries, Parlant's model fits better. For teams building a multi-step internal tool, a code review pipeline, or a sequential data extraction workflow, LangGraph's explicit graph model is more appropriate.

Editorial conclusion

Parlant is a practical choice for engineering teams building customer-facing agents where behavioral consistency, compliance traceability, and on-brand tone are non-negotiable constraints. Teams building internal workflow automation or data extraction pipelines will find LangGraph or similar workflow engines a better fit. Before committing, verify Python version compatibility (3.10 to less than 3.15 due to torch and triton constraints), review whether v3.3.2 is the latest stable release for your target deployment, and walk through the 5-minute quickstart at parlant.io to confirm the guidelines model fits your use case.

Frequently asked questions

Official sources

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