Agents

Agents

In Parlant, think of an agent as a specialized AI personality crafted for a specific service role. Agents form the basic unit of conversational customization—all behavioral configurations are made at the agent level.

A single Parlant server can host multiple agents, each with distinct roles and personalities. For example:

• Hexon: Technical Support specialist
• Sprocket: Customer Success experts
• Piston: Pre-Sales consultant

Creating a new agent

CLI

$ parlant agent create \
    --name "Hexon" \
    --description "Technical support specialist"

Python

from parlant.client import ParlantClient

client = ParlantClient(base_url=SERVER_ADDRESS)

agent = client.agents.create(
    name="Scooby",
    description="Technical support specialist",
)

TypeScript

import { ParlantClient } from 'parlant-client';

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

const agent = await client.agents.create({
    name: "Scooby",
    description: "Technical support specialist",
});

Each agent can be uniquely configured with its own style, demeanor, and interaction patterns tailored to its target users. More importantly, different business units can own and maintain specific agents. For example:

• IT Department manages Hexon
• Customer Success team oversees Sprocket
• Sales/Marketing controls Piston

This agent-based architecture creates natural boundaries for separation of concerns within Parlant

tip

To learn more about how to structure a development team to craft and ship high-quality agents, read about our recommended best practices on the Development Process page.

Crafting an Agent's Identity

Imagine you're creating a new employee who will become the voice of your service. Just as you'd carefully consider the personality and approach of a human hire, crafting an agent's identity requires thoughtful consideration of its core characteristics—and like any good hire, it can grow and adapt based on real-world interactions.

Let's follow the evolution of Hexon, our technical support specialist. In its first iteration, we might simply define it as "a technical support agent who helps users solve technical problems professionally and efficiently." After observing some interactions, we might notice it comes across as too mechanical, missing opportunities to build user confidence.

So we refine its identity:

"A technical support specialist who combines deep technical knowledge with patient explanation. You take pride in making complex concepts accessible without oversimplifying them. While you're always professional, you communicate with a warm, approachable tone. You believe that every technical issue is an opportunity to help users better understand their tools. When users are frustrated, you remain calm and empathetic, acknowledging their challenges while focusing on solutions."

As we observe more interactions, we might further refine this identity. Perhaps we notice users respond better when Hexon shows more personality, or maybe we find certain technical discussions need more gravitas. The identity can evolve with these insights.

Consider another example with Sprocket, our customer success agent. Its initial identity might focus purely on product knowledge, but after seeing real customer interactions, we might realize the need for a more nuanced approach:

"A customer success expert who believes in the power of proactive support. You're naturally enthusiastic about helping customers maximize value from our platform, but you temper this enthusiasm with careful attention to each customer's pace and preferences. You have a collaborative mindset, seeing yourself as a partner in the customer's journey rather than just a support resource. While you're always eager to showcase new features, you prioritize understanding and addressing the customer's immediate needs first."

The key is to start with a solid foundation but remain open to refinement based on real interactions. Watch how users respond, gather feedback from stakeholders, and adjust the identity accordingly. Maybe Sprocket needs to be more assertive with feature recommendations, or perhaps it needs to be more patient with technical explanations. Each interaction provides insights that can help you refine the agent's core character.

Remember, this identity text will be present in every interaction, so while it should capture essential aspects of the agent's personality, it can and should evolve as you learn what works best for your users. Think of it as an ongoing dialogue between your vision for the agent and the practical reality of user interactions.

note

Parlant gives you multiple elements with which you can shape the conversational experiences. To learn about their differences and when to use each one, check out this comparison.

API Highlights

Retrieving an agent

CLI

$ parlant agent view --id AGENT_ID

Python

from parlant.client import ParlantClient

client = ParlantClient(base_url=SERVER_ADDRESS)

agent = client.agents.retrieve(AGENT_ID);

TypeScript

import { ParlantClient } from 'parlant-client';

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

const agent = await client.agents.retrieve(AGENT_ID)

Updating an agent

CLI

$ parlant agent update \
    --id AGENT_ID \
    --name "Hexon" \
    --description "Technical support specialist"

Python

from parlant.client import ParlantClient

client = ParlantClient(base_url=SERVER_ADDRESS)

client.agents.update(
    AGENT_ID,
    name="Scooby",
    description="Technical support specialist",
)

TypeScript

import { ParlantClient } from 'parlant-client';

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

await client.agents.update(AGENT_ID, {
    name: "Scooby",
    description: "Technical support specialist",
});

Listing agents

CLI

$ parlant agent list

Python

from parlant.client import ParlantClient

client = ParlantClient(base_url=SERVER_ADDRESS)

agents = client.agents.list()

TypeScript

import { ParlantClient } from 'parlant-client';

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

const agents = await client.agents.list();