dspy.ReAct, unelte (dspy.Tool) și MCP în DSPy & Programare Algoritmică LLM

agent = dspy.ReAct("question -> answer", tools=[functie], max_iters=10)
unealta = dspy.Tool.from_mcp_tool(session, mcp_tool)

O unealtă DSPy este o funcție Python cu type hints și docstring. dspy.Tool deduce din ea numele, descrierea și schema argumentelor; modulele care primesc tools= fac conversia automat. Argumentele propuse de model sunt validate față de schemă înainte de execuție. Numele funcției, al parametrilor și docstring-ul sunt tot ce vede modelul, deci contează la fel de mult ca numele câmpurilor dintr-o semnătură.

La fiecare pas, dspy.ReAct cere modelului next_thought, next_tool_name și next_tool_args, execută o singură unealtă și adaugă observația în trajectory. O excepție din unealtă devine observație, ca modelul să poată încerca altceva. Bucla se oprește când modelul alege unealta specială finish sau la max_iters (implicit 20); apoi un ChainOfThought separat extrage ieșirile, deci există cel puțin un apel în plus după buclă. dspy.ReActV2 este înlocuitorul experimental: istoric structurat dspy.History, mai multe apeluri de unelte pe tură și o unealtă submit care întoarce direct ieșirile. Documentația anunță că va deveni dspy.ReAct în 3.5, iar numele ReActV2 va fi eliminat în 3.6.

Uneltele unui server MCP se convertesc cu dspy.Tool.from_mcp_tool(session, tool) (extra-ul pip install -U "dspy[mcp]"). Rezultatul este o unealtă asincronă, deci agentul se apelează cu await agent.acall(...). Puntea acceptă atât SDK-ul MCP v1, cât și v2. Pentru uneltele LangChain există dspy.Tool.from_langchain(tool).

Concepte cheie și caracteristici

Concept / Parametru	Descriere practică
dspy.ReAct(signature, tools, max_iters=20)	Agentul: semnătura sarcinii, lista de unelte și numărul maxim de pași.
prediction.trajectory	Dicționarul pașilor: thought_i, tool_name_i, tool_args_i, observation_i.
dspy.Tool(func, name=None, desc=None, args=None, arg_types=None, arg_desc=None)	Împachetează o funcție; valorile date explicit le înlocuiesc pe cele deduse.
Tool.from_mcp_tool(session, tool, result_mode="text")	Unealtă asincronă pentru un tool MCP. result_mode="structured" întoarce structuredContent când există.
Tool.from_langchain(tool)	Unealtă DSPy dintr-un BaseTool LangChain.
allow_tool_async_sync_conversion	Setare (în dspy.context sau dspy.configure) care permite apelarea sincronă a unei unelte async.
dspy.ReActV2	Variantă experimentală cu istoric structurat; rezultatul are history și termination_reason.

Exemple practice și scenarii reale

Exemplul 1: Agent cu o unealtă

import dspy

dspy.configure(lm=dspy.LM("openai/gpt-6-astra"))

def vremea(oras: str) -> str:
    """Întoarce vremea curentă pentru un oraș."""
    return f"În {oras} este senin, 18 grade."   # date de test

agent = dspy.ReAct("intrebare -> raspuns", tools=[vremea], max_iters=5)
rez = agent(intrebare="Cum e vremea la Cluj?")
print(rez.raspuns)

for pas, valoare in rez.trajectory.items():
    print(f"{pas}: {valoare}")

Exemplul 2: Unealtă cu nume și descriere date explicit

def cauta(query: str, limit: int = 5) -> list[str]:
    """Caută în baza de cunoștințe pasaje relevante."""
    return index.search(query, limit=limit)

cauta_docs = dspy.Tool(cauta, name="cauta_docs", desc="Caută în documentația produsului.")
agent = dspy.ReAct("intrebare -> raspuns", tools=[cauta_docs])

Exemplul 3: Unelte de pe un server MCP

După tutorialul DSPy, care folosește clientul de nivel înalt din SDK-ul MCP v2; mcp_server.py este serverul tău.

import asyncio
import dspy
from mcp import Client, StdioServerParameters
from mcp.client.stdio import stdio_client

dspy.configure(lm=dspy.LM("openai/gpt-6-astra"))
server = StdioServerParameters(command="python", args=["mcp_server.py"])

async def main():
    async with Client(stdio_client(server)) as client:
        tools = await client.list_tools()
        unelte = [dspy.Tool.from_mcp_tool(client, t) for t in tools.tools]
        agent = dspy.ReAct("cerere -> rezultat", tools=unelte)
        rez = await agent.acall(cerere="Rezervă un zbor Iași–București pe 3 noiembrie.")
        print(rez.rezultat)

asyncio.run(main())

Greșeli frecvente și capcane

• Apelezi sincron un agent cu unelte MCP. Uneltele MCP sunt asincrone; folosește await agent.acall(...) sau activează explicit allow_tool_async_sync_conversion.
• Dai unelte cu nume vagi (f, run) sau fără docstring. Modelul nu are alt indiciu despre ce face unealta.
• Lași max_iters la valoarea implicită (20) pentru sarcini simple. Fiecare pas este un apel la model, plus apelul final de extragere.
• Construiești cod nou pe dspy.ReActV2 fără să fixezi versiunea DSPy. API-ul este marcat experimental.

Noțiuni și module înrudite

• dspy-built-in-modules
• dspy-async-streaming
• dspy-signatures-modules
• dspy-adapters-typed-outputs