Agents

In Parlant, an agent is a single, coherent AI personality; in other words, "the one you talk to."

import parlant.sdk as p

async with p.Server() as server:
    hexon = await server.create_agent(
        name="Hexon",
        description="Technical support specialist"
    )

    # Model the agent's behavior using guidelines, journeys, tools, etc.

Managing multi-topic context

Unlike graph-based frameworks where an agent is a specialized task node, Parlant follows a simpler modeling standpoint where an agent is a complete conversational entity with its own identity, behavioral rules, and tools.

Research on multi-agent system failures shows that splitting into multiple agents often introduces coordination and consistency problems that outweigh the partial modularity benefits.

In Parlant, you don't need sub-agents to manage different topics or tasks. Instead, a single agent dynamically assembles the right context for each moment in the dialogue, applying the relevant guidelines and calling the appropriate tools as needed.

All behavioral configuration—guidelines, journeys, tools, glossary—is scoped to an agent, and a single Parlant server can host an unlimited number of agents.

Crafting Identity

An agent's description sets its general personality and tone. Start simple, then refine based on real interactions:

# First iteration — functional but generic
hexon = await server.create_agent(
    name="Hexon",
    description="A technical support agent who helps users solve problems professionally.",
)

# After observing interactions — more personality, clearer tone
hexon = await server.create_agent(
    name="Hexon",
    description=(
        "A technical support specialist who combines deep technical knowledge "
        "with patient explanation. Makes complex concepts accessible without "
        "oversimplifying. Professional but warm and approachable. When users "
        "are frustrated, remains calm and empathetic while focusing on solutions."
    ),
)

The description gives the agent its overall, baseline orientation. It's always included in the agent's context.

For specific behavioral rules that apply contextually—when to upsell, how to handle complaints, what to say in sensitive moments—use guidelines and canned responses, which participate in context filtering.

Custom IDs

By default, for convenience, Parlant auto-generates agent IDs from the description. This is convenient for development, but means description changes break session linkage. For production, use hardcoded IDs:

hexon = await server.create_agent(
    id="hexon",  # Stable across description changes and deployments
    name="Hexon",
    description="Technical support specialist",
)

Single Agent or Multiple Agents?

A common question: should you split your agent into multiple specialized agents, or keep everything in one?

Parlant's recommendation: model AI agents the way human agents work. If you'd hire one person for the role, use one agent. Users expect a coherent personality that maintains full context throughout the conversation—not one that suddenly forgets what was discussed because it was silently swapped for a different node.

This is practical, not just philosophical. Because Parlant dynamically matches only the relevant guidelines per turn, a single agent can handle complex, multi-topic conversations without losing focus. You don't need to split into multiple agents to manage complexity—the framework handles that for you.

When you do need specialization (e.g., transferring from sales to billing), Parlant supports explicit agent transfers that maintain conversation history and feel natural to the user.

Output Modes

By default, Parlant delivers responses as a single block. For longer responses or voice agents, streaming lets text appear incrementally:

Mode	Behavior	Best for
BLOCK	Full message sent at once (default)	Short responses, strict composition
STREAM	Tokens streamed as generated	Longer responses, voice agents

agent = await server.create_agent(
    name="Hexon",
    description="Technical support specialist",
    output_mode=p.OutputMode.STREAM,
)

Streaming changes only the delivery mechanism. Guideline matching, tool calling, and context assembly all work the same way—only the final message generation streams incrementally instead of buffering.

Streaming and Canned Responses

Streaming is only supported with FLUID composition mode. When a canned response is selected, the agent delivers it as a block regardless of the output mode setting.

Transferring Between Agents

To transfer a customer, update the session's agent ID via the client SDK. This can be called from within a tool, allowing transfers to happen automatically based on conversation context.

Python

from parlant.client import ParlantClient

client = ParlantClient(PARLANT_SERVER_URL)

# Transfer session to a different agent
client.sessions.update(
    session_id=SESSION_ID,
    agent_id="billing_specialist"
)
# Subsequent responses will come from the billing specialist agent

TypeScript

import { ParlantClient } from "parlant-client";

const client = new ParlantClient({ environment: PARLANT_SERVER_URL });

// Transfer session to a different agent
await client.sessions.update(SESSION_ID, {
    agentId: "billing_specialist"
});
// Subsequent responses will come from the billing specialist agent

Preamble Configuration

While Parlant matches guidelines, calls tools, and generates a reply, it sends a short acknowledgment—a preamble—to keep the conversation feeling naturaland responsive.

Think of it as the "Got it, let me check" a human agent would say while looking something up.

By default, Parlant picks from generic preambles like "Hey there" and "Let me check that for you," but you can customize these preambles per agent:

agent = await server.create_agent(
    name="Hexon",
    description="Technical support specialist",
    preamble_config=p.PreambleConfiguration(
        examples=["One moment, please.", "Let me look into that.", "Checking now."],
    ),
)

The examples field replaces the default preamble set for this agent.

Dynamic Preamble Instructions

For more control, provide a get_instructions callable that returns contextual instructions for preamble generation:

async def preamble_instruction_provider(ctx: p.EngineContext) -> Sequence[str]:
    instructions = []

    hour = datetime.now().hour
    if hour < 12:
        instructions.append("Use a morning greeting like 'Good morning'")
    elif hour >= 18:
        instructions.append("Use an evening greeting like 'Good evening'")

    return instructions

agent = await server.create_agent(
    name="Hexon",
    description="Technical support specialist",
    preamble_config=p.PreambleConfiguration(
        examples=["One moment, please", "Let me look into that", "Good morning"],
        get_instructions=preamble_instruction_provider,
    ),
)

Reach out for help