# Changelog

All notable changes to Parlant will be documented here.

## [Unreleased]

### Added

- Add `HealthReporter` (`parlant.core.health_reporter`) — a generic, per-process health-reporting service registered in the container. Subsystems call `report(kind, attributes)`; registered `HealthView` objects interpret reports per kind and contribute to the `/healthz` snapshot. Each kind has a configurable retention policy (`window` + `max_count`). Views declare `Criticality.CRITICAL` or `INFORMATIONAL`; only critical views feed the worst-of overall status rollup
- Add `NLPHealthView` reporting NLP request health sliced by schema (success rate, p50/p95 latency, recent error breakdown) with configurable thresholds for `degraded`/`unhealthy` classification
- Instrument `BaseSchematicGenerator.generate()` and `BaseEmbedder.embed()` to emit `nlp.request` / `nlp.embed` health reports on success and failure, providing dashboard visibility into LLM and embedding behavior across all adapters
- Wrap the existing event-loop check as `EventLoopHealthView` so `/healthz` rollup is uniform across all health views
- Add per-decision debug logs to journey node selection (`Journey '<title>': advanced/stayed/exited/completed/backtracked/auto-advanced/...`) so journey progression is visible at debug level alongside guideline matching
- Add a warning log for invalid condition ids returned during journey next-step selection

### Changed

- Rename journey `conditions` to `triggers` throughout the codebase, REST API, CLI, and SDKs to better reflect their role as activation signals. The REST API field, query parameter, and request bodies use `triggers` (no aliases). The Python SDK `Server.create_journey(...)` keeps `conditions=` as a deprecated keyword that emits a `DeprecationWarning`; passing both `triggers=` and `conditions=` raises an error. Existing journey records are migrated automatically by `parlant-prepare-migration` from the `journey_conditions` collection (with a `condition` field) to a new `journey_triggers` collection (with a `trigger` field). LLM prompt strings that include "Journey activation condition" are intentionally preserved
- Rename SDK callback `on_match` to `on_selected` on guidelines and journey state transitions to reflect that it fires post-resolution, when the entity is selected for message generation; `EngineHooks.on_guideline_match_handlers` and `on_journey_match_handlers` are renamed to `on_guideline_selected_handlers` and `on_journey_selected_handlers` accordingly
- Standardize guideline matcher log vocabulary: `"Activated"` → `"Matched"`, `"Skipped"` → `"Not matched"`, and `"Not applied"` → `"Unapplied"`
- Standardize relational resolver log vocabulary: `"Skipped: ... deactivated due to ..."` → `"Dropped (<reason>): ..."` with reasons `lower priority`, `unmet dependency`, `dependency on dropped entity`, `deprioritized by guideline`, and `deprioritized by journey`
- Disambiguation batch now uses the standard matcher vocabulary (`"Matched (disambiguation)"` / `"Not matched (disambiguation)"`) and emits a log on the negative branch (previously silent)
- Normalize observational batch rationale to plain `match.rationale` (no longer wrapped with `Condition Application Rationale: "..."`) for consistency with other batches
- Normalize low-criticality batch warning string to `"No checks generated"` to match other batches

### Removed

- Remove redundant `glm_service.py` NLP adapter and `NLPServices.glm()` factory method — the GLM/bigmodel.cn API is already covered by the existing Zhipu adapter (`zhipu_service.py`), which uses the official `zhipuai` SDK and supports GLM-4 model variants. Use `NLPServices.zhipu()` instead.

### Fixed

- Fix low-criticality matcher logging the entire inference blob once per guideline in a batch (N copies of the same payload at debug level); now logs a single per-item entry
- Fix WebSocketLogger event loop starvation — when no WebSocket clients are subscribed, the drain loop processed queued messages without yielding, progressively blocking the async event loop and causing increasing latency over time
- Fix journey reachable-follow-ups evaluation being order-dependent at fan-in nodes — `JourneyReachableNodesEvaluator` captured a child's path list by reference and then prepended to it in place, so a node with multiple parents had its stored routes mutated by whichever parent was visited first; the second parent then lost routes (or double-counted a hop) depending purely on graph/DFS order. The child's routes are now snapshotted per parent, making the result depend only on journey structure. This intentionally changes the computed follow-ups for existing fan-in journeys: a shared child's later parent now retains the routes it previously lost

