Generating Multi-Faceted Queries

Consider a RAG system that needs to search through a large database of code examples and tutorials. A user might ask for “Python examples using the chat endpoint” or “JavaScript tutorials for text summarization”.

In a basic RAG setup, these queries would be passed as-is to a search function, potentially missing important context or failing to leverage the structured nature of the data. For example, the code examples database might consist of metadata such as the programming language, the created time, the tech stack used, and so on.

It would be great if we could design a system that could leverage this metadata as a filter to retrieve only the relevant results.

We can achieve this using a tool use approach. Here, we can build a system that generates multi-faceted queries to capture the full intent of a user’s request. This allows for more precise and relevant results by utilizing the semi-structured nature of the data.

Here are some examples of how this approach can be applied:

1. E-commerce product searches: Filtering by price range, category, brand, customer ratings, and availability.
2. Academic research databases: Narrowing results by publication year, field of study, citation count, and peer-review status.
3. Job search platforms: Refining job listings by location, experience level, salary range, and required skills.

In this tutorial, we’ll cover:

• Defining the function for data querying
• Creating the tool for generating multi-faceted queries
• Building an agent for performing multi-faceted queries
• Running the agent

We’ll build an agent that helps developers find relevant code examples and tutorials for using Cohere.

Setup

To get started, first we need to install the cohere library and create a Cohere client.

1
! pip install cohere -qq

1
import json
2
import os
3
import cohere
4
5
co = cohere.ClientV2(
6
    "COHERE_API_KEY"
7
)  # Get your free API key: https://dashboard.cohere.com/api-keys

Defining the function for data querying

We’ll remove the other tools from Part 1 and just use one – search_code_examples.

Now, instead of just the query parameter, we’ll add two more parameters: programming_language and endpoints:

• programming_language: The programming language of the code example or tutorial.
• endpoints: The Cohere endpoints used in the code example or tutorial.

We’ll use these parameters as the metadata to filter the code examples and tutorials.

Let’s rename the function to search_code_examples_detailed to reflect this change.

And as in Part 1, for simplicity, we create query as just a mock parameter and no actual search logic will be performed based on it.

IMPORTANT:

The source code for tool definitions can be found here. Make sure to have the tool_def.py file in the same directory as this notebook for the imports to work correctly.

1
from tool_def import (
2
    search_code_examples_detailed,
3
    search_code_examples_detailed_tool,
4
)

1
functions_map = {
2
    "search_code_examples_detailed": search_code_examples_detailed,
3
}

Creating the tool for generating multi-faceted queries

With the search_code_examples modified, we now need to modify the tool definition as well. Here, we are adding the two new properties to the tool definition:

• programming_language: This is a string property which we provide a list of options for the model to choose from. We do this by adding “Possible enum values” to the description, which in our case is py, js.
• endpoints: We want the model to be able to choose from more than one endpoint, and so here we define an array property. When defining an array property, we need to specify the type of the items in the array using the items key, which in our case is string. We also provide a list of endpoint options for the model to choose from, which is chat, embed, rerank, classify.

We make only the query parameter required, while the other two parameters are optional.

1
tools = [search_code_examples_detailed_tool]

Building an agent for performing multi-faceted queries

Next, let’s create a run_agent function to run the agentic RAG workflow, the same as in Part 1.

The only change we are making here is to make the system message simpler and more specific since the agent now only has one tool.

1
system_message = """## Task and Context
2
You are an assistant who helps developers find code examples and tutorials on using Cohere."""

1
model = "command-a-03-2025"
2
3
4
def run_agent(query, messages=None):
5
    if messages is None:
6
        messages = []
7
8
    if "system" not in {m.get("role") for m in messages}:
9
        messages.append({"role": "system", "content": system_message})
10
11
    # Step 1: get user message
12
    print(f"QUESTION:\n{query}")
13
    print("=" * 50)
14
15
    messages.append({"role": "user", "content": query})
16
17
    # Step 2: Generate tool calls (if any)
18
    response = co.chat(
19
        model=model, messages=messages, tools=tools, temperature=0.3
20
    )
21
22
    while response.message.tool_calls:
