Skip to main content
Async-safe RAG for agents running under arun or a FastAPI handler — knowledge search never blocks the event loop.

Quick Start

1

Agent under arun

An agent that searches knowledge inside arun() no longer blocks the event loop — concurrent requests stay responsive.
2

Orchestrator (library authors)

Call aretrieve_knowledge / aadd_knowledge directly when you build on the persistence layer.

How It Works

aretrieve_knowledge and aadd_knowledge inspect the underlying store and pick the right path automatically. Every real vector backend issues a network round trip on search. From an async agent, the sync retrieve_knowledge would block the loop for the whole round trip and serialise every other concurrent request. The a* methods align RAG with the existing async conversation hooks (aon_message, aon_agent_start).

When to Use a* vs Sync

Use the a* variants whenever an event loop is running. In a plain sync script, the existing retrieve_knowledge / add_knowledge methods are the right choice.

Configuration Options

aretrieve_knowledge(query_embedding, collection="default", limit=5, filters=None) aadd_knowledge(documents, collection="default")

Best Practices

Any code path that already runs on an event loop — agent.arun(...), a FastAPI route, a background async task — should call aretrieve_knowledge / aadd_knowledge. The sync methods would block the loop for the full network round trip.
A sync knowledge store plugged into an async agent is not rejected — it is offloaded to a thread via asyncio.to_thread(...). You do not need a native async backend to benefit.
Two concurrent RAG calls against a store with a 0.3 s round trip finish in ~0.3 s, not 0.6 s. Fire two aretrieve_knowledge calls with asyncio.gather and confirm they overlap.

Async Conversation Store

Sibling async hooks (aon_message, aon_agent_start).

Persistence Overview

Where knowledge stores are configured.

RAG Module

The full RAG pipeline.