Skip to content

fix(sdk): use ephemeral ports for Parlant servers #341

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
darvell-thenvoi wants to merge 4 commits into
base: main
Choose a base branch
from
Open

fix(sdk): use ephemeral ports for Parlant servers #341

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
58cad3a
fix(sdk): reapply Parlant port after base sync [INT-530]
darvell-thenvoi Jun 3, 2026
7753bb0
fix(sdk): let Parlant choose ephemeral ports [INT-530]
darvell-thenvoi Jun 3, 2026
09479c8
fix(examples): expose Parlant in generic runner [INT-530]
darvell-thenvoi Jun 3, 2026
60f93d3
fix(examples): point Parlant setup at current dev extra [INT-530]
darvell-thenvoi Jun 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -343,8 +343,8 @@ Adapter emit support:
| Gemini | Yes | - | - |
| Google ADK | Yes | - | - |
| Pydantic AI | Yes | - | - |
| Parlant | Yes | - | - |
| LangGraph | Yes | - | - |
| Parlant | - | - | - |
| A2A / A2A Gateway | - | - | - |
| ACP Client | - | - | - |

Expand Down
98 changes: 13 additions & 85 deletions examples/parlant/01_basic_agent.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,7 @@
"""
Basic Parlant agent example using the official Parlant SDK.

This example shows how to create a Band agent using the Parlant SDK
directly, with the full set of Band tools.
This example shows how to create a Band agent using the Parlant SDK directly.

Run with:
uv run examples/parlant/01_basic_agent.py
Expand All @@ -29,90 +28,23 @@
from setup_logging import setup_logging
from band import Agent
from band.adapters import ParlantAdapter
from band.integrations.parlant.tools import create_parlant_tools

setup_logging()
logger = logging.getLogger(__name__)

# Agent description with detailed instructions
AGENT_DESCRIPTION = """You are a helpful, knowledgeable assistant in the Band multi-agent platform.

## Your Tools

1. **band_send_message**: Send messages to users or agents in the chat room. Requires @mentions.
2. **band_send_event**: Share your reasoning ('thought'), report errors ('error'), or progress ('task').
3. **band_lookup_peers**: Find available agents that can help with specific topics.
4. **band_add_participant**: Invite agents or users to the current chat room.
5. **band_remove_participant**: Remove participants from the room.
6. **band_get_participants**: See who's currently in the room.
7. **band_create_chatroom**: Create new rooms for specific discussions.
AGENT_DESCRIPTION = """
You are a helpful, knowledgeable assistant.

## How to Respond

- Give detailed, specific answers to questions
- Remember information the user shares about themselves
- Reference previous parts of the conversation when relevant
- Ask follow-up questions to better understand the user's needs
- Be friendly but substantive - avoid generic or vague responses

## When to Use Tools

- To respond to users: Use band_send_message with their name in mentions
- Before complex actions: Use band_send_event with type='thought' to explain your plan
- If you can't answer something: Use band_lookup_peers to find specialized agents, then band_add_participant
- When asked about the room: Use band_get_participants to see who's here
- For new discussions: Use band_create_chatroom to create a dedicated space
- Be friendly but substantive; avoid generic or vague responses
"""


async def setup_agent_with_guidelines(
server: p.Server,
tools: list,
) -> p.Agent:
"""Create and configure a Parlant agent with basic guidelines and tools."""
agent = await server.create_agent(
name="Parlant",
description=AGENT_DESCRIPTION,
)

# When user asks a question or needs help
await agent.create_guideline(
condition="User asks a question or needs help with something",
action="Analyze the request. If you can answer directly, use band_send_message with the user's name in mentions. If you need to think through a complex problem, first use band_send_event with type='thought' to share your reasoning.",
tools=tools,
)

# When user asks to add someone or wants specialized help
await agent.create_guideline(
condition="User asks to add someone to the chat, mentions a specific agent name, or asks for specialized help you can't provide",
action="First use band_lookup_peers to find available agents. Then IMMEDIATELY call band_add_participant with the name parameter set to the exact name from the band_lookup_peers result. Do NOT ask for confirmation - just add them. If user wants multiple agents, call band_add_participant once for each.",
tools=tools,
)

# When user asks about participants
await agent.create_guideline(
condition="User asks who is in the room, about participants, or who they're talking to",
action="Use band_get_participants to list all current room members",
tools=tools,
)

# When user wants to create a new room
await agent.create_guideline(
condition="User wants to create a new chat room, discussion space, or separate conversation",
action="Use band_create_chatroom to create a dedicated space for the new topic",
tools=tools,
)

# When user asks to remove someone
await agent.create_guideline(
condition="User asks to remove someone from the chat",
action="Use band_remove_participant with the name parameter set to the exact name to remove",
tools=tools,
)

