Patrón de integración

Las dos formas de conectarlo

La mayoría de los equipos recurre primero a la versión imperativa, porque parece más sencilla:

# Imperative: your code decides, always, on every turn.
context = hive.search(user_question)        # always fires, relevant or not
answer  = llm(prompt=user_question, context=context)
return answer

La versión con invocación de herramientas delega ese criterio en el modelo:

# Tool-based: the model decides whether to search, what to search for,
# and whether what came back was worth a follow-up query.
tools = [
    {
        "name": "search_team_knowledge",
        "description": (
            "Search the team's knowledge base for prior decisions, standards "
            "and meeting outcomes. Use whenever the answer might depend on "
            "something the team already decided. Prefer this over guessing."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "question": {
                    "type": "string",
                    "description": "A natural-language question, not keywords.",
                }
            },
            "required": ["question"],
        },
    },
]
# ... on a tool_use block, call aiqbee_search and return the result.

Por qué gana la segunda

1. La calidad de la recuperación depende de la consulta, y el modelo escribe mejores consultas

aiqbee_search es semántica. Si recibe las palabras en bruto del usuario, rinde razonablemente; si recibe una pregunta bien formulada, rinde considerablemente mejor. El modelo tiene la conversación delante: puede convertir "¿decidimos descartar eso?" en "¿cuál fue la decisión sobre limitar la tasa de la API pública?". Su código no puede, porque no sabe a qué se refería "eso".

2. La mayoría de los turnos no deberían realizar ninguna búsqueda

"Gracias, eso funcionó" no requiere recuperación. Una búsqueda incondicional aumenta la latencia e introduce en el prompt contexto irrelevante, lo que degrada las respuestas de forma medible. Permitir que el modelo se abstenga es una ventaja, no pereza.

3. Una sola búsqueda suele no ser suficiente

Las preguntas reales requieren una primera búsqueda, revisar lo obtenido y una segunda búsqueda más acotada. Ese bucle es natural en la invocación de herramientas y difícil de expresar con un flujo de control fijo.

4. Escribir de vuelta es donde una capa de memoria demuestra su valor

Esta es la parte que la mayoría de las integraciones omite, y es el objetivo principal. Proporcione también una herramienta de escritura al modelo, y el conocimiento se acumulará como efecto secundario del trabajo normal, sin que nadie tenga que acordarse de archivarlo.

{
    "name": "record_team_knowledge",
    "description": (
        "Record a durable decision, standard or outcome so it is available "
        "to the team later. Use when something is settled that a colleague "
        "would need in six months. Do NOT use for chit-chat, transient "
        "status, or anything you were not told."
    ),
    "input_schema": {
        "type": "object",
        "properties": {
            "title":   {"type": "string"},
            "content": {"type": "string",
                        "description": "Include who, what and WHY. Self-contained."},
            "type_id": {"type": "string",
                        "description": "A real id from aiqbee_get_neuron_types."},
        },
        "required": ["title", "content", "type_id"],
    },
}

Cómo redactar descripciones de herramientas que funcionen

La descripción es su verdadera superficie de integración: es el prompt que decide si la herramienta se usa correctamente. Algunos aspectos que importan de forma constante:

• Indique cuándo usarla, no solo qué hace. "Busca en la base de conocimiento" produce un uso errático. "Úsela siempre que la respuesta pueda depender de una decisión previa del equipo" produce un buen uso.
• Indique cuándo no usarla. Sin una exclusión explícita, las herramientas de escritura se invocan ante simples cortesías y el Brain se llena de ruido.
• Describa la forma de una buena entrada. "Una pregunta en lenguaje natural, no palabras clave" cambia lo que envía el modelo.
• Devuelva los errores tal cual. Los errores de Hive están redactados para ser accionables: un duplicado rechazado devuelve la neurona existente para que el modelo pueda actualizarla o vincularla. Si los descarta, pierde esa recuperación.

Salvaguardas que conviene mantener en su código

Dejar al modelo el criterio sobre cuándo llamar no es lo mismo que darle autoridad sin restricciones. Mantenga esto de su lado:

• Mínimo privilegio. Conceda a la cuenta de servicio acceso de solo lectura, salvo que el agente necesite realmente escribir. El acceso es por Brain.
• Identidades separadas por integración. Una cuenta de servicio por agente, para que el historial de auditoría y la revocación tengan sentido.
• Confirme las llamadas destructivas. Lo mejor es dejar las herramientas de eliminación fuera del conjunto de herramientas, o protegerlas con aprobación humana.
• Active la auditoría para todo lo regulado — así cada escritura es atribuible a la cuenta de servicio que llama. Función de pago; consulte Licencias & planes.

Cuándo son adecuadas las llamadas imperativas

Existe un caso legítimo para llamar directamente: el trabajo determinista y no conversacional. Importaciones masivas de documentos, una sincronización nocturna, un script de aprovisionamiento, una migración. No se requiere criterio, así que no hay nada que delegar: use la API REST o llame directamente a las herramientas MCP y manténgalo sencillo.