Agent Registry

Route inbound WhatsApp/SMS messages to a specific agent by phone number

Assign each of your agents a phone number, drop them in a registry, and the gateway dispatches every inbound WhatsApp/SMS message to the right agent.

from praisonaiagents import Agent
from praisonai_bot.bots import AgentRegistry

support = Agent(name="support", instructions="Help customers with product issues.")
sales   = Agent(name="sales",   instructions="Answer pricing and demo questions.")

registry = AgentRegistry(default_agent=support)
registry.assign("[phone]", support)
registry.assign("[phone]",    sales)

# The gateway calls this for every inbound message
agent = registry.resolve("[phone]")  # → support

Users experience it as three separate helplines backed by one gateway:

User texts	Number	Routed to	Reply
Alice: “my order hasn’t arrived”	[phone]	support agent	Shipment lookup
Bob: “what does the Pro plan cost?”	[phone]	sales agent	Pricing answer
Priya: brand-new number	never seen before	triage default agent	”Who are you trying to reach?”

Quick Start

1. Enable with a single agent

   One number, one agent. Normalisation means the formatting you assign with does not have to match the inbound format.

   from praisonaiagents import Agent
   from praisonai_bot.bots import AgentRegistry
   
   agent = Agent(name="support", instructions="Be helpful.")
   
   registry = AgentRegistry()
   registry.assign("[phone]", agent)
   
   registry.resolve("[phone]")  # → agent  (normalisation matches)
   
2. Multiple agents, multiple numbers

   Add a default_agent so unknown numbers still get answered.

   from praisonaiagents import Agent
   from praisonai_bot.bots import AgentRegistry
   
   support = Agent(name="support", instructions="Product help.")
   sales   = Agent(name="sales",   instructions="Pricing and demos.")
   triage  = Agent(name="triage",  instructions="Greet new callers and route them.")
   
   registry = AgentRegistry(default_agent=triage)
   registry.assign("[phone]", support)
   registry.assign("[phone]", sales)
   
   registry.resolve("[phone]")     # → support
   registry.resolve("[phone]")  # → triage (fallback)
   
3. Wire it into a WhatsApp bot

   A real gateway calls registry.resolve(inbound_number) on every message, then hands the chat to the chosen agent. See WhatsApp Bot for the full bot setup.

   from praisonai_bot.bots import AgentRegistry
   
   registry = AgentRegistry(default_agent=triage)
   registry.assign("[phone]", support)
   registry.assign("[phone]", sales)
   
   async def on_inbound(webhook):
       # `to_number` is the WhatsApp business number the user messaged
       agent = registry.resolve(webhook["to_number"])
       reply = await agent.chat(webhook["text"])
       return reply
   

---

How It Works

The gateway resolves the destination number to an agent, runs the chat, and replies on the same channel.

Step	What happens
Webhook	The inbound message carries the business number the user texted (to_number)
Resolve	registry.resolve(to_number) returns the assigned agent, the default_agent, or None
Chat	The gateway runs the chosen agent with the user’s text
Reply	The response is sent back on the same channel

---

Number Normalisation

"[phone]" and "[phone]" resolve to the same agent because normalize_number strips every non-digit and preserves a single leading +. Blank, non-string, or digit-free inputs normalise to None.

Input	Normalised key
"[phone]"	"[phone]"
"[phone]"	"[phone]"
"14155550123" (no leading +)	"14155550123"
"", " ", None, non-string	None

---

API Reference

AgentRegistry(default_agent=None)

In-memory phone-number → agent routing table. No I/O, no dependencies. Not thread-safe.

Option	Type	Default	Description
default_agent	Any | None	None	Fallback returned by resolve() when the inbound number is unknown or blank. When None, unknown numbers resolve to None.

Methods

Method	Signature	Returns	Description
assign	assign(number: str, agent: Any) -> str	Normalised key (str)	Assign number to agent. Re-assigning replaces the previous agent. Raises ValueError if number normalises to empty.
unassign	unassign(number: str) -> bool	bool	Remove any agent for number. Returns True if a mapping was removed, else False.
resolve	resolve(number: Optional[str]) -> Optional[Any]	Agent or None	Return the agent assigned to number, else default_agent, else None.
numbers	numbers() -> List[str]	List[str]	All assigned (normalised) numbers.
__contains__	number in registry	bool	Membership test using the normalised key.
__len__	len(registry)	int	Number of assigned numbers.
__iter__	for key, agent in registry	Iterator[Tuple[str, Any]]	Iterate (normalised_number, agent) pairs.

normalize_number(number)

normalize_number(number: Optional[str]) -> Optional[str] returns the canonical key, or None when blank / non-string / no digits.

• Strips whitespace and formatting characters (spaces, dashes, parens, dots).
• Preserves a single leading +.

---

AgentRegistry vs ChannelDirectory

Pick by message direction: AgentRegistry routes inbound by phone number; ChannelDirectory routes outbound by target name.

---

Common Patterns

Fallback agent — set a default_agent so unknown numbers are never left unanswered.

from praisonaiagents import Agent
from praisonai_bot.bots import AgentRegistry

triage = Agent(name="triage", instructions="Greet new callers and route them.")
registry = AgentRegistry(default_agent=triage)

registry.resolve("[phone]")  # → triage (no assignment yet)

Dynamic re-assignment — remap or drop a number at runtime.

registry.assign("[phone]", sales)   # move that number to sales
registry.unassign("[phone]")       # take sales off that number
"[phone]" in registry               # → True
len(registry)                            # → 1
list(registry)                           # → [("[phone]", <Agent name='sales'>)]

---

Best Practices

Prefer E.164 numbers

Store numbers as +<country><digits> (E.164). Normalisation still handles human-typed variants like "[phone]", but E.164 is unambiguous and matches what most webhooks send.

Build one registry per process

The registry holds references to already-constructed agents and does no I/O. Create it once at startup and consult it on every inbound message.

Always set a default_agent

Set AgentRegistry(default_agent=triage) if you never want to leave an inbound message unanswered. Without it, unknown numbers resolve to None and the caller must handle that case.

AgentRegistry is not thread-safe

Construct it before your gateway starts and treat it as read-mostly. If you mutate it from multiple threads, add your own lock.

---

Related

WhatsApp Bot

Connect an agent to WhatsApp — Cloud API or Web mode.

Channels Gateway

Route agents across Telegram, Discord, Slack, and WhatsApp.

Messaging Bots

All supported messaging platforms in one place.

Platform-Aware Agents

Outbound routing with ChannelDirectory and ReachableTarget.