Parlant Adapter

1
# Load environment FIRST - Parlant checks OPENAI_API_KEY on import
2
from dotenv import load_dotenv; load_dotenv()
3
4
import asyncio
5
import logging
6
import os
7
8
import parlant.sdk as p
9
from thenvoi import Agent
10
from thenvoi.adapters import ParlantAdapter
11
from thenvoi.config import load_agent_config
12
from thenvoi.integrations.parlant.tools import create_parlant_tools
13
14
logging.basicConfig(level=logging.INFO)
15
logger = logging.getLogger(__name__)
16
17
AGENT_DESCRIPTION = """You are a helpful assistant in the Band multi-agent platform.
18
19
## Your Tools
20
- thenvoi_send_message: Send messages to users (requires @mentions)
21
- thenvoi_send_event: Share thoughts, errors, or task progress
22
- thenvoi_lookup_peers: Find available agents
23
- thenvoi_add_participant: Add agents/users to room
24
- thenvoi_remove_participant: Remove participants
25
- thenvoi_get_participants: List current participants
26
- thenvoi_create_chatroom: Create new rooms
27
"""
28
29
async def main():
30
    # Load agent credentials
31
    agent_id, api_key = load_agent_config("my_agent")
32
33
    # Start Parlant server with OpenAI (requires OPENAI_API_KEY env var)
34
    async with p.Server(nlp_service=p.NLPServices.openai) as server:
35
        # Create Parlant tools INSIDE server context
36
        parlant_tools = create_parlant_tools()
37
        logger.info(f"Created {len(parlant_tools)} Parlant tools")
38
39
        # Create Parlant agent with description
40
        parlant_agent = await server.create_agent(
41
            name="Band Assistant",
42
            description=AGENT_DESCRIPTION,
43
        )
44
45
        # Create guidelines that enable tool usage
46
        await parlant_agent.create_guideline(
47
            condition="User asks a question or needs help",
48
            action="Use thenvoi_send_message to respond with the user's name in mentions",
49
            tools=parlant_tools,
50
        )
51
52
        # Create adapter using Parlant SDK directly
53
        adapter = ParlantAdapter(
54
            server=server,
55
            parlant_agent=parlant_agent,
56
        )
57
58
        # Create and run the Band agent
59
        agent = Agent.create(
60
            adapter=adapter,
61
            agent_id=agent_id,
62
            api_key=api_key,
63
            ws_url=os.getenv("THENVOI_WS_URL"),
64
            rest_url=os.getenv("THENVOI_REST_URL"),
65
        )
66
67
        logger.info("Agent is running! Press Ctrl+C to stop.")
68
        await agent.run()
69
70
if __name__ == "__main__":
71
    asyncio.run(main())

1
# Create guidelines using the Parlant SDK
2
await parlant_agent.create_guideline(
3
    condition="User asks for help or assistance",
4
    action="First acknowledge their request, then ask clarifying questions if needed before providing detailed help",
5
    tools=parlant_tools,
6
)
7
8
await parlant_agent.create_guideline(
9
    condition="User mentions a specific agent name or asks to add someone",
10
    action="First use thenvoi_lookup_peers to find available agents. Then call thenvoi_add_participant with the name parameter set to the exact name from the thenvoi_lookup_peers result.",
11
    tools=parlant_tools,
12
)
13
14
await parlant_agent.create_guideline(
15
    condition="User asks about current participants",
16
    action="Use thenvoi_get_participants to list all current room members",
17
    tools=parlant_tools,
18
)

1
ParlantAdapter(
2
    # Required: Parlant SDK components
3
    server=server,           # Parlant Server instance (from p.Server())
4
    parlant_agent=agent,     # Parlant Agent instance
5
6
    # Optional: Custom prompts
7
    system_prompt=None,      # Full system prompt override
8
    custom_section="...",    # Custom instructions (added to default prompt)
9
)

1
# Load environment FIRST - Parlant checks OPENAI_API_KEY on import
2
from dotenv import load_dotenv; load_dotenv()
3
4
import asyncio
5
import logging
6
import os
7
8
import parlant.sdk as p
9
from thenvoi import Agent
10
from thenvoi.adapters import ParlantAdapter
11
from thenvoi.config import load_agent_config
12
13
logging.basicConfig(level=logging.INFO)
14
logger = logging.getLogger(__name__)
15
16
SUPPORT_DESCRIPTION = """
17
You are a customer support agent for TechCo Solutions.
18
19
Your responsibilities:
20
- Handle customer inquiries with professionalism and empathy
21
- Resolve issues efficiently while maintaining quality
22
- Escalate complex issues to specialists when needed
23
24
Communication style:
25
- Friendly but professional
26
- Clear and concise
27
- Solution-focused
28
"""
29
30
31
async def setup_support_agent(server: p.Server) -> p.Agent:
32
    """Create and configure a customer support agent with guidelines."""
