✨ Add ConciergeRouter for multi-agent orchestration with example assistants

[sergio-sanchezo]

🧠 Overview

This PR introduces a new ConciergeRouter to the Celai platform, enabling multi-agent orchestration via dynamic assistant selection and runtime transfers. This router intelligently decides which sub-agent should respond based on conversation context, while also allowing agents to request control transfers mid-dialogue. Additionally, this PR includes a runnable demo with two example agents showcasing how to use this orchestration pattern.

---

📂 Key Additions

Concierge Agent

cel/assistants/router/concierge_agent.py

• Implements the ConciergeRouter class, extending AgenticRouter.
• Injects a request_transfer tool into all sub-agents to allow dynamic role switching during a session.
• Maintains state per session:
  • active_agent: controls which agent is currently handling the conversation.
  • transfer_requested: flag that triggers an immediate rerouting of the message.
• Uses an LLM (default: GPT-4o) to infer the best agent from a list, given the recent conversation history.
• Includes transfer logic that retries routing up to MAX_TRANSFER_PER_TURN times per message to avoid loops.

examples/19_concierge_router_experimental/assistant.py

• A runnable demo assistant that integrates:
  • ConciergeRouter as the main orchestrator.
  • TelegramConnector for user interaction.
  • Two sub-agents: Balance Agent and Transfer Agent.

examples/19_concierge_router_experimental/balance_agent.py & transfer_agent.py

• Define two simple example agents:
  • Balance Agent for handling account balance inquiries.
  • Transfer Agent for managing money transfers.
• Both are implemented using MacawAssistant and include descriptive prompts for routing.

Agentic Router improvement

cel/assistants/router/agentic_router.py

• Improves the agent selection prompt in AgenticRouter by including both the name and description of each assistant.

---

✅ Features

• ✨ Multi-agent orchestration with stateful routing.
• 🔁 Mid-conversation transfer support via injected tools.
• 🧠 LLM-powered assistant selection using conversation context.
• 📦 Clean integration with existing Celai architecture and state stores.
• 🧪 Example ready-to-run

---

🧪 Usage

cd examples/19_concierge_router_experimental
python assistant.py

Requires environment variables:

• TELEGRAM_TOKEN
• OPENAI_API_KEY
• (Optional) WEBHOOK_URL

---

ℹ️ Notes

• ConciergeRouter is backward-compatible with existing AgenticRouter usage.
• The routing logic is fully observable via logs and LangSmith tracing.
• Ideal for use cases where assistant responsibilities are clearly segmented and may need to be switched dynamically during a session.