El mòdul 4 va acabar amb una frontera dibuixada amb precisió: DocuBot sap — respon amb fonts sobre tot el que diu la documentació de Nubelia — però no pot fer. La pregunta que vam deixar a l'aire, "quantes tasques té ara mateix el meu projecte Atlas?", no té resposta en cap wiki: la dada viu a l'API de Nubelia, canvia cada minut, i cap pipeline RAG del món no la recuperarà d'una col·lecció de chunks. En aquesta lliçó creuem aquesta frontera amb el mecanisme anomenat function calling (o tool use): descrivim al model quines funcions tenim, el model decideix quan i amb quins arguments convé cridar-les, i el nostre codi les executa i li retorna el resultat. És probablement la idea amb pitjor nom de tot l'ecosistema — el model no crida cap funció — i alhora una de les més transformadores: és la peça que separa un chatbot d'un assistent que opera sobre el teu sistema. Aquí construirem la primera eina de DocuBot, consultar_projecte, i tancarem per fi la pregunta d'Atlas.

1. La idea clau: el model decideix, el teu codi executa
2. Definir una eina: JSON Schema i descripcions que són prompt engineering
3. El flux complet amb l'SDK: tool_use → executar → tool_result → resposta final
4. La primera eina de DocuBot: consultar_projecte contra l'API de Nubelia
5. Quan l'eina falla: errors com a tool_result amb is_error
6. tool_choice: elecció automàtica, forçada i prohibida
7. Function calling com a evolució de "demanar JSON" (02-03)

Desmuntem primer el malentès que dona nom a la tècnica. En function calling el LLM no executa absolutament res: no té accés a la teva xarxa, ni a la teva base de dades, ni a l'API de Nubelia. L'única cosa que fa el model és el que sempre ha fet — generar tokens —, només que ara pot generar un tipus especial de sortida estructurada que significa "vull que cridis aquesta funció amb aquests arguments". La teva aplicació llegeix aquesta petició, decideix si l'atén, executa la funció amb codi Python normal i corrent, i li retorna el resultat al model en un segon torn perquè redacti la resposta final.

Aquesta divisió del treball té conseqüències importants, totes bones:

