[FEATURE] Document the full workflow: Retrieval → Search → Agent integration

[virginia-delos]

Problem Statement

The current documentation explains how to create a Search (or Retrieval Tool), but it does not clearly explain that a Retrieval must be defined first before creating a Search.

As a result, users attempting to create a search from scratch may not understand that the correct workflow is:

1. Define a Retrieval
2. Create a Retrieval Tool (Search)
3. Register the tool in the Agent

Without this explanation, the relationship between retrievals, searches, and agents is unclear, making the architecture harder to understand for new users.

Proposed Solution

Add a dedicated section in the documentation that clearly describes the full workflow required to implement a search from scratch:

Step 1 – Define a Retrieval

• Explain its purpose (semantic search configuration).
• Specify that it must be defined in data/retrievals.py.
• Provide a clean, correct example.

Step 2 – Create a Retrieval Tool (Search)

• Explain that this connects the retrieval to the agent.
• Specify the expected location (e.g., agents/searches.py).
• Provide a minimal, correct example.

Step 3 – Register the Search in the Agent

• Show how to include the search tool in the agent’s tools list.
• Clarify that without this step, the search will not be used.
• Additionally, ensure the examples are clean (remove duplicated imports and repeated class definitions).

Alternative Solutions

Add a “Creating a Search from Scratch” tutorial-style guide.

Use Case

A developer wants to create a new search capability for their agent without first creating a Retrieval. This results in confusion or runtime errors because the retrieval layer was never defined.