23
24
        print("TOOL PLAN:")
25
        print(response.message.tool_plan, "\n")
26
        print("TOOL CALLS:")
27
        for tc in response.message.tool_calls:
28
            print(
29
                f"Tool name: {tc.function.name} | Parameters: {tc.function.arguments}"
30
            )
31
        print("=" * 50)
32
33
        messages.append(
34
            {
35
                "role": "assistant",
36
                "tool_calls": response.message.tool_calls,
37
                "tool_plan": response.message.tool_plan,
38
            }
39
        )
40
41
        # Step 3: Get tool results
42
        for tc in response.message.tool_calls:
43
            tool_result = functions_map[tc.function.name](
44
                **json.loads(tc.function.arguments)
45
            )
46
            tool_content = []
47
            for data in tool_result:
48
                tool_content.append(
49
                    {
50
                        "type": "document",
51
                        "document": {"data": json.dumps(data)},
52
                    }
53
                )
54
                # Optional: add an "id" field in the "document" object, otherwise IDs are auto-generated
55
            messages.append(
56
                {
57
                    "role": "tool",
58
                    "tool_call_id": tc.id,
59
                    "content": tool_content,
60
                }
61
            )
62
63
        # Step 4: Generate response and citations
64
        response = co.chat(
65
            model=model,
66
            messages=messages,
67
            tools=tools,
68
            temperature=0.3,
69
        )
70
71
    messages.append(
72
        {
73
            "role": "assistant",
74
            "content": response.message.content[0].text,
75
        }
76
    )
77
78
    # Print final response
79
    print("RESPONSE:")
80
    print(response.message.content[0].text)
81
    print("=" * 50)
82
83
    # Print citations (if any)
84
    verbose_source = (
85
        False  # Change to True to display the contents of a source
86
    )
87
    if response.message.citations:
88
        print("CITATIONS:\n")
89
        for citation in response.message.citations:
90
            print(
91
                f"Start: {citation.start}| End:{citation.end}| Text:'{citation.text}' "
92
            )
93
            print("Sources:")
94
            for idx, source in enumerate(citation.sources):
95
                print(f"{idx+1}. {source.id}")
96
                if verbose_source:
97
                    print(f"{source.tool_output}")
98
            print("\n")
99
100
    return messages

Running the agent

Let’s start with a broad query about “RAG code examples”.

Since it’s broad, this query shouldn’t require any metadata filtering.

And this is shown by the agent’s response, which provides only one parameter, query, in its tool call.

1
messages = run_agent("Do you have any RAG code examples")
2
# Tool name: search_code_examples | Parameters: {"query":"RAG code examples"}

1
QUESTION:
2
Do you have any RAG code examples
3
==================================================
4
TOOL PLAN:
5
I will search for RAG code examples. 
6
7
TOOL CALLS:
8
Tool name: search_code_examples_detailed | Parameters: {"query":"RAG"}
9
==================================================
10
RESPONSE:
11
I found one code example for RAG with Chat, Embed and Rerank via Pinecone.
12
==================================================
13
CITATIONS:
14
15
Start: 38| End:74| Text:'Chat, Embed and Rerank via Pinecone.' 
16
Sources:
17
1. search_code_examples_detailed_kqa6j5x92e3k:2

Let’s try a more specific query about “javascript tutorials on text summarization”.

This time, the agent uses the programming_language parameter and passed the value js to it.

1
messages = run_agent("Javascript tutorials on summarization")
2
# Tool name: search_code_examples | Parameters: {"programming_language":"js","query":"..."}

1
QUESTION:
2
Javascript tutorials on summarization
3
==================================================
4
TOOL PLAN:
5
I will search for Javascript tutorials on summarization. 
6
7
TOOL CALLS:
8
Tool name: search_code_examples_detailed | Parameters: {"query":"summarization","programming_language":"js"}
9
==================================================
10
RESPONSE:
11
I found one JavaScript tutorial on summarization:
12
- Build a Chrome extension to summarize web pages
13
==================================================
14
CITATIONS:
15
16
Start: 52| End:99| Text:'Build a Chrome extension to summarize web pages' 
17
Sources:
18
1. search_code_examples_detailed_mz15bkavd7r1:0