return agent


async def main() -> None:
load_dotenv()

Expand All @@ -124,34 +56,30 @@ async def main() -> None:
if not rest_url:
raise ValueError("BAND_REST_URL environment variable is required")
# Start Parlant server with OpenAI (requires OPENAI_API_KEY env var)
async with p.Server(nlp_service=p.NLPServices.openai) as server:
# Create Parlant tools INSIDE server context
parlant_tools = create_parlant_tools()
logger.info(
"Created %s Parlant tools: %s",
len(parlant_tools),
[t.tool.name for t in parlant_tools],
async with p.Server(
port=0,
tool_service_port=0,
nlp_service=p.NLPServices.openai,
) as server:
parlant_agent = await server.create_agent(
name="Parlant",
description=AGENT_DESCRIPTION,
)

# Create Parlant agent with guidelines and tools
parlant_agent = await setup_agent_with_guidelines(server, parlant_tools)
logger.info("Parlant agent created: %s", parlant_agent.id)

# Create adapter using Parlant SDK directly
adapter = ParlantAdapter(
server=server,
parlant_agent=parlant_agent,
)

# Create and start Band agent
agent = Agent.from_config(
"parlant_agent",
adapter=adapter,
ws_url=ws_url,
rest_url=rest_url,
)

logger.info("Starting Band agent with Parlant SDK (full tools)...")
logger.info("Starting Band agent with Parlant SDK...")
await agent.run()


Expand Down
98 changes: 17 additions & 81 deletions examples/parlant/02_with_guidelines.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
Parlant agent with behavioral guidelines using the official Parlant SDK.

This example shows how to use Parlant's guideline system for controlled
agent behavior with the full Band toolset.
agent behavior while the Band adapter supplies the platform contract and tools.

Run with:
uv run examples/parlant/02_with_guidelines.py
Expand All @@ -29,7 +29,6 @@
from setup_logging import setup_logging
from band import Agent
from band.adapters import ParlantAdapter
from band.integrations.parlant.tools import create_parlant_tools

setup_logging()
logger = logging.getLogger(__name__)
Expand All @@ -40,93 +39,37 @@
## Your Role
- Help users navigate multi-agent conversations
- Facilitate collaboration between different agents
- Manage participants in chat rooms
- Create new chat rooms when needed for specific topics

## Your Tools
- band_send_message: Respond to users (requires mentions)
- band_send_event: Share thoughts, errors, or task progress
- band_lookup_peers: Find available agents
- band_add_participant: Add agents/users to room
- band_remove_participant: Remove participants
- band_get_participants: List current participants
- band_create_chatroom: Create new rooms
- Manage conversations clearly when multiple participants are involved
- Keep responses focused and actionable

## Guidelines
1. Be proactive about suggesting relevant agents to add
1. Be proactive about suggesting relevant specialists when a request is outside your scope
2. Keep responses focused and actionable
3. Always confirm actions taken with the user
4. Use band_send_event with type='thought' before complex actions
3. Be clear about what happened and what still needs attention
4. Ask focused follow-up questions when you need more context
"""


async def setup_agent_with_guidelines(
server: p.Server,
tools: list,
) -> p.Agent:
"""Create and configure a Parlant agent with comprehensive guidelines and tools."""
async def setup_agent_with_guidelines(server: p.Server) -> p.Agent:
"""Create and configure a Parlant agent with comprehensive guidelines."""
agent = await server.create_agent(
name="Parlant",
description=CUSTOM_DESCRIPTION,
)

# Communication guidelines
await agent.create_guideline(
condition="User asks a question or sends a message",
action="Use band_send_message to respond, with the user's name in the mentions field",
tools=tools,
action="Answer concisely and ask a focused follow-up when more context is needed.",
)

await agent.create_guideline(
condition="You are about to perform a complex action or multi-step process",
action="First use band_send_event with type='thought' to explain what you're about to do and why",
tools=tools,
)

# Participant management guidelines
await agent.create_guideline(
condition="User mentions a specific participant, agent name, or asks to add someone",
action="First use band_lookup_peers to find available agents. Then IMMEDIATELY call band_add_participant with the name parameter set to the exact name from the band_lookup_peers result. Do NOT ask for confirmation - just add them. If user wants multiple agents, call band_add_participant once for each.",
tools=tools,
)

await agent.create_guideline(
condition="User asks about current participants or who is in the room",
action="Use band_get_participants to list all current room members",
tools=tools,
)

await agent.create_guideline(
condition="User asks to remove someone from the chat",
action="Use band_remove_participant with the name parameter set to the exact name to remove",
tools=tools,
)

# Room management guidelines
await agent.create_guideline(
condition="User wants to create a new chat, discussion space, or separate topic",
action="Use band_create_chatroom to create a dedicated space for the new topic",
tools=tools,
)

# Error handling guideline
await agent.create_guideline(
condition="An error occurs or something goes wrong",
action="Use band_send_event with type='error' to report the problem, then try to suggest alternatives",
tools=tools,
)

# Conversation flow guidelines
await agent.create_guideline(
condition="User asks for help and you cannot directly provide it",
action="Use band_lookup_peers to find specialized agents, explain your plan using band_send_event with type='thought', then add the most relevant agent",
tools=tools,
action="Explain what kind of specialist would be useful and summarize the context they would need.",
)

await agent.create_guideline(
condition="Conversation is ending or user says goodbye",
action="Use band_send_message to summarize what was discussed and offer to help with anything else",
tools=tools,
action="Close warmly and briefly offer further help.",
)

return agent
Expand All @@ -143,26 +86,19 @@ async def main() -> None:
if not rest_url:
raise ValueError("BAND_REST_URL environment variable is required")
# Start Parlant server with OpenAI
async with p.Server(nlp_service=p.NLPServices.openai) as server:
# Create Parlant tools INSIDE server context
parlant_tools = create_parlant_tools()
logger.info(
"Created %s Parlant tools: %s",
len(parlant_tools),
[t.tool.name for t in parlant_tools],
)

# Create Parlant agent with comprehensive guidelines and tools
parlant_agent = await setup_agent_with_guidelines(server, parlant_tools)
async with p.Server(
port=0,
tool_service_port=0,
nlp_service=p.NLPServices.openai,
) as server:
parlant_agent = await setup_agent_with_guidelines(server)
logger.info("Parlant agent with guidelines created: %s", parlant_agent.id)

# Create adapter using Parlant SDK directly
adapter = ParlantAdapter(
server=server,
parlant_agent=parlant_agent,
)

# Create and start Band agent
agent = Agent.from_config(
"parlant_agent",
adapter=adapter,
Expand Down
24 changes: 13 additions & 11 deletions examples/parlant/03_support_agent.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@
Run with:
uv run examples/parlant/03_support_agent.py

Requires `OPENAI_API_KEY` because this example starts Parlant with OpenAI.

See also: https://github.com/emcie-co/parlant/blob/develop/examples/travel_voice_agent.py
"""

Expand Down Expand Up @@ -62,35 +64,34 @@ async def setup_support_agent(server: p.Server) -> p.Agent:
description=SUPPORT_DESCRIPTION,
)

