Parlant

ParlantAdapter connects a Parlant agent to Band rooms. Parlant matches each message against condition and action guidelines that you declare, which suits agents whose responses must follow fixed rules. In Python, the adapter starts and stops the Parlant server inside your process.

The adapter ships in the Python SDK (band-sdk 6.0.1) and the TypeScript SDK (@band-ai/sdk 0.6.0). The TypeScript adapter connects to a Parlant server you run, see Connect from TypeScript.

Prerequisites

• A Band account at app.band.ai
• Python 3.11 or later and uv. For Connect from TypeScript, Node.js 22.12 or later
• An OPENAI_API_KEY from OpenAI, for Parlant’s OpenAI NLP service

Connect the Agent

echo "agent_config.yaml" >> .gitignore

uv init band-parlant && cd band-parlant
uv add "band-sdk[parlant]==6.0.1"

OPENAI_API_KEY=sk-...

echo "parlant-data/" >> .gitignore

import asyncio
import logging
import parlant.sdk as p
from dotenv import load_dotenv
from band import Agent, configure_logging
from band.adapters import ParlantAdapter, ParlantAdapterConfig
configure_logging(logging.INFO)
def build_adapter() -> ParlantAdapter:
    adapter = ParlantAdapter(
        ParlantAdapterConfig(
            description="You are a support assistant. Give specific, accurate answers.",
        ),
        nlp_service=p.NLPServices.openai,
    )
    adapter.add_guideline(
        condition="The user asks a question or needs help",
        action="Answer the question directly, then ask whether anything else is unclear",
    )
    adapter.add_guideline(
        condition="The user asks for help you cannot provide",
        action="Use band_lookup_peers to find an agent that can help, then add it with band_add_participant",
    )
    return adapter
async def main() -> None:
    load_dotenv()
    agent = Agent.from_config("my_agent", adapter=build_adapter())
    await agent.run()
if __name__ == "__main__":
    asyncio.run(main())

uv run agent.py

2026-09-30 09:30:00 [INFO] band.integrations.parlant.ports: Parlant server ports: api=54321, tool_service=54322
2026-09-30 09:30:20 [INFO] band.adapters.parlant.adapter: Parlant SDK adapter started for agent: Parlant Agent (parlant_agent_id=...)
2026-09-30 09:30:21 [INFO] band.agent: Agent started: Parlant Agent (band-sdk 6.0.1)

Declare Guidelines

add_guideline(condition, action) queues a guideline that the adapter creates on the Parlant agent at startup. Extra keyword arguments go to Parlant’s create_guideline unchanged.

Each guideline gets Band’s platform tools by default, so its action can name tools such as band_lookup_peers. Pass tools=[] for a guideline that only shapes the reply, which keeps the tool schemas out of that guideline:

adapter.add_guideline(
    condition="The customer thanks you",
    action="Thank them and offer further help",
    tools=[],
)

The adapter posts Parlant’s reply to the room and mentions the sender. If a guideline already sent the reply through band_send_message, the adapter does not post it again. Parlant’s preamble messages are never posted.

Call add_guideline before the agent starts. After startup it raises RuntimeError: add_guideline must be called before the agent starts. For guidelines on a running agent, journeys, or other Parlant APIs, pass an async configure(server, parlant_agent) callback, which runs at startup after the declared guidelines are created.

Configure the Parlant Server

nlp_service and server_options are arguments of ParlantAdapter. name, description, custom_section, system_prompt, response_timeout, and response_poll are fields of ParlantAdapterConfig.

Parlant’s own server defaults to the fixed ports 8800 and 8818, so two servers on one host collide. The adapter reserves a free pair on every start, which lets several Parlant agents run on one host. The ports line in the log shows the pair it chose.

Parlant stores its data, including parlant.log and an embedding cache, in parlant-data/ in the working directory. Set PARLANT_HOME to use another directory.

Bring Your Own Server

Pass server= to use a Parlant server your process already runs, and parlant_agent= to use an agent you created on it. The adapter does not stop a server you pass in.

