Add curl_hook for external HTTP endpoint integration in Pipecat Flows

[Copilot]

Enables external HTTP API calls from conversation templates without code changes. Merchants can now integrate with webhooks, CRMs, and custom backends directly via JSON configuration.

Implementation

• CurlHook class (hooks.py +142 lines)

  • Supports GET, POST, PUT, PATCH, DELETE
  • Configurable URL, method, headers, body, timeout
  • Static values and LLM-inferred data via HookFieldConfig
  • Async execution using context.aiohttp_session
  • Comprehensive error handling and logging

• Field Sources

  • static: Fixed values in template (URLs, tokens, structure)
  • llm: Dynamic values from conversation (reasons, addresses, notes)
  • Template variables: {customer_id} substituted at load time

Usage

{
  "function_name": "confirm_order",
  "hooks": [{
    "name": "curl_hook",
    "expected_fields": {
      "url": {"source": "static", "value": "https://api.merchant.com/orders"},
      "method": {"source": "static", "value": "POST"},
      "body": {"source": "static", "value": {"order_id": "{order_id}"}},
      "cancellation_reason": {"source": "llm"}
    }
  }]
}

Deliverables

• Core implementation in existing hook system
• Comprehensive documentation (24k+ words)
• Template examples (basic + real-world order confirmation)
• Verification script and unit tests
• Security: 0 vulnerabilities (CodeQL)

Architecture Notes

Follows existing async hook pattern: conversation transitions are synchronous while hooks execute fire-and-forget. This prevents external API latency from blocking the voice flow.

Original prompt

Pipecat Flows Deep Dive: Architecture & Breeze Buddy Integration
This document explains the architecture of Pipecat Flows and how it is implemented within the Breeze Buddy voice agent.

1. Core Concepts of Pipecat Flows
   Pipecat Flows is a framework for building structured, state-based conversations for AI voice agents. Instead of a single, massive prompt, the conversation is broken down into manageable steps called Nodes.

The Node (The State)
A Node represents a specific state in the conversation (e.g., "Greeting", "Collecting Order", "Confirming Address"). Each node defines:

What the AI should do (Task Messages).
What tools are available (Functions).
What happens before/after (Actions).
Messages
Messages drive the LLM's behavior within a node.

role_messages: Define the persona and general behavior (e.g., "You are a helpful assistant for a pizza shop. Be polite and concise."). These are usually set once at the start.
task_messages: Define the specific objective for the current node (e.g., "Ask the user for their delivery address."). These change as the user moves from node to node.
Functions (The Tools)
Functions allow the LLM to interact with the outside world and transition to new nodes.

Example: A function record_address(address) might save the address to a database and then return the confirm_address node as the next step.
Flow Control: The LLM decides when to call a function based on the conversation. The function's return value determines where the conversation goes next.
Actions
Actions are deterministic code blocks that run automatically at specific times.

pre_actions: Run immediately when entering a node, before the LLM generates a response. (e.g., "Play a 'typing' sound effect").
post_actions: Run after the LLM has finished speaking. (e.g., "Hang up the call").
Flow Manager (The Engine)
The FlowManager is the central orchestrator. It:

Maintains the current state (current node).
Updates the LLM's context (messages + tools).
Executes actions.
Handles function calls and transitions to new nodes.
2. Breeze Buddy Implementation Breakdown
Breeze Buddy uses a Dynamic Flow pattern, meaning the conversation structure isn't hardcoded in Python files but is loaded from a database.

manager.py (The Engine)
Location: venv/lib/python3.13/site-packages/pipecat_flows/manager.py (Library Code)
Role: This is the generic engine provided by the pipecat-flows library. It knows how to run a flow but knows nothing about your specific flow (orders, merchants, etc.).
Responsibility: It handles the low-level mechanics: "I am in Node A. The LLM called Function X. Function X returned Node B. Now I switch to Node B."
loader.py (The Fetcher)
Location: app/ai/voice/agents/breeze_buddy/template/loader.py
Role: The bridge between the database and the application.
Responsibility: It fetches the JSON representation of the flow from the database based on the merchant_id and template_name.
Analogy: It's like opening a script file for a play.
builder.py (The Translator)
Location: app/ai/voice/agents/breeze_buddy/template/builder.py
Role: The translator that converts the raw JSON data into executable Python objects (NodeConfig).
Responsibility: This is where the Business Logic lives.
The JSON might say: "handler": "check_order_status".
The builder.py maps that string to the actual Python function check_order_status() defined in the codebase.
It constructs the NodeConfig dictionary that manager.py expects.
3. The "Dynamic Flow" Pattern
Breeze Buddy uses Dynamic Flows to allow for flexibility. Different merchants can have different conversation flows without changing the code.

Why Dynamic?
Configurability: A merchant can change their script (e.g., add a "Upsell" step) by updating the JSON in the database, without redeploying the backend code.
Scale: One codebase can support thousands of different conversation structures.
The Lifecycle
Database: Stores the Flow definition as JSON.
loader.py: Fetches the JSON when a call starts.
builder.py: Iterates through the JSON nodes.
It looks up the actual Python functions for any "handlers" mentioned in the JSON.
It assembles a valid NodeConfig object.
manager.py: Receives the initial NodeConfig and starts the conversation.
Live Conversation:
User speaks -> STT -> LLM.
LLM decides to call a function (e.g., confirm_order).
manager.py executes the Python function mapped by builder.py.
The function returns the next node (e.g., goodbye).
manager.py updates the state to goodbye.
4. Visual Flow Diagram
Mermaid
graph TD
subgraph "Data Layer"
DB[(Database)]
JSON[Flow JSON Template]
end

subgraph "Application Layer (Breeze Buddy)"
    Loader[loader.py]
    Builder[builder.py]
    Funcs[Python Functions<br/>(check_order, etc.)]
end

subgraph "Library Layer (Pipecat Flows)"
    Manager[manager.py<br/>(FlowManager)]
    LLM[LLM Service]
end

DB -->|Fetch Template| Loader
Loader -->|Raw JSON| Builder
Funcs -.->|Map Strings to Code|...

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.