### Security

- Upgrade dependencies to address known CVEs: authlib (>=1.6.11), requests (>=2.33.0), fastmcp (>=3.2.0), litellm (>=1.83.0), pytest (>=9.0.3), pyjwt (>=2.11.1), and constrain transitive deps — aiohttp, cryptography, pillow, pyopenssl, werkzeug, Mako, pyasn1, python-multipart, orjson, Pygments, diskcache
- Upgrade chat frontend: vite (>=7.3.2) and override transitive deps — picomatch, lodash, flatted, brace-expansion, immutable, yaml

## [3.3.1] - 2026-04-14

### Added

- Allow passing ToolId when attaching tools throughout the SDK
- Add `AnyOf(tag)` and `AllOf(tag)` modifiers for explicit control over tag dependency semantics in `depend_on()` — `AnyOf` requires at least one tagged member to be active, `AllOf` requires all of them (bare `Tag` defaults to `AllOf`)
- Add `depend_on_any()` to `Guideline`, `Tag`, and `Journey` for OR dependency relationships — at least one target must be active. Multiple `depend_on_any()` calls create independent OR groups that are AND'd together
- Add event loop health monitoring to `/healthz` endpoint — measures callback latency and reports `healthy`, `degraded`, or `unhealthy` status with peak latency over a configurable window
- Add resolution tracking to the relational resolver — every entity that enters resolution gets a `Resolution` with a `ResolutionKind` (`NONE`, `DEPRIORITIZED`, `UNMET_DEPENDENCY_ALL`, `UNMET_DEPENDENCY_ANY`, `ENTAILED`) and structured `ResolutionDetails` (relationship ID, target IDs) explaining why

### Changed

- Split `RelationshipEntityKind.TAG` into `TAG_ALL` and `TAG_ANY` to support explicit tag dependency semantics at the core level (existing `TAG` entries treated as `TAG_ALL` for backwards compatibility)

### Fixed

- Fix priority and dependency relationships propagating through inactive intermediaries — only direct relationships now affect resolution, consistent with the reinstatement principle from argumentation theory
- Fix entailment recording only the highest-scoring source when multiple guidelines entail the same target — all entailing relationships are now recorded in resolution details
- Fix dep-failed guidelines not recovering when entailment satisfies their dependency target in a later iteration
- Fix SDK startup appearing stuck at 100% after evaluations — add "Applying evaluations" progress bar for the metadata-writing phase
- Fix `Variable.get_value()` returning `None` when called from a retriever, caused by retrievers starting before context variables were loaded
- Fix journey tool-state auto-advancing even when the tool did not run

## [3.3.0] - 2026-03-15

### Added

- Add per-agent planners via `Server.create_agent(planner=...)`, allowing each agent to use a custom `Planner` implementation
- Accept `Tag` as a target in `depend_on()`, `exclude()`, and `prioritize_over()` on both `Guideline` and `Tag`, enabling relationships that target all guidelines sharing a custom tag
- Add `Tag.depend_on()`, `Tag.exclude()`, and `Tag.prioritize_over()` methods to the SDK, enabling tag-based dependency and priority relationships with guidelines and journeys
- Support custom TAG as source for DEPENDENCY relationships in the relational resolver
- Add `tags` parameter to `create_guideline`, `create_observation`, and `create_journey` on both `Agent` and `Journey`, allowing custom tags to be attached to entities at creation time
- Add `Tag.reevaluate_after()` method to the SDK, enabling tag-based reevaluation relationships with tools
- Add tag-based reevaluation support in the engine: when a tool fires, all guidelines carrying a tag that has a reevaluation relationship with that tool are now re-evaluated
- Add staged_events to GuidelineMatchingContext in SDK
- Add `priority` property to guidelines and journeys for priority-based filtering in the relational resolver
- Add transient guidelines (renamed from tool-provided guidelines), allowing tools to dynamically inject behavioral guidelines into the agent's context
- Add `Agent.utter()` to the SDK, enabling programmatic agent message generation with transient guidelines
- Add `Customer.update()` and `CustomerMetadata` to the SDK, allowing tools to update customer name and metadata
- Add `Session.update()`, `SessionMetadata`, and `SessionLabels` to the SDK, allowing tools to update session properties, metadata, and labels
- Add `customer`, `agent`, `mode`, and `title` properties to SDK `Session` class
- Add `Server.get_tag()` to the SDK, supporting lookup by either `id` or `name`
- Add name-based filtering to `TagStore.list_tags()` and the `GET /tags` API endpoint via an optional `name` query parameter
- Enforce tag name uniqueness in `TagStore`, raising an error when creating a tag with a duplicate name