import asyncio
import parlant.sdk as p
from dotenv import load_dotenv
from band import Agent
from band.adapters import ParlantAdapter
async def main() -> None:
    load_dotenv()
    async with p.Server(nlp_service=p.NLPServices.openai) as server:
        parlant_agent = await server.create_agent(
            name="Support Agent",
            description="You are a support assistant.",
        )
        adapter = ParlantAdapter(server=server, parlant_agent=parlant_agent)
        await Agent.from_config("my_agent", adapter=adapter).run()
if __name__ == "__main__":
    asyncio.run(main())

A server you construct uses Parlant’s fixed default ports unless you pass port and tool_service_port. The script does not call configure_logging, so after Parlant’s banner it prints nothing while the agent runs, and Parlant’s HTTP API stays down until the async with block exits.

These combinations raise ValueError when you construct the adapter:

• parlant_agent without server
• nlp_service or server_options with server
• system_prompt or custom_section with parlant_agent
• response_timeout or response_poll at or below 0

Events and Capabilities

ParlantAdapter posts no tool call or usage events, and any Emit value raises BandConfigError. The room shows only what the agent sends, including events a guideline sends with band_send_event.

capabilities={Capability.CONTACTS} adds the contact tools to the tools attached to each guideline. The Parlant tool set has no memory tools, so Capability.MEMORY adds none. See adapter features.

Connect from TypeScript

@band-ai/sdk 0.6.0 ships a ParlantAdapter that connects to a Parlant server you already run, through the parlant-client package. It does not start a server or declare guidelines: configure the Parlant agent on the server first. Without agentId, the adapter creates a Parlant agent named band-<agent name> from Band’s rendered system prompt and deletes it when the runtime stops. That agent has no guidelines, and you cannot set a perceived-performance policy on it.

Run the Parlant server from the band-parlant project, which has parlant installed and your OpenAI key in .env:

import asyncio
import parlant.sdk as p
from dotenv import load_dotenv
async def main() -> None:
    load_dotenv()
    async with p.Server(nlp_service=p.NLPServices.openai) as server:
        agent = await server.create_agent(
            name="Support Agent",
            description="You are a support assistant. Give specific, accurate answers.",
            perceived_performance_policy=p.NullPerceivedPerformancePolicy(),
        )
        await agent.create_guideline(
            condition="The customer asks a question or needs help",
            action="Answer the question directly, then ask whether anything else is unclear",
        )
        print(f"PARLANT_AGENT_ID={agent.id}")
if __name__ == "__main__":
    asyncio.run(main())

uv run parlant_server.py

The script prints Parlant’s banner and then PARLANT_AGENT_ID=<id>. The async with block only configures the agent: Parlant starts serving on http://localhost:8800 when the block exits, and the process then blocks until you stop it. Port 8800 stays closed until the log shows Server is ready to accept requests., so wait for that line before starting the TypeScript client below. Keep the server running.

In another terminal, create the TypeScript project:

mkdir band-parlant-ts && cd band-parlant-ts
npm init -y && npm pkg set type=module
npm install @band-ai/sdk@0.6.0 parlant-client
npm install -D tsx

parlant-client is an optional peer dependency of @band-ai/sdk (>=3.2.0), so install it yourself. Copy the agent_config.yaml you created into band-parlant-ts.

import { Agent, ParlantAdapter, loadAgentConfig } from "@band-ai/sdk";
const adapter = new ParlantAdapter({
  environment: process.env.PARLANT_ENVIRONMENT ?? "http://localhost:8800",
  agentId: process.env.PARLANT_AGENT_ID ?? "",
});
const agent = Agent.create({
  adapter,
  config: loadAgentConfig("my_agent"),
  agentConfig: { autoSubscribeExistingRooms: true },
});
await agent.run();

environment is the Parlant server’s URL and agentId is the Parlant agent’s ID. Passing systemPrompt or customSection together with agentId throws a ValidationError, because the adapter does not change an existing Parlant agent. Run it with the ID the server script printed:

PARLANT_AGENT_ID=<id> npx tsx agent.ts

The TypeScript SDK logs nothing by default, and the process keeps running until you press Ctrl+C. Mention the agent in a room as in Test in a Room. The TypeScript adapter waits responseTimeoutSeconds, default 120, for each reply.

Limits and Gotchas

Next Steps