# Add support-specific guidelines
await agent.create_guideline(
condition="Customer asks about refunds or returns",
action="Express empathy first, then ask for order details (order number, item) before providing refund information",
action="Express empathy first, then ask for order details such as order number and item before providing refund information.",
)

await agent.create_guideline(
condition="Customer is frustrated or upset",
action="Acknowledge their frustration, apologize for any inconvenience, and focus on finding a solution",
action="Acknowledge their frustration, apologize for any inconvenience, and focus on finding a solution.",
)

await agent.create_guideline(
condition="Customer asks a technical question",
action="Ask about their setup (device, OS, version) before troubleshooting",
action="Ask about their setup, including device, operating system, and version, before troubleshooting.",
)

await agent.create_guideline(
condition="Issue cannot be resolved by this agent",
action="Explain the limitation clearly and offer to escalate to a specialist by adding them to the conversation",
action="Summarize the unresolved issue, the customer impact, and the specialist expertise needed.",
)

await agent.create_guideline(
condition="Customer provides positive feedback",
action="Thank them warmly and ask if there's anything else you can help with",
action="Thank them warmly and ask if there's anything else you can help with.",
)

await agent.create_guideline(
condition="Customer mentions urgency or deadline",
action="Prioritize their request and provide the fastest path to resolution",
action="Prioritize their request and provide the fastest path to resolution.",
)

return agent
Expand All @@ -107,18 +108,19 @@ async def main() -> None:
if not rest_url:
raise ValueError("BAND_REST_URL environment variable is required")
# Start Parlant server
async with p.Server(nlp_service=p.NLPServices.openai) as server:
# Create support agent with guidelines
async with p.Server(
port=0,
tool_service_port=0,
nlp_service=p.NLPServices.openai,
) as server:
parlant_agent = await setup_support_agent(server)
logger.info("Support agent created: %s", parlant_agent.id)

# Create adapter using Parlant SDK directly
adapter = ParlantAdapter(
server=server,
parlant_agent=parlant_agent,
)

# Create and start Band agent
agent = Agent.from_config(
"support_agent",
adapter=adapter,
Expand Down
Loading
Loading