From bdfaa935103008d031f346f15aa81f690f95965b Mon Sep 17 00:00:00 2001 From: Nicolas Fernandez Date: Wed, 11 Mar 2026 17:54:11 -0300 Subject: [PATCH 1/2] docs: update agents and tools documentation to clarify registration process --- docs/agents-tools.md | 63 ++++++++++++++++++++++++++++++++++++++++- docs/getting-started.md | 6 ++++ 2 files changed, 68 insertions(+), 1 deletion(-) diff --git a/docs/agents-tools.md b/docs/agents-tools.md index d4637cd..15e9c45 100644 --- a/docs/agents-tools.md +++ b/docs/agents-tools.md @@ -14,9 +14,11 @@ This document provides comprehensive reference documentation for building agents - [BaseTool](#basetool) - [Tool Parameters](#tool-parameters) - [Tool Implementation](#tool-implementation) + - [Registering with an Agent](#registering-with-an-agent) - [Retrieval Tools](#retrieval-tools) - [BaseRetrievalTool](#baseretrievaltool) - [Connecting to Retrievals](#connecting-to-retrievals) + - [Registering with an Agent](#registering-retrieval-tools-with-an-agent) - [Related Content](#related-content) - [BaseFAQ](#basefaq) - [BaseFixedResponse](#basefixedresponse) @@ -414,6 +416,36 @@ class WeatherTool(BaseTool): return {"temp": 20, "condition": "sunny"} ``` +### Registering with an Agent + +> **Important:** Defining a tool class in `agents/tools.py` does **not** make it available to an agent automatically. You must explicitly import the tool and add an instance of it to the agent's `tools` list in `agents//agent.py`. + +```python +# agents//agent.py + +from cogsol.agents import BaseAgent, genconfigs +from cogsol.prompts import Prompts +from ..tools import WeatherTool, OrderLookupTool # Import your tool classes + + +class SupportAgent(BaseAgent): + system_prompt = Prompts.load("support.md") + generation_config = genconfigs.QA() + + # Each tool must be explicitly listed here as an instance + tools = [ + WeatherTool(), + OrderLookupTool(), + ] +``` + +After updating `agent.py`, regenerate and apply migrations so the agent configuration is synced: + +```bash +python manage.py makemigrations agents +python manage.py migrate agents +``` + --- ## Retrieval Tools @@ -493,6 +525,34 @@ class SupportAgent(BaseAgent): 2. Create the retrieval in `data/retrievals.py` 3. Run `python manage.py makemigrations data` 4. Run `python manage.py migrate data` +5. Register the retrieval tool in the agent's `tools` list in `agents//agent.py` (see below) + +### Registering Retrieval Tools with an Agent + +> **Important:** Defining a retrieval tool class in `agents/searches.py` does **not** make it available to an agent automatically. You must explicitly import it and add an instance to the agent's `tools` list in `agents//agent.py`. + +```python +# agents//agent.py + +from cogsol.agents import BaseAgent, genconfigs +from cogsol.prompts import Prompts +from ..searches import ProductDocsSearch # Import your retrieval tool + + +class SupportAgent(BaseAgent): + system_prompt = Prompts.load("support.md") + generation_config = genconfigs.QA() + + # Retrieval tools are registered the same way as regular tools + tools = [ProductDocsSearch()] +``` + +After updating `agent.py`, regenerate and apply migrations: + +```bash +python manage.py makemigrations agents +python manage.py migrate agents +``` --- @@ -786,7 +846,8 @@ class KnowledgeBaseSearch(BaseRetrievalTool): python manage.py migrate data ``` 6. **Ingest Documents:** `python manage.py ingest knowledge_base /path/to/docs` -7. **Connect to Agent:** Create retrieval tool in `agents/searches.py` +7. **Create Retrieval Tool:** Create retrieval tool in `agents/searches.py` +8. **Register with Agent:** Add the retrieval tool to the agent's `tools` list in `agents//agent.py`, then run `python manage.py makemigrations agents && python manage.py migrate agents` ## Prompts diff --git a/docs/getting-started.md b/docs/getting-started.md index 2db7f72..723bb99 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -352,6 +352,12 @@ class EscalationLesson(BaseLesson): ## Adding Tools +> **Note:** Adding a tool to your project is a two-step process: +> 1. **Define** the tool class in `agents/tools.py` (or `agents/searches.py` for retrieval tools). +> 2. **Register** it in the agent by importing it and adding an instance to the `tools` list in `agents//agent.py`. +> +> Simply defining the tool class is not enough — the agent will not use it until it is explicitly listed in `agent.py`. + ### Step 1: Create a Custom Tool Edit `agents/tools.py` to add a useful tool. New projects include a commented example block; uncomment it or replace it with your own tool classes. From d6f0357c83a93a8de17e3e0fe34ca72ab04bfa5c Mon Sep 17 00:00:00 2001 From: Nicolas Fernandez Date: Thu, 12 Mar 2026 11:00:30 -0300 Subject: [PATCH 2/2] docs: clarify registration process for retrieval tools in agents --- docs/agents-tools.md | 32 +++++++------------------------- 1 file changed, 7 insertions(+), 25 deletions(-) diff --git a/docs/agents-tools.md b/docs/agents-tools.md index 15e9c45..09a72cd 100644 --- a/docs/agents-tools.md +++ b/docs/agents-tools.md @@ -529,30 +529,7 @@ class SupportAgent(BaseAgent): ### Registering Retrieval Tools with an Agent -> **Important:** Defining a retrieval tool class in `agents/searches.py` does **not** make it available to an agent automatically. You must explicitly import it and add an instance to the agent's `tools` list in `agents//agent.py`. - -```python -# agents//agent.py - -from cogsol.agents import BaseAgent, genconfigs -from cogsol.prompts import Prompts -from ..searches import ProductDocsSearch # Import your retrieval tool - - -class SupportAgent(BaseAgent): - system_prompt = Prompts.load("support.md") - generation_config = genconfigs.QA() - - # Retrieval tools are registered the same way as regular tools - tools = [ProductDocsSearch()] -``` - -After updating `agent.py`, regenerate and apply migrations: - -```bash -python manage.py makemigrations agents -python manage.py migrate agents -``` +> **Important:** Defining a retrieval tool class in `agents/searches.py` does **not** make it available to an agent automatically. Retrieval tools are registered with an agent exactly the same way as regular tools — see [Registering with an Agent](#registering-with-an-agent). --- @@ -847,7 +824,12 @@ class KnowledgeBaseSearch(BaseRetrievalTool): ``` 6. **Ingest Documents:** `python manage.py ingest knowledge_base /path/to/docs` 7. **Create Retrieval Tool:** Create retrieval tool in `agents/searches.py` -8. **Register with Agent:** Add the retrieval tool to the agent's `tools` list in `agents//agent.py`, then run `python manage.py makemigrations agents && python manage.py migrate agents` +8. **Register with Agent:** Add the retrieval tool to the agent's `tools` list in `agents//agent.py` (see [Registering with an Agent](#registering-with-an-agent)) +9. **Migrate agents:** + ``` + python manage.py makemigrations agents + python manage.py migrate agents + ``` ## Prompts