### Changed

- Made extended thinking indicator optional in perceived performance policy
- Change `reevaluate_after()` on `Tag` and `Guideline` to accept multiple tools (`*tools`) and return `Sequence[Relationship]`
- Change `tags` field type from `Sequence[TagId]` to `Sequence[Tag]` on `Guideline`, `Journey`, `Capability`, `Term`, `Variable`, `Customer`, and `Agent` in the SDK
- Change `Tag.preamble()` to return a full `Tag` object instead of a `TagId`
- Upgrade MCP service and bump dependency versions to resolve security vulnerabilities

### Deprecated

- OpenAPI tool services are now deprecated; please migrate to SDK tool services

### Fixed

- Fix deadlock when sending a new message right after a preamble
- Fix transitive filtering in relational resolver for custom tag dependency targets (guidelines depending on a custom tag are now correctly deactivated when a tagged member is deprioritized)
- Fix SSE `read_event` endpoint stalling after first streaming chunk until full completion
- Fix response analysis logs not always reaching the integrated UI
- Fix guideline formatting in canned response and streaming modes when condition is absent
- Fix AzureService small text embedding dimension size
- Fix onnxruntime compatibility with Python 3.10 and transformers 5.x type changes
- Fix agent intention proposer prompt clarification
- Fix embedding LRU cache eviction corrupting the length index when entries share the same text length
- Fix LiteLLMEmbedder failing to resolve via lagom container when LITELLM_EMBEDDING_MODEL_NAME is set
- Fix non-consequential tool calls being rejected when optional parameters are missing

### Removed

- Remove stale `parlant-test` entry point and testing framework documentation from README

## [3.2.2] - 2026-02-18

### Added

- Added p.MATCH_ALWAYS, now the preferred alias to p.Guideline.MATCH_ALWAYS
- Added `logger` property to p.Server

### Changed

- Adjusted log levels of relational resolver to trace instead of debug
- Allow tool context parameter names to be all of 'context', 'ctx', and 'c'

### Fixed

- Fix completed streamed messages re-animating on page refresh
- Propagate `Server.current` context to tool functions in hosted plugin server

## [3.2.1] - 2026-02-17

### Added

- Add optional `dependencies` parameter to guideline, observation, and journey creation methods
- Add `exclude()` as an alias for `prioritize_over()` on guidelines and journeys
- Add `tools` parameter to `create_observation` methods

### Changed

- Deprecate `attach_tool()` in favor of `create_guideline()`/`create_observation()` with `tools` parameter

### Fixed

- Preserve draft message language during canned response recomposition
- Fix server hang when an exception occurs during setup
- Fix canned response field extraction to handle falsy values

## [3.2.0] - 2026-02-08

### Added

- Add labels to Guidelines, Journeys, JourneyNodes, and Sessions for categorization and filtering
- Add automatic session label propagation from matched entities (guidelines, observations, journeys)
- Add `track` parameter to guidelines to control "previously applied" tracking
- Support multiple targets in `prioritize_over()` and `depend_on()` methods
- Add `field_dependencies` to canned responses for explicit field availability requirements
- Add `attach_retriever()` to Guideline, Journey, and JourneyState for conditional data retrieval
- Add `on_match` and `on_message` hooks to journeys for lifecycle callbacks
- Add per-agent preamble configuration (custom examples and instructions)
- Add separate default greeting responses for first agent message in fluid mode
- Add streaming message output mode
- Allow specifying custom journey node ID
- Add matched guidelines/journey states to completion ready event

