Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.bolna.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

Graph agents support two kinds of tools (call transfer and custom HTTP) and an optional per-node retrieval-augmented generation (RAG) hook. Tools are defined globally in api_tools and referenced by name in node prompts. RAG is configured per node and only fires when the conversation is on that node.

​
Call transfer

Define the transfer tool once in api_tools.tools and api_tools.tools_params: 
{
  "key": "transfer_call",
  "name": "transfer_call_main",
  "description": "Use when the customer requests a human agent.",
  "pre_call_message": "Transferring you now, please hold..."
}

{
  "tools_params": {
    "transfer_call_main": {
      "url": null,
      "param": {
        "call_sid": "%(call_sid)s",
        "call_transfer_number": "+91XXXXXXXXXX"
      },
      "method": "POST"
    }
  }
}
On the transfer node, set function_call to force the response LLM to pick this tool when the node is entered: 
{
  "id": "transfer",
  "prompt": "Transfer the call to a human agent.",
  "function_call": "transfer_call_main",
  "edges": []
}
function_call sets the response LLM’s tool_choice to the named tool. The LLM still emits the call; the framework doesn’t auto-invoke it.

​
Custom API tools

Define a tool the LLM can call mid-conversation, e.g. to look up an order: 
{
  "key": "custom_task",
  "name": "fetch_order_status",
  "description": "Fetch order status using the customer's order ID.",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string", "description": "Customer order ID" }
    }
  },
  "pre_call_message": "Just a moment, let me check that..."
}

{
  "tools_params": {
    "fetch_order_status": {
      "url": "https://your-api.example.com/order/status",
      "param": { "order_id": "%(order_id)s" },
      "method": "POST",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}
Reference the tool from a node prompt with the @ prefix: 
Call @fetch_order_status with the [order_id] collected earlier.
Only define tools you actually use. Every tool is visible to the LLM as a callable function, and unused tools increase the chance of accidental invocations.

​
Per-node RAG

Any node can attach its own knowledge base. When the conversation is on that node, the latest user message is used to retrieve relevant chunks from the configured vector store, and they are injected into the system prompt before the response LLM runs. 
{
  "id": "policy_questions",
  "prompt": "Answer the customer's policy question using the knowledge base.",
  "rag_config": {
    "vector_store": {
      "provider_config": { "vector_id": "policies_v1" }
    },
    "similarity_top_k": 10,
    "temperature": 0.7,
    "model": "gpt-4o",
    "max_tokens": 150
  },
  "edges": [
    { "to_node_id": "closing", "condition": "Customer is satisfied" }
  ]
}
If the retrieval call fails, the node still responds, just without retrieved context. The error is logged but never raised to the caller.
Only configure rag_config on nodes that actually need it. Every retrieval call adds latency, so a node that doesn’t need a knowledge base shouldn’t pay for one.