• El control és teu. Entre el tool_use i l'execució hi ha una línia de codi Python que escrius tu. Pots validar els arguments, aplicar permisos, registrar la crida o negar-te a executar-la. El model proposa; el teu codi disposa.
• La seguretat es raona com sempre. La funció que executes és codi teu amb les credencials de la teva aplicació — li apliquen els mateixos principis de tota la vida, començant pel de mínim privilegi: una eina de consulta ha de fer servir credencials de només lectura. consultar_projecte no pot esborrar res perquè el codi que la implementa no sap esborrar res. (Les accions d'escriptura i les seves salvaguardes arriben a 05-02, i els atacs que exploten eines, a 06-01.)
• El model aporta el que cap if no pot: entendre que "com va Atlas?", "digue'm l'estat del meu projecte Atlas" i "how many open tasks in Atlas?" són la mateixa intenció, i traduir-la a una crida amb arguments correctes.

Perquè el model pugui demanar una funció, primer cal descriure-la-hi. Cada eina es defineix amb tres peces:

La description mereix que ens hi aturem: és prompt engineering. Tot el que vam aprendre al mòdul 2 aplica aquí — el model decidirà si fa servir l'eina, i amb quins arguments, basant-se gairebé exclusivament en aquest text. Compara:

La segona versió fa tres coses que la primera no fa: delimita el quan sí amb exemples (few-shot en miniatura, 02-02), delimita el quan no (evita que el model cridi l'API per a preguntes de documentació), i anuncia què retorna (el model redactarà millor la resposta final sabent què pot esperar).

Vegem el mecanisme amb l'SDK anthropic que fem servir des de 03-01 — el flux és conceptualment idèntic a OpenAI, Google o Mistral (canvien els noms de camp: tools/tool_calls/function, però el ball és el mateix). Els passos:

1. Primera crida: envies la pregunta i la llista d'eines (paràmetre tools).
2. Si el model decideix fer-ne servir una, la resposta arriba amb stop_reason == "tool_use" i un bloc de contingut de tipus tool_use amb name, input (els arguments, ja com a dict) i un id de correlació.
3. El teu codi executa la funció corresponent.
4. Segona crida: reenvies la conversa completa — inclosa la resposta de l'assistent amb el seu bloc tool_use — i hi afegeixes un missatge d'usuari amb un bloc tool_result que referencia aquell id.
5. El model, ja amb la dada a la mà, redacta la resposta final (stop_reason == "end_turn").

Els punts 2 i 4 amaguen els dos detalls que més errors causen: el bloc tool_use de l'assistent ha de tornar a l'historial (si no, el model no sap què va demanar), i el tool_result va dins d'un missatge amb rol user — des del punt de vista de la conversa, el resultat de l'eina és una cosa que "expliques" al model, i ha de ser el primer contingut d'aquell missatge.

Construïm-ho de debò. Com que en aquest curs no tenim una API de Nubelia desplegada, la simulem amb un mòdul mock — la gràcia didàctica és que al model tant li fa: ell només veu la definició de l'eina i els resultats; que al darrere hi hagi un dict o un microservei amb base de dades és invisible des del seu costat de la frontera.

Ara la definició de l'eina i el seu despatxador, en un mòdul nou que anirà creixent durant el mòdul:

I el flux complet. Fixa't que reutilitzem cridar_amb_reintents (03-02) i MODEL (03-01) sense tocar-los — les eines són un paràmetre més de la crida. El que sí que necessitem és un system nou: el SYSTEM_DOCUBOT de 02-01 ordena basar-se exclusivament en el bloc <documentacio>, i aquesta regla, perfecta per a RAG, deixaria l'eina sense feina. Afegim a prompts.py una variant (i pugem PROMPT_VERSION, com mana 02-04):

Una execució típica:

La pregunta que a 01-04 ens servia d'exemple d'allò impossible acaba de tenir resposta — i amb la dada real del sistema, no amb una al·lucinació plausible. Tres observacions abans de continuar:

• bloc.input arriba com a dict ja parsejat per l'SDK. Tot i així, tracta'l com a entrada no fiable: el model pot passar un nom de projecte que no existeix o un valor inesperat. La nostra defensa és a obtenir_projecte (normalitza i valida), no a confiar en el model.
• El resultat viatja com a text (per això el json.dumps): un tool_result és contingut per al model, i un JSON compacte i amb claus descriptives és un format que entén de meravella. No cal prosa.
• Aquest flux resol un pas d'eina i acaba. Si el model necessités encadenar diverses crides (consultar la documentació i després l'API), caldria un bucle — exactament el tema de 05-02, no l'avancem.

Ja has vist el try/except al codi anterior; ara, la filosofia. Quan una eina falla, la pitjor opció és deixar que l'excepció rebenti el flux, i la segona pitjor és retornar a l'usuari un traceback. L'opció bona és la que hem implementat: retornar l'error al model com a tool_result amb is_error: True, amb un missatge d'error informatiu — i deixar que el model faci allò que sap fer millor: explicar-lo en llenguatge natural.

Pregunta: "com va el meu projecte Safir?". L'eina llança ProjecteNoTrobat amb el nostre missatge ("No existeix cap projecte anomenat 'Safir'. Projectes disponibles: Atlas, Boreal, Cierzo."), i el model respon una cosa com:

Fixa't en la cadena de valor: el missatge de l'excepció també és prompt engineering. Com que incloem la llista de projectes disponibles a l'error, el model pot oferir alternatives en lloc d'un "no existeix" eixut. Escriu els errors de les teves eines pensant que el seu lector és un LLM que els tornarà a explicar: què ha fallat, per què, i què s'hi pot fer. I la mateixa regla de sempre: al missatge d'error, res de secrets ni detalls interns (rutes, SQL, stack traces) — anirien directes al context del model i, potencialment, a la resposta de l'usuari.

Per defecte el model decideix lliurement si fa servir una eina o respon directament. El paràmetre tool_choice et dona el comandament quan el necessites:

El tercer cas és més útil del que sembla i connecta directament amb la secció següent: si forces una eina concreta, el model genera sempre un bloc tool_use amb arguments que compleixen el teu input_schema. És a dir: acabes d'aconseguir sortida estructurada garantida.

A 02-03 vam muntar el contracte JSON de DocuBot demanant el format al prompt i defensant-nos amb netejar_json i validar_contracte — el model de vegades embolicava el JSON amb prosa o amb tanques de codi, i calia netejar-lo. Function calling és la versió industrialitzada d'aquella idea:

L'última fila és la moralitat: function calling elimina la lampisteria sintàctica, però la validació defensiva de valors no es jubila — que {"nom": "Safir"} sigui JSON perfecte no fa que Safir existeixi. L'instint de 02-03 ("no confiïs, valida") continua sent la llei; només ha canviat on aplicar-lo.

• Oblidar reenviar el torn de l'assistent. L'error més freqüent del flux: enviar el tool_result sense haver afegit abans {"role": "assistant", "content": resposta.content} a l'historial. L'API rebutjarà la petició — el tool_result referencia un tool_use_id que, sense aquell missatge, no existeix a la conversa.
• Descripcions d'eina esquifides. "Consulta un projecte" produeix crides de més (per a preguntes de documentació) i de menys (per a formulacions indirectes). Tracta la description amb el mateix rigor amb què vas tractar SYSTEM_DOCUBOT: quan sí, quan no, exemples.
• Creure que l'esquema valida per tu. L'input_schema garanteix forma, no veritat. Valida els valors a la teva funció (existeix el projecte?, el rang és raonable?) com si els hagués teclejat un desconegut — perquè, en certa manera, així és.
• No preveure el camí sense eina. Amb tool_choice: auto, el model pot respondre directament (stop_reason == "end_turn"). Si el teu codi assumeix que sempre hi haurà un bloc tool_use, aquell next(...) llançarà StopIteration a la primera pregunta trivial. Comprova sempre stop_reason primer.
• Diversos tool_use en un mateix torn. El model pot demanar més d'una eina alhora (crides paral·leles). El nostre flux d'avui en processa una perquè la seva única eina no dona per a més; el bucle de 05-02 iterarà sobre tots els blocs. Si et passa abans, respon amb un tool_result per cada tool_use_id.
• Errors d'eina que no ajuden ningú. KeyError: 'safir' com a tool_result obliga el model a improvisar. Escriu errors amb context i alternatives — i sense filtrar informació interna.

1. Segona eina: llistar_projectes. Afegeix a eines.py una eina sense arguments que retorni la llista de projectes de l'usuari (nom i estat), i amplia executar_eina. Prova amb "quins projectes tinc ara mateix?" i amb "com va Atlas?" per comprovar que el model tria l'eina correcta en cada cas.
2. L'error com a conversa. Amb el codi de la lliçó, fes la pregunta "quantes tasques té el meu projecte Safir?" i observa la resposta. Després, empobreix a propòsit el missatge de ProjecteNoTrobat (deixa'l en "error") i repeteix. Compara totes dues respostes finals i escriu en una frase la conclusió.
3. Extracció estructurada amb eina forçada. Defineix una eina extreure_consulta l'input_schema de la qual tingui categoria (enum amb les 6 categories de prompt_classificacio() de 02-02) i projecte (string opcional). Crida-la amb tool_choice: {"type": "tool", "name": "extreure_consulta"} sobre la pregunta "no em deixa facturar les hores del projecte Boreal" i examina bloc.input. Quina peça de 02-03 acabes de substituir?