### Changed

- Make condition optional for SDK guidelines
- Tweak default preamble examples
- Soften log levels for relational guideline resolver
- Add activated/skipped logs to custom guideline matcher batches

### Fixed

- Fix websocket warning upon startup
- Fix agent intention proposer (guidelines were getting rewritten incorrectly)
- Fix multiple customer guideline matchers not working
- Fix bug with context variable access in SDK

## [3.1.0] - 2026-01-05

### Added

- Add .current property for Server, Agent, and Customer in SDK
- Add /healthz endpoint
- Add API for CRUD operations on session metadata
- Add EmcieService
- Add GLM service
- Add Mistral service
- Add OpenRouter service
- Add OpenTelemetry integration for Meter, Logger and Tracer
- Add Qdrant VectorDatabase adapter
- Add Snowflake Cortex service
- Add ability to configure and extend the FastAPI app object
- Add deferred retrievers
- Add dynamic composition mode
- Add follow-up canned responses
- Add guideline criticality level
- Add guideline on_match() hooks
- Add persistence option for context variable values (variable store)
- Added guideline descriptions
- Allow bailing out of canned response selection and utilize the draft directly, using a hook
- Allow controlling max tool result payload via environment variable
- Allow controlling perceived performance policy per agent
- Allow journey transitions from one tool state to another
- Allow specifying custom IDs when creating agents via SDK and API
- Allow specifying custom IDs when creating customers via SDK and API
- Allow specifying custom IDs when creating guidelines, journeys, and glossary terms via SDK and API
- Expose IoC container in server object
- Support adding custom canrep fields to matched guidelines and journey states
- Support code-based, custom guideline matchers

### Changed

- Changed default NLPService to EmcieService
- Improved efficiency of journey state matching when first state is a tool state
- Rename ContextualCorrelator to Tracer
- Rename LoadedContext to EngineContext
- Support proxy URL for LiteLLM

### Fixed

- Fix critical bug with cancellation during response analysis
- Fix critical similarity calculation error in TransientVectorDatabase
- Fix unnecessary extra evaluation of journeys and tools in some edge cases
- Improved Gemini Flash 2.5 output consistency by using function call trick instead of structured outputs

## [3.0.4] - 2025-11-18

### Fixed

- Fix bug where NanoDB query failed when no filters matched
- Extend tool insights across iterations
- Fix deprecated status.HTTP_422_UNPROCESSABLE_ENTITY to status.HTTP_422_UNPROCESSABLE_CONTENT
- Fix broken CLI by adding missing websocket-client dependency
- Added specific classes for embedder initialisation
- Make base url once in OllamaEmbedder
- Update dependencies for security, upgrade FastAPI, fix mypy in hugging_face.py
- Bump torch for fixing vulnerability

## [3.0.3] - 2025-10-23

### Fixed

- Fix installation issue in some environments, failing due to an older FastMCP version
- Bump versions of OpenTelemetry
- Made ChromaDB an extra package parlant[chroma]
- Update NPM dependencies for integrated UI

## [3.0.2] - 2025-08-27

### Added

- Added docs/\* and llms.txt
- Added Vertex NLP service
- Added Ollama NLP service
- Added LiteLLM support to the SDK
- Added Gemini support to the SDK
- Added Journey.create_observation() helper
- Added auth permission READ_AGENT_DESCRIPTION
- Added optional AWS_SESSION_TOKEN to BedrockService
- Support creating status events via the API

### Changed

- Moved tool call success log to DEBUG level
- Optimized canrep to not generate a draft in strict mode if no canrep candidates found
- Removed `acknowledged_event_offset` from status events
- Removed `last_known_event_offset` from `LoadedContext.interaction`

### Fixed

