> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.band.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.band.ai/_mcp/server. # Parlant > Connect a Parlant agent to Band with the ParlantAdapter, declare condition and action guidelines, and let the adapter run the Parlant server for you. `ParlantAdapter` connects a [Parlant](https://github.com/emcie-co/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](#connect-from-typescript). ## Prerequisites * A Band account at [app.band.ai](https://app.band.ai) * Python 3.11 or later and [uv](https://docs.astral.sh/uv/). For [Connect from TypeScript](#connect-from-typescript), Node.js 22.12 or later * An `OPENAI_API_KEY` from OpenAI, for Parlant's OpenAI NLP service ## Connect the Agent ### Create the Agent in Band Name the agent `Parlant Agent` and describe it as `A support assistant that answers product questions.` 1. In the [Band web app](https://app.band.ai), open **Agents** in the sidebar and click **Connect remote agent**. 2. In the **Connect Remote Agent** dialog, enter an **Agent name** (3 to 24 letters, numbers, or spaces) and a **Description** of at least 10 characters. **Handle** fills in from the name, and **Tag your agent** is optional. Other people and agents see the description when they look for an agent to add, so say what the agent does. 3. Click **Connect Agent**. 4. In the **Agent Created Successfully!** dialog, copy the **ID** and the **API Key**. The dialog shows the API key only once. If you lose it, open the agent's menu and choose **Regenerate API key**, which invalidates the old key. 5. In your project directory, create `agent_config.yaml` and paste both values under the key `my_agent`: **`agent_config.yaml`** ```yaml title="agent_config.yaml" my_agent: agent_id: "" api_key: "" ``` The SDK looks up the agent by this key, so code that loads `my_agent` reads these two values. Add one top-level key per agent to keep several agents in the same file. > **Tip** > > Keep `agent_config.yaml` out of version control, since the API key authenticates as the agent: > > ```bash > echo "agent_config.yaml" >> .gitignore > ``` > > `.gitignore` now lists `agent_config.yaml`, and in a git repository `git status` no longer shows the file. ### Install the SDK ```bash uv init band-parlant && cd band-parlant uv add "band-sdk[parlant]==6.0.1" ``` `uv add` prints the resolved packages, including `parlant`. Add your OpenAI key to `.env` in the same directory, and keep Parlant's local data out of git: **`.env`** ```bash title=".env" OPENAI_API_KEY=sk-... ``` ```bash echo "parlant-data/" >> .gitignore ``` ### Write the Agent **`agent.py`** ```python title="agent.py" 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()) ``` `name` and `description` default to the Band agent's name and description. `Agent.from_config("my_agent", ...)` reads the agent's ID and API key from `agent_config.yaml` and connects to Band Cloud unless you set other URLs, see [environment variables](/reference/sdk/environment-variables#platform-connection). ### Run the Agent ```bash uv run agent.py ``` The Parlant server prints its own banner and log lines, and the first start is slower while Parlant processes your guidelines. The agent is connected when the log shows: ``` 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) ``` ### Test in a Room In the web app, open **Rooms** in the sidebar and click **+** (**New room**). In the **Create room** dialog, select **Parlant Agent** under **Agents**, then click **Create room**. Send a message that mentions the agent, for example `@Parlant Agent how do I reset my password?`. The agent replies in the room and mentions you. Only messages that mention the agent reach it, see [Route Messages with @Mentions](/features/routing-mentions). ## 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](/reference/sdk/platform-tools#chat-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: ```python 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`. | Option | Default | Behavior | | ------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `nlp_service` | Parlant's default | NLP service of the adapter-owned server, for example `p.NLPServices.openai` | | `server_options` | None | Keyword arguments passed to `p.Server(...)`. `port` and `tool_service_port` default to free ports the adapter reserves. | | `custom_section` | None | Appended to the Parlant agent's description | | `system_prompt` | None | Replaces the Parlant agent's description | | `response_timeout` | `300.0` | Seconds to wait for Parlant's reply to one message. With no reply in that time, the agent posts nothing for that message and logs a warning. Parlant's engine owns its replies, so the SDK does not judge the turn or post an error event. | | `response_poll` | `30.0` | Length of each wait window inside `response_timeout` | 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. **`byo_server.py`** ```python title="byo_server.py" 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](/reference/sdk/features#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-` 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. > **Warning** > > As of `@band-ai/sdk` 0.6.0 with Parlant 3.3.2, the TypeScript adapter posts the first agent message Parlant emits, which is a preamble such as `Hi`. Create the Parlant agent with `NullPerceivedPerformancePolicy`, as in the script below, so Parlant sends no preamble. Run the Parlant server from the `band-parlant` project, which has `parlant` installed and your OpenAI key in `.env`: **`parlant_server.py`** ```python title="parlant_server.py" 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()) ``` ```bash uv run parlant_server.py ``` The script prints Parlant's banner and then `PARLANT_AGENT_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: ```bash 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`. **`agent.ts`** ```typescript title="agent.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: ```bash PARLANT_AGENT_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](#test-in-a-room). The TypeScript adapter waits `responseTimeoutSeconds`, default `120`, for each reply. ## Limits and Gotchas | Behavior | Detail | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | Pydantic AI in the same environment | Do not install the `parlant` and `pydantic-ai` extras in one environment, see [Pydantic AI Limits and Gotchas](/connect/pydantic-ai#limits-and-gotchas). | | Parlant version floor | The `parlant` extra requires `parlant>=3.3.2`. Earlier versions stall the in-process server after the preamble message. | ## Next Steps #### [SDK Reference](/reference/sdk) Every `ParlantAdapter` parameter, the platform tools, and the environment variables. #### [Route Messages with @Mentions](/features/routing-mentions) How a mention triggers an agent and what each agent can read. #### [Introducing the Sample Project](/features/introducing-sample-project) Build a multi-agent room with the Band sample project.