A hallucination is a plausible-sounding answer that is wrong or contradicts the relevant retrieved information. In a retrieval-augmented system, the model hallucinates when it answers from internal knowledge instead of treating retrieved documents as authoritative. section 6.3.2
Hallucination is not deliberate deception: the model is producing likely output from whatever information is available. The practical fix is to constrain the task so retrieved context—not the model’s fallback knowledge—controls the answer. section 6.3.2
Use a grounding checklist to reduce hallucinations:
- Tell the agent to answer only from the provided context and to say when the context lacks the answer. section 6.3.2
- Require citations for each claim, including the source document and a quotation. section 6.3.2
- Ask the model to identify relevant passages before writing the answer. section 6.3.2
- Require agents to cite retrieved passages and trace interactions in production systems. section 6.6
A grounded movie-script agent
A RAG agent ingests Back to the Future, splits the script into semantic chunks, stores embeddings in Chroma, and retrieves passages for questions such as where Doc tells Marty to meet and what happens at 1:15 AM. Grounding makes the retrieved script the authority for both answers. section 6.3.2
Listing 6.6 02_RAG_agent_vector.py
script_text = Path("chapter_06/sample_documents/back_to_the_future.txt").read_text(
encoding="utf-8"
)
def simple_chunk(text, max_tokens=200): #1
tokenizer = tiktoken.get_encoding("cl100k_base")
words, chunk, chunks = text.split(), [], []
for w in words:
if len(tokenizer.encode(" ".join(chunk + [w]))) > max_tokens:
chunks.append(" ".join(chunk))
chunk = [w]
else:
chunk.append(w)
if chunk:
chunks.append(" ".join(chunk))
return chunks
docs = simple_chunk(script_text, max_tokens=200)
client = chromadb.PersistentClient( #2
path="./chapter_06/chroma_script_store"
)
collection_name = "bttf_script"
try:
collection = client.get_collection(collection_name) #3
except Exception: #4
collection = client.create_collection(name=collection_name) #4
if collection.count() == 0: #4
collection.add(ids=[str(uuid.uuid4()) for _ in docs], documents=docs)
@function_tool #5
def search_script(query: str, top_k: int = 3) -> str:
res = collection.query(query_texts=[query], n_results=top_k)
if res and "documents" in res and res["documents"] and res["documents"][0]:
return "\n\n".join(res["documents"][0])
return "No relevant documents found."
agent = Agent(
name="Script Agent",
instructions=( #6
"You answer questions about the movie *Back to the Future*.\n" #7
"When needed, call the `search_script` tool to fetch passages, " #7
"then cite or paraphrase them in your answer." #7
"Make sure your answers are grounded in the script text.\n" #7
), #7
tools=[search_script],
)
query = "Where does Doc tell Marty to meet him, and at what time?"
result = Runner.run_sync(agent, query)
print("\n--- ANSWER ---\n", result.final_output)
query = "What happens at 1:15AM" #7
result = Runner.run_sync(agent, query)
print("\n--- ANSWER ---\n", result.final_output)
OUTPUT
--- ANSWER ---
Doc tells Marty to meet him at the Twin Pines Mall parking lot at 1:15 AM.
--- ANSWER ---
There's no specific event or mention of 1:15 AM in the script passages I retrieved. If you have a particular scene or context in mind, let me know, and I can help further! #7
Inspect the working vector-search RAG listing that chunks a script, creates or loads a Chroma collection, and supplies retrieved context to an agent. section 6.3.2