- Fixed presentation of missing API keys for built-in NLP services
- Improvements to canned response generation
- Fixed bug with null journey paths in some cases
- Fixed tiny bug with terminal nodes in journey node selection
- Fixed evaluations not showing properly after version upgrade

## [3.0.1] - 2025-08-16

### Changed

- Move tool call success log to DEBUG level

### Fixed

- Fix tool-based variable not enabling the associated tool on the server
- Fix authorization errors throwing 500 instead of 403
- Changed OpenAI LLM request operation level to TRACE to fix evaluation progress bars

## [3.0.0] - 2025-08-15

- Please see the announcement at https://parlant.io/blog/parlant-3-0-release

## [2.2.0] - 2025-05-20

### Added

- Add journeys
- Add of guideline properties evaluation
- Add automatic guideline action deduction when adding direct tool guidelines
- Added choices of invalid and missing tool parameters to tool insights

### Changed

- Make guideline action optional

## [2.1.2] - 2025-05-07

### Changed

- Remove interaction history from utterance recomposition prompt
- Use tool calls from the entire interaction for utterance field substitution
- Improve error handling and reporting with utterance rendering failures

### Fixed

- Always reason about utterance selection to improve performance

## [2.1.1] - 2025-04-30

### Fixed

- Fixed rendering relationships in CLI
- Fixed parlant client using old imports from python client SDK

## [2.1.0] - 2025-04-29

### Added

- ToolParameterOptions.choice_provider can now access ToolContext
- Added utterance/draft toggle in the integrated UI
- Added new guideline relationship: Dependency
- Added tool relationships and the OVERLAP relationship
- Added the 'overlap' property to tools. By default, tools will be assumed not to overlap with each other, simplifying their evaluation at runtime.
- Introduce ToolBatchers
- Introduce Journey

### Changed

- Improved tool calling efficiency by adjusting the prompt to the tool at hand
- Revised completion schema (ARQs) for tool calling
- Utterances now follow a 2-stage process: draft + select
- Changed guest customer name to Guest

### Fixed

- Fixed deprioritized guidelines always being skipped
- Fixed agent creation with tags
- Fixed client CLI exit status when encountering an error
- Fixed agent update

### Known Issues

- OpenAPI tool services sometimes run into issues due to a version update in aiopenapi3

## [2.0.0] - 2025-04-09

### Added

- Improved tool parameter flexibility: custom types, Pydantic models, and annotated ToolParameterOptions
- Allow returning a new (modified) container in modules using configure_module()
- Added Tool Insights with tool parameter options
- Added support for default values for tool parameters in tool calling
- Added WebSocket logger feature for streaming logs in real time
- Added a log viewer to the sandbox UI
- Added API and CLI for Utterances
- Added support for the --migrate CLI flag to enable seamless store version upgrades during server startup
- Added clear rate limit error logs for NLP adapters
- Added enabled/disabled flag for guidelines to facilitate experimentation without deletion
- Allow different schematic generators to adjust incoming prompts in a structured manner
- Added tags to context variables, guidelines, glossary and agents
- Added guideline matching strategies
- Added guideline relationships
- Added support for tool parameters choice provider using the tool context as argument

### Changed

- Made the message generator slightly more polite by default, following user feedback
- Allow only specifying guideline condition or action when updating guideline from CLI
- Renamed guideline proposer with guideline matcher

### Fixed

- Lowered likelihood of the agent hallucinating facts in fluid mode
- Lowered likelihood of the agent offering services that were not specifically mentioned by the business

## [1.6.2] - 2025-01-29

### Fixed

- Fix loading DeepSeek service during server boot

## [1.6.1] - 2025-01-20

### Fixed

- Fix ToolCaller not getting clear information on a parameter being optional
- Ensure ToolCaller only calls a tool if all required args were given
- Improve valid JSON generation likelihood in MessageEventGenerator
- Improve ToolCaller's ability to correctly run multiple tools at once

## [1.6.0] - 2025-01-19

### Added

- Add shot creation helper functions under Shot
- Add ContextEvaluation in MessageEventGenerator
- Add a log command under client CLI for streaming logs
- Add engine lifecycle hooks

