Ground a voice AI agent in your documents

AI AgentsRAG for voice AI

Connect a voice AI agent to your documents so it retrieves relevant content before answering.

datasphererag

The claim

Datasphere is SignalWire’s hosted document store: upload PDFs, Word files or Markdown, it chunks and embeds them, and POST /api/datasphere/documents/search returns the passages closest to a query. This agent has one tool, search_docs, which runs that search restricted to the documents tagged for it and hands the passages back as the tool’s response. The retrieval is the platform’s; the boundary is the tag; the code is thirty lines.

Why it holds

What this does not prove: that the model will never answer from its own knowledge. Search evidence cannot enforce a behavioural guarantee; the prompt asks for it and the tool makes it the path of least resistance. Structural constraints on what the model can do are the governance recipes (scope-tools-per-step, require-verification-before-unlocking-tools).

How it works

res = client.datasphere.documents.search(query_string=query, tags=["product-docs"], count=3)
passages = [c["text"] for c in res["chunks"]]
return FunctionResult("Relevant documentation:\n\n" + "\n\n".join(f"- {p}" for p in passages))

The request body (query_string, tags, count, and also distance, language, pos_to_expand, max_synonyms) is the documented Datasphere search API; tags is what scopes the corpus. An empty result returns an explicit “not covered” response rather than nothing, so the model has something truthful to say.

Alternatives with the same shape: the SDK’s datasphere skill (webhook) or datasphere_serverless skill (a DataMap, no server of yours), and native_vector_search for a local .swsearch index with no hosted store.

What to change first

Give two agents two tags over one Datasphere project, a sales corpus and a support corpus, and confirm neither can retrieve the other’s documents.

Where this sits

Before this

Give a voice AI agent a tool

Let a voice AI agent call an API without your server

Write a reusable AI agent skill

Seen in a build

One of 10 recipes composed by Embed a state-aware voice agent in your web page.

python/app.py

"""Ground an agent in your docs.

`search_docs` is a SWAIG tool that queries Datasphere - SignalWire's hosted
document store with chunking and vector search - restricted to the documents
tagged for this agent. The model receives matching passages, and nothing else.

Upload documents (PDF, DOCX, Markdown, ...) in the Dashboard under Datasphere,
or with `POST /api/datasphere/documents`, and tag them; the tag is the corpus
boundary here.

Written against signalwire-sdk 3.0.1 (RestClient.datasphere).
"""
import os

from dotenv import load_dotenv
from signalwire import AgentBase, FunctionResult
from signalwire.rest import RestClient

# the SDK does not read .env for you
load_dotenv()

CORPUS_TAGS = os.getenv("DATASPHERE_TAGS", "product-docs").split(",")
TOP_K = int(os.getenv("DATASPHERE_COUNT", "3"))


def search(client, query, tags=CORPUS_TAGS, count=TOP_K):
    """Return the matching passages, most relevant first."""
    res = client.datasphere.documents.search(query_string=query, tags=tags, count=count)
    return [c.get("text") or c.get("content", "") for c in res.get("chunks", [])]


class DocsAgent(AgentBase):
    def __init__(self, client=None):
        super().__init__(name="docs", route="/docs")
        self.client = client or RestClient()
        self.prompt_add_section(
            "Role",
            "You answer questions about our product from the documentation. For "
            "every question, call search_docs first and answer from the passages "
            "it returns. If nothing relevant comes back, say the documentation "
            "does not cover it.",
        )

    @AgentBase.tool(
        name="search_docs",
        description="Search the product documentation for passages on a question",
        parameters={"query": {"type": "string",
                              "description": "What the caller wants to know"}},
    )
    def search_docs(self, args, raw_data):
        query = (args.get("query") or "").strip()
        if not query:
            return FunctionResult("I need a question to search for.")
        passages = search(self.client, query)
        if not passages:
            return FunctionResult("No relevant documentation was found for that.")
        body = "\n\n".join(f"- {p}" for p in passages)
        return FunctionResult("Relevant documentation:\n\n" + body)


if __name__ == "__main__":
    DocsAgent().serve(port=int(os.getenv("PORT", "8080")))

Run it

1. In the Dashboard, open Datasphere, upload your documents and tag them product-docs (or set DATASPHERE_TAGS). 2. ``bash cd python pip install -r requirements.txt SIGNALWIRE_SPACE=... SIGNALWIRE_PROJECT_ID=... SIGNALWIRE_API_TOKEN=... python app.py ` 3. Point a phone number’s SWML webhook at https://<user>:<password>@<your-host>/docs/, using the credentials from your .env`.

Verify it

python verify.py          # from the recipe folder, not python/

It replaces the REST client’s HTTP layer with a recorder and runs the tool. The verifier then asserts:

one POST to /api/datasphere/documents/search
a body that is a documented search request carrying exactly the corpus tags, checked against tools/openapi/rest.json
the response text is the returned passages
an empty result says so

Report an issue