> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/emcie-co/parlant) · [上游 README](https://github.com/emcie-co/parlant/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
> **在寻找 Ada、Decagon 或 Sierra 的开源替代方案？**
**Parlant 已可用于生产环境。它简化了企业级 B2C（business-to-consumer，企业对消费者）以及需要保持一致、合规、符合品牌形象且可全面追溯的敏感 B2B 交互的开发与维护。**
## 为什么选择 Parlant？
对话式上下文工程（conversational context engineering）之所以困难，是因为真实世界的交互多样、微妙且非线性。
### ❌ 问题：你可能已经尝试过、却无法规模化落地的做法
**系统提示词（system prompts）** 在投产复杂度上升之前还能奏效。你在提示词中加入的指令越多，智能体就越快会忽略其中任何一条。
**路由图（routed graphs）** 能解决提示词过载问题，但路由越多，面对自然交互的混乱时就越脆弱。
### 🔑 解决方案：面向对话控制的上下文工程
Parlant 是一个智能体框架（agentic harness），针对对话场景优化了 [context engineering](https://www.gartner.com/en/articles/context-engineering) for conversational use cases：在恰当时机将恰到好处的上下文注入提示词——不多也不少。你只需定义一次规则、知识与工具，引擎会在实时对话中把上下文收窄到与每一轮对话直接相关的内容。
### Parlant 与 LangGraph 或 DSPy 有何不同？
Parlant 专注于对话治理（conversational governance）以及行为控制与一致性，而 LangGraph 更适合工作流自动化，DSPy 更适合底层提示词优化。
## 设计目标
Parlant 围绕三个目标构建，这些目标塑造了框架中的每一项决策：
### 1. 对对话体验的最大控制
Parlant 围绕一个简单理念设计：开发者应能精确控制智能体的行为。在面向客户的对话中，语气、时机、边界情况、策略约束和品牌调性等细节都很重要。因此我们选择了一种让这些方面易于配置和管理的设计。这种做法会增加复杂度，但能让团队更紧密地掌控智能体在真实对话中的表现。
### 2. 最大程度防止不良行为
Parlant 将行为偏离（misalignment）视为核心设计问题。它基于[关于模型准确性与一致性的研究](https://arxiv.org/abs/2503.03669#:~:text=We%20present%20Attentive%20Reasoning%20Queries%20%28ARQs%29%2C%20a%20novel,in%20Large%20Language%20Models%20through%20domain-specialized%20reasoning%20blueprints.) so that it is structurally harder for the agent to behave outside its intended boundaries, and easier to detect and correct when it does. 与其在输出端事后加装护栏，Parlant 从一开始就在 LLM 的使用方式中施加约束与控制点，以产出安全且正确的输出。
### 3. 从产品反馈到实现的最快路径
Parlant 力求让负责智能体对话体验的人员能以直观方式塑造其行为，从而形成工程师可以快速响应的反馈循环。Parlant 的设计让你能尽可能快地将持续的产品反馈纳入其中，而无需手动重连图结构或微调模型，确保宝贵的工程时间只用于更深层的改动，而非琐碎调整。
## 快速开始
```bash
pip install parlant
```
```python
import parlant.sdk as p
async with p.Server():
agent = await server.create_agent(
name="Customer Support",
description="Handles customer inquiries for an airline",
)
# Evaluate and call tools only under the right conditions
expert_customer = await agent.create_observation(
condition="customer uses financial terminology like DTI or amortization",
tools=[research_deep_answer],
)
# When the expert observation holds, always respond
# with depth. Set the guideline to automatically match
# whenever the observation it depends on holds...
expert_answers = await agent.create_guideline(
matcher=p.MATCH_ALWAYS,
action="respond with technical depth",
dependencies=[expert_customer],
)
beginner_answers = await agent.create_guideline(
condition="customer seems new to the topic",
action="simplify and use concrete examples",
)
# When both match, beginners wins. Neither expert-level
# tool-data nor instructions can enter the agent's context.
await beginner_answers.exclude(expert_customer)
```
请跟随 **[5 分钟快速入门](https://www.parlant.io/docs/quickstart/installation)** for a full walkthrough. 获取完整演练。
## Parlant 一览
你在代码中（而非提示词中）定义智能体行为，引擎会在每一轮动态收窄上下文，仅保留当下直接相关的内容，从而让 LLM 保持专注、智能体保持对齐。
```mermaid
graph TD
O[Observations] -->|Events| E[Contextual Matching Engine]
G[Guidelines] -->|Instructions| E
J["Journeys (SOPs)"] -->|Current Steps| E
R[Retrievers] -->|Domain Knowledge| E
GL[Glossary] -->|Domain Terms| E
V[Variables] -->|Memories| E
E -->|Tool Requests| T[Tool Caller]
T -.->|Results + Optional Extra Matching Iterations| E
T -->|**Key Result:**
Focused Context Window| M[Message Generation]
```
Parlant 不会向模型发送冗长的系统提示词再接原始对话，而是先组装一份聚焦的上下文——仅匹配与每一轮对话相关的指令与工具——再基于收窄后的上下文生成回复。
```mermaid
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#e8f5e9', 'primaryTextColor': '#1b5e20', 'primaryBorderColor': '#81c784', 'lineColor': '#66bb6a', 'secondaryColor': '#fff9e1', 'tertiaryColor': 'transparent'}}}%%
flowchart LR
A(User):::outputNode
subgraph Engine["Parlant Engine"]
direction LR
B["Match Guidelines and Resolve Journey States"]:::matchNode
C["Call Contextually-Associated Tools and Workflows"]:::toolNode
D["Generated Message"]:::composeNode
E["Canned Message"]:::cannedNode
end
A a@-->|💬 User Input| B
B b@--> C
C c@-->|Fluid Output Mode?| D
C d@-->|Strict Output Mode?| E
D e@-->|💬 Fluid Output| A
E f@-->|💬 Canned Output| A
a@{animate: true}
b@{animate: true}
c@{animate: true}
d@{animate: true}
e@{animate: true}
f@{animate: true}
linkStyle 2 stroke-width:2px
linkStyle 4 stroke-width:2px
linkStyle 3 stroke-width:2px,stroke:#3949AB
linkStyle 5 stroke-width:2px,stroke:#3949AB
classDef composeNode fill:#F9E9CB,stroke:#AB8139,stroke-width:2px,color:#7E5E1A,stroke-width:0
classDef cannedNode fill:#DFE3F9,stroke:#3949AB,stroke-width:2px,color:#1a237e,stroke-width:0
```
这样一来，增加更多规则会让智能体更聪明，而不是更困惑——因为由引擎来过滤上下文相关性，而非由 LLM 负责。
## Parlant 适合你吗？
Parlant 面向那些需要让 AI 智能体在真实客户面前可靠表现的团队而构建。若符合以下情况，它会是不错的选择：
- 你正在构建**面向客户的智能体（customer-facing agent）**——支持、销售、onboarding（入驻引导）、咨询等——在这些场景中语气、准确性与合规性至关重要。
- 你有**数十甚至数百条行为规则**，系统提示词已不堪重负。
- 你处于**受监管或高风险领域**（金融、保险、医疗、电信），每条回复都需要可解释、可审计。
**_Parlant 已在最严苛的组织中投入生产使用，其中包括银行。_**
> _Parlant 不仅仅是一个框架。它是直接正面解决对话建模（conversational modeling）问题的高层软件。_
> — **Sarthak Dalabehera**, Principal Engineer, Slice Bank
> _这是我见过的最优雅的对话式 AI 框架。_
> — **Vishal Ahuja**, Senior Lead, Applied AI, JPMorgan Chase
> _Parlant 大幅减少了提示工程（prompt engineering）和复杂流程控制的需求。构建智能体更接近领域建模（domain modeling）。_
> — **Diogo Santiago**, AI Engineer, Orcale
## 功能特性
- **[Guidelines](https://parlant.io/docs/concepts/customization/guidelines)** —
行为规则以条件-动作（condition-action）对表示；引擎每轮仅匹配相关内容。
- **[Relationships](https://parlant.io/docs/concepts/customization/relationships)** —
准则之间的依赖与互斥关系，使上下文保持精简且聚焦。
- **[Journeys](https://parlant.io/docs/concepts/customization/journeys)** —
多轮 SOP（标准作业程序），能根据客户实际交互方式自适应调整。
- **[Canned Responses](https://parlant.io/docs/concepts/customization/canned-responses)** —
预批准的回复模板，在关键时刻消除幻觉风险。
- **[Tools](https://parlant.io/docs/concepts/customization/tools)** —
外部 API 与工作流，仅在其观测条件匹配时触发。
- **[Glossary](https://parlant.io/docs/concepts/customization/glossary)** —
领域专用词汇，使智能体理解客户的语言。
- **[Explainability](https://parlant.io/docs/advanced/explainability)** —
完整的 OpenTelemetry 追踪——每条准则匹配与决策均有日志记录。
## [Guidelines](https://parlant.io/docs/concepts/customization/guidelines)
行为规则以条件-动作对表示：当条件成立时，对应动作即进入上下文。
引擎不会在单个提示词中塞入全部准则，而是在每轮对话中评估哪些准则适用，并仅将相关准则纳入 LLM 的上下文。
这样你可以定义数百条准则，而不会降低遵循度。
```python
await agent.create_guideline(
condition="customer uses financial terminology like DTI or amortization",
action="respond with technical depth — skip basic explanations",
)
```
## [Relationships](https://parlant.io/docs/concepts/customization/guidelines)
元素之间的关系帮助你把最终上下文调控得恰到好处：精简且聚焦。
**互斥（Exclusion）**关系在匹配到冲突准则时，将特定准则排除在模型注意力之外。
```python
for_experts = await agent.create_guideline(
condition="customer uses financial terminology",
action="respond with technical depth",
)
for_beginners = await agent.create_guideline(
condition="customer seems new to the topic",
action="simplify and use concrete examples",
)
# In conflicting reads of the customer, set which takes priority
await for_beginners.exclude(for_experts)
```
**依赖（Dependency）**关系确保某条准则仅当另一条准则已奠定基础时才激活，帮助你构建_基于主题的准则层级结构。_
```python
suspects_fraud = await agent.create_observation(
condition="customer suspects unauthorized transactions on their card",
)
await agent.create_guideline(
condition="customer wants to take action regarding the transaction",
action="ask whether they want to dispute the transaction or lock the card",
# Only activates when fraud suspicion has been established
dependencies=[suspects_fraud],
)
```
## [Journeys](https://parlant.io/docs/concepts/customization/journeys)
多轮 SOP（标准作业程序，Standard Operating Procedures）。为预订、故障排查、onboarding 等流程定义路径。智能体遵循该流程但会自适应调整——它可以快进状态、回到先前状态，或根据客户交互方式调整节奏。
```python
journey = await agent.create_journey(
title="Book Flight",
description="Guide the customer through flight booking",
conditions=["customer wants to book a flight"],
)
t0 = await journey.initial_state.transition_to(
# Instruction to follow while in this state (could be multiple turns)
chat_state="See if they're interested in last-minute deals",
)
# Branch A - not interested in deals
t1 = await t0.target.transition_to(
chat_state="Determine where they want to go and when",
condition="They aren't interested",
)
# Branch B - interested in deals
t2 = await t0.target.transition_to(
tool_state=load_latest_flight_deals,
condition="They are",
)
t3 = await t1.target.transition_to(
chat_state="List deals and see if they're interested",
)
```
## [Canned Responses](https://parlant.io/docs/concepts/customization/canned-responses)
在关键时刻或对话事件中，将智能体限制为仅使用预批准的回复模板。
运行匹配序列并为客户端拟稿后，智能体会选择与其生成草稿最匹配的模板，而非直接发送草稿，从而彻底消除幻觉风险，并确保措辞字字准确。
```python
await agent.create_guideline(
condition="The customer discusses things unrelated to our business"
action="Tell them you can't help with that",
# Strict composition mode triggers when this guideline
# matches - the rest of the agent stays fluid
composition_mode=p.CompositionMode.STRICT,
canned_responses=[
await agent.create_canned_response(
"Sorry, but I can't help you with that."
)
],
priority=100, # Top priority, focuses the agent on this alone
)
```
## [Tools](https://parlant.io/docs/concepts/customization/tools)
工具仅在其观测条件匹配时激活；它们不会永久占用上下文。这避免了困扰传统 LLM 工具配置的错误阳性调用。
```python
@p.tool
async def query_docs(context: p.ToolContext, user_query: str) -> p.ToolResult:
results = search_knowledge_base(user_query)
return p.ToolResult(results)
await agent.create_observation(
condition="customer asks about service features",
tools=[query_docs],
)
```
工具还可将自定义值注入预制回复模板。
## [Glossary](https://parlant.io/docs/concepts/customization/glossary)
为你的智能体配置领域专用词汇。将口语化表达与同义词映射到精确的业务定义，使智能体理解客户的语言。
```python
await agent.create_term(
name="Ocean View",
description="Room category with direct view of the Atlantic",
synonyms=["sea view", "rooms with a view to the Atlantic"],
)
```
## [Explainability](https://parlant.io/docs/advanced/explainability)
每项决策均通过 OpenTelemetry 追踪。Parlant 开箱即用，提供完善的日志、指标与追踪数据。
## 框架集成
Parlant 负责对话治理（conversational governance）；它不会取代你现有的技术栈。
可与 LangGraph、Agno、LlamaIndex 等框架搭配使用，用于工作流自动化与知识检索。Parlant 接管行为控制层，而你选择的框架处理智能体其余的处理逻辑。
任何外部工作流或智能体（agent）都可以成为 Parlant 工具，仅在相关时触发：
```python
from my_workflows import refund_graph # a compiled LangGraph StateGraph
@p.tool
async def run_refund_workflow(
context: p.ToolContext,
order_id: str
) -> p.ToolResult:
result = await refund_graph.ainvoke({"order_id": order_id})
# Graph result can inject both data and instructions into the agent.
# Instructions are transformed to guidelines, and participate
# in contextual guideline resolution (including prioritizations)
return p.ToolResult(
data=result["data"],
# Inject dynamic guidelines from workflow result
guidelines=[
{"action": inst, "priority": 3} for inst in result["instructions"]
],
)
await agent.create_observation(
condition="customer wants to process a refund",
tools=[run_refund_workflow],
)
```
同样的模式也适用于 LlamaIndex 查询引擎、Agno agents，或任何异步 Python 函数。
## LLM 无关
Parlant 可与大多数 LLM 提供商配合使用。推荐的是 [Emcie](https://www.emcie.co)，它专为 Parlant 构建，在成本与质量之间提供了理想平衡；OpenAI 和 Anthropic 也能产出出色的高质量结果。你也可以通过 LiteLLM 使用任意模型和提供商，但它们需要足够优秀——现成的过小模型往往会产生不一致的结果。
一般来说，你可以在不更改行为配置的情况下切换模型。
## [官方 React 聊天组件](https://github.com/emcie-co/parlant-chat-react)
即插即用的聊天组件，可立即启动前端。
## 了解更多
- **[Parlant 如何确保合规](https://www.parlant.io/blog/how-parlant-guarantees-compliance)** — 深入了解引擎
- **[Parlant 与 LangGraph 对比](https://www.parlant.io/blog/parlant-vs-langgraph)** — 何时使用哪一个
- **[Parlant 与 DSPy 对比](https://www.parlant.io/blog/parlant-vs-dspy)** — 不同问题选用不同工具
## 社区 - 获取 Parlant 帮助
- **[Discord](https://discord.gg/duxWqxKk6J)** — 提问并分享你的作品
- **[GitHub Issues](https://github.com/emcie-co/parlant/issues)** — 错误报告与功能请求
- **[Contact](https://parlant.io/contact)** — 直接联系工程团队
**如果 Parlant 帮助你构建了更好的 agents，**[给它点个星](https://github.com/emcie-co/parlant)** — 这能帮助其他人发现该项目。**
## 许可证
Apache 2.0 — 可免费用于商业用途。
---
**[立即试用](https://www.parlant.io/docs/quickstart/installation)** • **[加入 Discord](https://discord.gg/duxWqxKk6J)** • **[阅读文档](https://www.parlant.io/)**
由 **[Emcie](https://emcie.co)** 团队构建
