Herramienta de búsqueda web de LangChain sobre una API SERP, más una versión para LlamaIndex

¿Cómo escribo la herramienta de búsqueda?

Una herramienta de LangChain es una función tipada con un docstring. El decorador convierte la firma en el esquema de argumentos y el docstring en la descripción que lee el modelo, así que ambos merecen cuidado. Nombra los argumentos tal como el modelo debería pensarlos: una consulta, un país, un idioma.

Devuelve texto, no el JSON completo. Cinco resultados con título, enlace y snippet le dan al modelo lo suficiente para responder y citar, a una fracción de los tokens de la respuesta en bruto. Devuelve un mensaje corto en los errores en vez de lanzar una excepción, para que el agente pueda explicar o intentar de nuevo.

"""A LangChain tool that searches Google through the SerpCrypto SERP API."""
import os

import requests
from langchain_core.tools import tool

API_URL = "https://serpcrypto.com/api/v1/search"


@tool
def google_search(query: str, gl: str = "us", hl: str = "en") -> str:
    """Search Google for current information. Returns the top results with title, link and snippet.

    Args:
        query: the search query, as a person would type it.
        gl: two-letter country code of the results, for example us, gb or de.
        hl: language code, for example en, de or pt-BR.
    """
    r = requests.get(
        API_URL,
        params={"q": query, "gl": gl, "hl": hl},
        headers={"Authorization": "Bearer " + os.environ["SERPCRYPTO_API_KEY"]},
        timeout=90,
    )
    if r.status_code != 200:
        return f"Search failed with HTTP {r.status_code}."
    results = r.json().get("organic_results", [])[:5]
    return "\n\n".join(f"{x['title']}\n{x['link']}\n{x.get('snippet', '')}" for x in results) or "No results."

¿Cómo dejo que un agente decida cuándo buscar?

Pasa la herramienta a create_agent, disponible desde LangChain 1.0. El modelo lee la descripción y llama a la herramienta cuando la pregunta necesita datos recientes. Configura AGENT_MODEL con un identificador de modelo que admita tu cuenta, como openai: o anthropic: seguido de un nombre de modelo; sirve cualquier modelo de chat con tool calling.

El system prompt importa tanto como el código. Pedirle al agente que busque solo información más reciente que sus datos de entrenamiento y que cite los enlaces mantiene las respuestas fundamentadas y limita el número de búsquedas de pago.

"""An agent that decides when to search (LangChain 1.0 or later)."""
import os

from langchain.agents import create_agent

from search_tool import google_search

agent = create_agent(
    model=os.environ["AGENT_MODEL"],  # a provider:model string, such as one of your OpenAI or Anthropic models
    tools=[google_search],
    system_prompt="Answer with current facts. Use google_search when you need information newer than your training data, and cite the links you used.",
)

result = agent.invoke({"messages": [{"role": "user", "content": "What changed in Google's search results pages this year?"}]})
print(result["messages"][-1].content)

¿Cómo hago lo mismo con LlamaIndex?

Escribe una función normal con type hints y un docstring, y luego envuélvela con FunctionTool.from_defaults. LlamaIndex lee el nombre, los hints y el docstring para construir el esquema de la herramienta, igual que LangChain. Añade la herramienta a cualquier agente de LlamaIndex que acepte una lista de herramientas.

"""The same search as a LlamaIndex FunctionTool."""
import os

import requests
from llama_index.core.tools import FunctionTool


def google_search(query: str, gl: str = "us", hl: str = "en") -> str:
    """Search Google for current information and return the top results with title, link and snippet."""
    r = requests.get(
        "https://serpcrypto.com/api/v1/search",
        params={"q": query, "gl": gl, "hl": hl},
        headers={"Authorization": "Bearer " + os.environ["SERPCRYPTO_API_KEY"]},
        timeout=90,
    )
    r.raise_for_status()
    results = r.json().get("organic_results", [])[:5]
    return "\n\n".join(f"{x['title']}\n{x['link']}\n{x.get('snippet', '')}" for x in results)


search_tool = FunctionTool.from_defaults(fn=google_search)
# Pass search_tool in the tools list of your LlamaIndex agent.

¿La herramienta debe devolver JSON o texto?

Texto, en la mayoría de los casos. Los modelos leen bien el texto corto y etiquetado, y cuesta menos tokens que un JSON anidado. Devuelve JSON solo cuando un paso posterior de tu cadena lo analice, por ejemplo para guardar rankings.

Mantén los enlaces en la salida. Le permiten al modelo citar sus fuentes y te permiten comprobar después en qué páginas se basó una respuesta.

¿Cómo controlo los costes de búsqueda en un agente?

Cada llamada a la herramienta que sale bien es un crédito. Tres hábitos mantienen el conteo bajo: decirle al modelo en el system prompt cuándo no buscar, limitar el número de llamadas a la herramienta por ejecución en tu bucle del agente y cachear respuestas para preguntas repetidas en tu propio código.

Un pack de 100.000 búsquedas cuestan 56,25 US$, y Los créditos de búsqueda prepagados no caducan nunca: las consultas sin usar se quedan en tu cuenta hasta que las uses, así que un mes tranquilo no desperdicia nada.