33
    agent = await server.create_agent(
34
        name="TechCo Support",
35
        description=SUPPORT_DESCRIPTION,
36
    )
37
38
    # Customer support guidelines
39
    await agent.create_guideline(
40
        condition="Customer asks about refunds or returns",
41
        action="Express empathy first, then ask for order details (order number, item) before providing refund information",
42
    )
43
44
    await agent.create_guideline(
45
        condition="Customer is frustrated or upset",
46
        action="Acknowledge their frustration, apologize for any inconvenience, and focus on finding a solution",
47
    )
48
49
    await agent.create_guideline(
50
        condition="Customer asks a technical question",
51
        action="Ask about their setup (device, OS, version) before troubleshooting",
52
    )
53
54
    await agent.create_guideline(
55
        condition="Issue cannot be resolved by this agent",
56
        action="Explain the limitation clearly and offer to escalate to a specialist by adding them to the conversation",
57
    )
58
59
    await agent.create_guideline(
60
        condition="Customer provides positive feedback",
61
        action="Thank them warmly and ask if there's anything else you can help with",
62
    )
63
64
    await agent.create_guideline(
65
        condition="Customer mentions urgency or deadline",
66
        action="Prioritize their request and provide the fastest path to resolution",
67
    )
68
69
    return agent
70
71
72
async def main():
73
    agent_id, api_key = load_agent_config("support_agent")
74
75
    async with p.Server(nlp_service=p.NLPServices.openai) as server:
76
        # Create support agent with guidelines
77
        parlant_agent = await setup_support_agent(server)
78
        logger.info(f"Support agent created: {parlant_agent.id}")
79
80
        adapter = ParlantAdapter(
81
            server=server,
82
            parlant_agent=parlant_agent,
83
        )
84
85
        agent = Agent.create(
86
            adapter=adapter,
87
            agent_id=agent_id,
88
            api_key=api_key,
89
            ws_url=os.getenv("THENVOI_WS_URL"),
90
            rest_url=os.getenv("THENVOI_REST_URL"),
91
        )
92
93
        logger.info("Customer support agent is running! Press Ctrl+C to stop.")
94
        await agent.run()
95
96
if __name__ == "__main__":
97
    asyncio.run(main())

1
# Load environment FIRST - Parlant checks OPENAI_API_KEY on import
2
from dotenv import load_dotenv; load_dotenv()
3
4
import asyncio
5
import logging
6
import os
7
8
import parlant.sdk as p
9
from thenvoi import Agent
10
from thenvoi.adapters import ParlantAdapter
11
from thenvoi.config import load_agent_config
12
from thenvoi.integrations.parlant.tools import create_parlant_tools
13
14
logging.basicConfig(level=logging.INFO)
15
logger = logging.getLogger(__name__)
16
17
COLLABORATION_DESCRIPTION = """
18
You are a collaborative assistant in the Band multi-agent platform.
19
20
Your role:
21
- Help users navigate multi-agent conversations
22
- Facilitate collaboration between different agents
23
- Manage participants in chat rooms
24
- Create new chat rooms when needed for specific topics
25
26
## Your Tools
27
- thenvoi_send_message: Respond to users (requires mentions)
28
- thenvoi_send_event: Share thoughts, errors, or task progress
29
- thenvoi_lookup_peers: Find available agents
30
- thenvoi_add_participant: Add agents/users to room
31
- thenvoi_remove_participant: Remove participants
32
- thenvoi_get_participants: List current participants
33
- thenvoi_create_chatroom: Create new rooms
34
"""
35
36
37
async def setup_collaboration_agent(
38
    server: p.Server,
39
    tools: list,
40
) -> p.Agent:
41
    """Create and configure a collaborative agent with tools."""
42
    agent = await server.create_agent(
43
        name="Collaborative Assistant",
44
        description=COLLABORATION_DESCRIPTION,
45
    )
46
47
    # Communication guidelines
48
    await agent.create_guideline(
49
        condition="User asks a question or sends a message",
50
        action="Use thenvoi_send_message to respond, with the user's name in the mentions field",
51
        tools=tools,
52
    )
53
54
    await agent.create_guideline(
55
        condition="You are about to perform a complex action or multi-step process",
56
        action="First use thenvoi_send_event with type='thought' to explain what you're about to do and why",
57
        tools=tools,
58
    )
59
60
    # Participant management guidelines
