Crearea de Unelte Custom: Decoratorul @tool și BaseTool în CrewAI & Sisteme Multi-Agent

from crewai.tools import tool

@tool("Verificare Curs BNR")
def verifica_curs_bnr(moneda: str) -> str:
    """Returnează cursul oficial BNR pentru moneda specificată (ex: EUR, USD)."""
    # Logică apel API / DB
    return f"Cursul pentru {moneda.upper()} este 4.9765 RON."

Descriere & Utilizare

Un agent fără unelte se poate baza doar pe cunoștințele din antrenamentul modelului. Pentru a interacționa cu lumea exterioară (API-urile firmei, baza de date, calcule financiare), îi atașezi unelte în lista tools=[...] a clasei Agent sau a unui Task specific.

Cea mai rapidă metodă este decoratorul @tool("Nume Unealtă") din crewai.tools: decorezi o funcție Python cu adnotări de tip și un docstring explicativ, iar CrewAI o transformă automat într-o unealtă cu cache inteligent.

Pentru unelte avansate care au nevoie de stare internă, conexiuni refolosibile sau validare strictă cu mai mulți parametri, poți moșteni clasa BaseTool, definind args_schema: Type[BaseModel] și metoda _run().

Cum să o reții ușor

💡 Decoratorul @tool este ca un briceag elvețian pe care îl prinzi la centura agentului în două secunde, iar BaseTool este o trusă profesională cu instrucțiuni de siguranță gravate pe capac (args_schema).

Opțiuni și parametri tehnici

• @tool("Titlu Unealtă"): numele uneltei și docstring-ul funcției sunt citite direct de LLM pentru a decide când să o apeleze.
• cache_function: în CrewAI, rezultatele uneltelor sunt memorate în cache implicit (dacă un al doilea agent apelează aceeași unealtă cu aceiași parametri, primește răspunsul instantaneu fără apel redundant).
• result_as_answer=True: forțează agentul să returneze direct rezultatul uneltei ca răspuns final al task-ului, fără ca LLM-ul să îl mai reformuleze.

Exemple practice și cazuri de utilizare

• Atașarea uneltei doar pe o sarcină anume: Task(..., tools=[verifica_curs_bnr]) (astfel agentul nu o folosește din greșeală la alte sarcini).
• Controlul cache-ului pe o unealtă: verifica_curs_bnr.cache_function = lambda args, result: "Eroare" not in result (nu salva în cache răspunsurile eșuate).
• Subclasarea BaseTool cu Pydantic: definește class CautareInput(BaseModel): interogare: str = Field(..., description="...") și args_schema = CautareInput.

Sfaturi de configurare & capcane

Returnează întotdeauna un str concis și informativ din funcția decorată cu @tool, chiar și atunci când apare o excepție în `try/except` (ex: return f"Eroare API: {e}. Încearcă cu alt parametru.").

Comenzi și ghiduri înrudite

• crewai-builtin-tools-mcp: Resursă asociată din acest modul.
• crewai-agent-role-goal: Resursă asociată din acest modul.
• crewai-task-guardrails-human: Resursă asociată din acest modul.