Let’s now try a query that involves filtering based on the endpoints. Here, the user asks for “code examples of using embed and rerank endpoints”.

And since we have set up the endpoints parameter to be an array, the agent is able to call the tool with a list of endpoints as its argument.

1
messages = run_agent(
2
    "Code examples of using embed and rerank endpoints."
3
)
4
5
# Tool name: search_code_examples | Parameters: {"endpoints":["embed","rerank"],"query":"..."}

1
QUESTION:
2
Code examples of using embed and rerank endpoints.
3
==================================================
4
TOOL PLAN:
5
I will search for code examples of using embed and rerank endpoints. 
6
7
TOOL CALLS:
8
Tool name: search_code_examples_detailed | Parameters: {"query":"code examples","endpoints":["embed","rerank"]}
9
==================================================
10
RESPONSE:
11
Here are some code examples of using the embed and rerank endpoints:
12
- Wikipedia Semantic Search with Cohere Embedding Archives
13
- RAG With Chat Embed and Rerank via Pinecone
14
- Build Chatbots That Know Your Business with MongoDB and Cohere
15
==================================================
16
CITATIONS:
17
18
Start: 71| End:127| Text:'Wikipedia Semantic Search with Cohere Embedding Archives' 
19
Sources:
20
1. search_code_examples_detailed_qjtk4xbt5g4n:0
21
22
23
Start: 130| End:173| Text:'RAG With Chat Embed and Rerank via Pinecone' 
24
Sources:
25
1. search_code_examples_detailed_qjtk4xbt5g4n:1
26
27
28
Start: 176| End:238| Text:'Build Chatbots That Know Your Business with MongoDB and Cohere' 
29
Sources:
30
1. search_code_examples_detailed_qjtk4xbt5g4n:2

Finally, let’s try a query that involves filtering based on both the programming language and the endpoints. Here, the user asks for “Python examples of using the chat endpoint”.

And the agent correctly uses both parameters to query the code examples.

1
messages = run_agent("Python examples of using the chat endpoint.")
2
3
# Tool name: search_code_examples | Parameters: {"endpoints":["chat"],"programming_language":"py","query":"..."}

1
QUESTION:
2
Python examples of using the chat endpoint.
3
==================================================
4
TOOL PLAN:
5
I will search for Python examples of using the chat endpoint. 
6
7
TOOL CALLS:
8
Tool name: search_code_examples_detailed | Parameters: {"query":"chat endpoint","programming_language":"py","endpoints":["chat"]}
9
==================================================
10
RESPONSE:
11
Here are some Python examples of using the chat endpoint:
12
- Calendar Agent with Native Multi Step Tool
13
- RAG With Chat Embed and Rerank via Pinecone
14
- Build Chatbots That Know Your Business with MongoDB and Cohere
15
==================================================
16
CITATIONS:
17
18
Start: 60| End:102| Text:'Calendar Agent with Native Multi Step Tool' 
19
Sources:
20
1. search_code_examples_detailed_79er2w6sycvr:0
21
22
23
Start: 105| End:148| Text:'RAG With Chat Embed and Rerank via Pinecone' 
24
Sources:
25
1. search_code_examples_detailed_79er2w6sycvr:2
26
27
28
Start: 151| End:213| Text:'Build Chatbots That Know Your Business with MongoDB and Cohere' 
29
Sources:
30
1. search_code_examples_detailed_79er2w6sycvr:3

Summary

In this tutorial, we learned about:

• How to define the function for data querying
• How to create the tool for generating multi-faceted queries
• How to build an agent for performing multi-faceted queries
• How to run the agent

By implementing multi-faceted queries over semi-structured data, we’ve enhanced our RAG system to handle more specific and targeted searches. This approach allows for better utilization of metadata and more precise filtering of results, which is particularly useful when dealing with large collections of code examples and tutorials.

While this tutorial demonstrates how to work with semi-structured data, the agentic RAG approach can be applied to structured data as well. That means we can build agents that can translate natural language queries into queries for tables or relational databases.

In Part 5, we’ll learn how to perform RAG over structured data (tables).