1. Definició i despatx:

Amb "quins projectes tinc?" el model ha de triar llistar_projectes; amb "com va Atlas?", consultar_projecte. Si es confon, la palanca és la description (no pas el codi!).

2. Amb l'error ric, el model respon amb alternatives concretes ("els teus projectes són Atlas, Boreal i Cierzo, et referies a algun d'aquests?"). Amb "error" a seques, el model només pot dir que alguna cosa ha fallat, o pitjor, especular sobre el motiu. Conclusió en una frase: la qualitat de la resposta final davant d'una fallada està limitada per la qualitat del missatge d'error que retorna la teva eina — els errors de les eines són part del prompt.

3. Esquema i crida:

Acabes de substituir el tàndem "demanar JSON al prompt + netejar_json": amb l'eina forçada no hi ha prosa a netejar ni tanques de codi a treure. validar_contracte (la validació semàntica) continuaria tenint feina — l'enum garanteix que categoria és una de les sis, però ningú no garanteix que sigui la correcta.

DocuBot acaba de fer una cosa que cap RAG no podia fer: respondre amb una dada que no estava escrita enlloc quan va arrencar la conversa. El mecanisme, un cop desmuntat el nom, és honest i simple — el model decideix quina funció cridar i amb quins arguments, el teu codi executa i li retorna el resultat, el model redacta —, i les seves peces són velles conegudes amb vestit nou: la description és prompt engineering (mòdul 2), l'input_schema és el contracte JSON de 02-03 amb garanties sintàctiques de fàbrica, els errors com a tool_result amb is_error són la degradació elegant de 03-02 explicada al model, i el tool_choice forçat ens regala de passada l'extracció estructurada més robusta que coneixem. Però la nostra respondre_amb_eina() té una limitació estructural que potser ja t'ha grinyolat: executa un pas d'eina i acaba. Si l'usuari pregunta "el meu projecte Atlas supera el límit de tasques del meu pla?", calen dues consultes — la documentació per al límit del pla, l'API per a les tasques d'Atlas — i una comparació entre totes dues. Això ja no és un flux de dues crides: és un bucle en què el model raona, actua, observa el resultat i decideix si necessita continuar. Aquest bucle té nom — agent — i és exactament el que construïm a la lliçó següent, on a més el RAG del mòdul 4 patirà una transformació elegant: de pipeline a eina.