### Changed

- Split vendor dependencies to extra packages to avoid reduce installation time
- Modified ToolCaller shot schema
- Disable coherence and connection checking by default in the CLI for now

### Fixed

- Improved GuidelineProposer's ability to handle compound actions
- Improved GuidelineProposer's ability to distinguish between a fulfilled and unfulfilled action
- Improved GuidelineProposer's ability to detect a previously applied guideline's application to new information
- Reduced likelihood of agent offering hallucinated services
- Fix ToolCaller false-negative argument validation from int to float
- Fix ToolCaller accuracy
- Fix ToolCaller making up argument values when it doesn't have them
- Fix some cases where the ToolCaller also calls a less-fitting tool
- Fix mistake in coherence checker few shots
- Fix markdown tables in sandbox UI
- Fix wrong import of RateLimitError
- Fix PluginServer validation for optional tool arguments when they're passed None
- Fix utterances sometimes not producing a message

## [1.5.1] - 2025-01-05

### Fixed

- Fix server CLI boot

## [1.5.1] - 2025-01-05

### Fixed

- Fix server CLI boot

## [1.5.0] - 2025-01-04

### Added

- Add DeepSeek provider support (via DeepSeekService)

### Changed

- Change default home dir from runtime-data to parlant-data

### Fixed

- Fix tool-calling test
- Fix HuggingFace model loading issues

## [1.4.3] - 2025-01-02

### Fixed

- Upgraded dependency "tiktoken" to 0.8.0 to fix installation errors on some environments

## [1.4.2] - 2024-12-31

### Fixed

- Fix race condition in JSONFileDocumentDatabase when deleting or updating documents

## [1.4.1] - 2024-12-31

### Changed

- Remove tool metadata from prompts - agents are now only aware of the data itself

### Fixed

- Fix tool calling in scenarios where a guideline has multiple tools where more than one should run

## [1.4.0] - 2024-12-31

### Added

- Support custom plugin data for PluginServer
- Allow specifying custom logger ID when creating loggers
- Add 'hosted' parameter to PluginServer, for running inside modules

### Fixed

- Fix the tool caller's few shots to include better rationales and arguments.

## [1.3.1] - 2024-12-27

### Changed

- Return event ID instead of trace ID from utterance API
- Improve and normalize entity update messages in client CLI

## [1.3.0] - 2024-12-26

### Added

- Add manual utterance requests
- Refactor few-shot examples and allow adding more examples from a module
- Allow tapping into the PluginServer FastAPI app to provide additional custom endpoints
- Support for union parameters ("T | None") in tool functions

### Changed

- Made all stores thread-safe with reader/writer locks
- Reverted GPT version for guideline connection proposer to 2024-08-06
- Changed definition of causal connection to take the source's when statement into account. The connection proposer now assumes the source's condition is true when examining if it entails other guideline.

### Fixed

- Fix 404 not being returned if a tool service isn't found
- Fix having direct calls to asyncio.gather() instead of safe_gather()

### Removed

- Removed connection kind (entails / suggests) from the guideline connection proposer and all places downstream. the connection_kind argument is no longer needed or supported for all guideline connections.

## [1.2.0] - 2024-12-19

### Added

- Expose deletion flag for events in Session API

### Changed

- Print traceback when reporting server boot errors
- Make cancelled operations issue a warning rather than an error

### Fixed

- Fixed tool calling with optional parameters
- Fixed sandbox UI issues with message regeneration and status icon
- Fixed case where guideline is applied due to condition being partially applied

### Removed

None

## [1.1.0] - 2024-12-18

### Added

- Customer selection in sandbox Chat UI
- Support tool calls with freshness rules for context variables
- Add support for loading external modules for changing engine behavior programmatically
- CachedSchematicGenerator to run the test suite more quickly
- TransientVectorDatabase to run the test suite more quickly

### Changed

- Changed model path for Chroma documents. You may need to delete your `runtime-data` dir.

### Fixed

- Improve handling of partially fulfilled guidelines

### Removed

None