🤝 Guidance-Driven Agent Orchestration

Integrates 🦜Parlant's ARQ (Attentive Reasoning Queries) into 🔷Microsoft Agent Framework via middleware.

Key Features

• Guideline Matching: 🚦Semantic matching with embeddings (cached in .embedding_cache.pkl)
• Journey State Tracking: Conversational flow as state machines
• ARQ Validation: 🛡️ Anchor → Reason → Predict (3-phase validation)
• Context Propagation: Shared state across agent handoffs
• Compliance: Validate responses before delivery ✔️

Installation

uv sync

Quick Start

from core.models import Guideline, Journey, JourneyState, StateType
from middleware.query_gateway import ARQGatewayMiddleware
from agent_framework.azure import AzureOpenAIChatClient

# Define guidelines
guidelines = [
    Guideline(id="g1", condition="Customer frustrated", 
              action="Acknowledge feelings", priority=10)
]

# Create agent with ARQ middleware
agent = chat_client.create_agent(
    name="Agent",
    instructions="Your instructions",
    middleware=[ARQGatewayMiddleware(guidelines=guidelines)]
)

# Run
result = await agent.run("User message")

Utilities

View Embedding Cache:

python view_cache.py  # Shows .embedding_cache.pkl contents

Examples

• demo_simple_arq_validation.py - Basic ARQ validation
• demo_journey_state_tracking.py - Journey state flow
• demo_customer_support_arq.py - Multi-agent support with handoffs
• demo_travel_booking_arq.py - Travel booking workflow (paper example)

Architecture

ARQ Flow: Guideline Matcher → Journey Manager → ARQ Generator → Agent Executor
Middleware: Non-invasive integration via AgentMiddleware
Cache: Embeddings stored in .embedding_cache.pkl (persistent)

References

ARQ (Attentive Reasoning Queries) are prompts designed to guide an AI to think step-by-step, focus on key details, and produce accurate, logically grounded answers by directing its attention.

• ARQ Paper - Attentive Reasoning Queries
• Parlant - Original ARQ implementation
• Microsoft Agent Framework