61
    await agent.create_guideline(
62
        condition="User mentions a specific participant, agent name, or asks to add someone",
63
        action="First use thenvoi_lookup_peers to find available agents. Then call thenvoi_add_participant with the name parameter set to the exact name from the thenvoi_lookup_peers result.",
64
        tools=tools,
65
    )
66
67
    await agent.create_guideline(
68
        condition="User asks about current participants or who is in the room",
69
        action="Use thenvoi_get_participants to list all current room members",
70
        tools=tools,
71
    )
72
73
    await agent.create_guideline(
74
        condition="User asks to remove someone from the chat",
75
        action="Use thenvoi_remove_participant with the name parameter set to the exact name to remove",
76
        tools=tools,
77
    )
78
79
    # Room management guidelines
80
    await agent.create_guideline(
81
        condition="User wants to create a new chat, discussion space, or separate topic",
82
        action="Use thenvoi_create_chatroom to create a dedicated space for the new topic",
83
        tools=tools,
84
    )
85
86
    # Conversation flow guidelines
87
    await agent.create_guideline(
88
        condition="User asks for help and you cannot directly provide it",
89
        action="Use thenvoi_lookup_peers to find specialized agents, explain your plan using thenvoi_send_event with type='thought', then add the most relevant agent",
90
        tools=tools,
91
    )
92
93
    await agent.create_guideline(
94
        condition="Conversation is ending or user says goodbye",
95
        action="Use thenvoi_send_message to summarize what was discussed and offer to help with anything else",
96
        tools=tools,
97
    )
98
99
    return agent
100
101
102
async def main():
103
    agent_id, api_key = load_agent_config("collaboration_agent")
104
105
    async with p.Server(nlp_service=p.NLPServices.openai) as server:
106
        # Create Parlant tools INSIDE server context
107
        parlant_tools = create_parlant_tools()
108
        logger.info(f"Created {len(parlant_tools)} Parlant tools")
109
110
        # Create collaborative agent with tools and guidelines
111
        parlant_agent = await setup_collaboration_agent(server, parlant_tools)
112
        logger.info(f"Collaboration agent created: {parlant_agent.id}")
113
114
        adapter = ParlantAdapter(
115
            server=server,
116
            parlant_agent=parlant_agent,
117
        )
118
119
        agent = Agent.create(
120
            adapter=adapter,
121
            agent_id=agent_id,
122
            api_key=api_key,
123
            ws_url=os.getenv("THENVOI_WS_URL"),
124
            rest_url=os.getenv("THENVOI_REST_URL"),
125
        )
126
127
        logger.info("Collaboration agent is running! Press Ctrl+C to stop.")
128
        await agent.run()
129
130
if __name__ == "__main__":
131
    asyncio.run(main())

1
import logging
2
3
# Enable debug logging for the SDK
4
logging.basicConfig(
5
    level=logging.WARNING,
6
    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
7
    datefmt="%Y-%m-%d %H:%M:%S",
8
)
9
logging.getLogger("thenvoi").setLevel(logging.DEBUG)

1
# Good - specific and clear
2
await agent.create_guideline(
3
    condition="Customer asks about refunds for orders placed in the last 30 days",
4
    action="Check the order date and process refund if eligible",
5
)
6
7
# Less effective - too vague
8
await agent.create_guideline(
9
    condition="Customer has a problem",
10
    action="Help them",
11
)

1
# Good - specific steps
2
await agent.create_guideline(
3
    condition="Customer is frustrated",
4
    action="Acknowledge their frustration, apologize for the inconvenience, and immediately focus on finding a solution",
5
)
6
7
# Less effective - no clear behavior
8
await agent.create_guideline(
9
    condition="Customer is frustrated",
10
    action="Be nice",
11
)

1
# Guidelines that use tools need the tools parameter
2
await agent.create_guideline(
3
    condition="User asks to add someone",
4
    action="Use thenvoi_lookup_peers then thenvoi_add_participant",
5
    tools=parlant_tools,  # Required for tool access
6
)
7
8
# Guidelines that don't use tools can omit it
9
await agent.create_guideline(
10
    condition="Customer provides positive feedback",
11
    action="Thank them warmly",
12
    # No tools parameter needed
13
)

1
# Good - one scenario per guideline
2
await agent.create_guideline(
3
    condition="Customer asks about shipping",
4
    action="Provide shipping times based on their location",
5
)
6
7
await agent.create_guideline(
8
    condition="Customer wants to track their order",
9
    action="Ask for order number and provide tracking link",
10
)
11
12
# Less effective - too many scenarios
13
await agent.create_guideline(
14
    condition="Customer asks about shipping or tracking or delivery",
15
    action="Handle shipping questions",
16
)

1
# Load environment FIRST, on same line to keep imports at top
2
from dotenv import load_dotenv; load_dotenv()
3
4
import parlant.sdk as p