ai-agents-for-beginners

Ako navrhnúť dobrých AI agentov

(Kliknite na obrázok vyššie pre zobrazenie videa tejto lekcie)

Dizajnový vzor používania nástrojov

Nástroje sú zaujímavé, pretože umožňujú AI agentom mať širší rozsah schopností. Namiesto toho, aby mal agent obmedzený súbor akcií, ktoré môže vykonať, pridaním nástroja môže agent teraz vykonávať širokú škálu akcií. V tejto kapitole sa pozrieme na dizajnový vzor používania nástrojov, ktorý popisuje, ako môžu AI agenti používať konkrétne nástroje na dosiahnutie svojich cieľov.

Úvod

V tejto lekcii sa pokúsime odpovedať na nasledujúce otázky:

Ciele učenia

Po dokončení tejto lekcie budete schopní:

Čo je dizajnový vzor používania nástrojov?

Dizajnový vzor používania nástrojov sa zameriava na to, aby dali LLM schopnosť interagovať s externými nástrojmi na dosiahnutie konkrétnych cieľov. Nástroje sú kód, ktorý môže agent vykonať na vykonanie akcií. Nástroj môže byť jednoduchá funkcia, ako napríklad kalkulačka, alebo API volanie na službu tretej strany, ako napríklad vyhľadávanie cien akcií alebo predpoveď počasia. V kontexte AI agentov sú nástroje navrhnuté tak, aby ich agenti vykonávali v reakcii na funkčné volania generované modelom.

Na aké použitia sa dá aplikovať?

AI agenti môžu využiť nástroje na dokončenie zložitých úloh, získanie informácií alebo prijímanie rozhodnutí. Dizajnový vzor používania nástrojov sa často používa v scénach vyžadujúcich dynamickú interakciu s externými systémami, ako sú databázy, webové služby alebo interprety kódu. Táto schopnosť je užitočná pre množstvo rôznych prípadov použitia, vrátane:

Aké prvky/stavebné kamene sú potrebné na implementáciu dizajnového vzoru používania nástrojov?

Tieto stavebné kamene umožňujú AI agentovi vykonávať širokú škálu úloh. Pozrime sa na kľúčové prvky potrebné pre implementáciu dizajnového vzoru používania nástrojov:

Ďalej sa pozrime podrobnejšie na Volanie funkcií/nástrojov.

Volanie funkcií/nástrojov

Volanie funkcie je primárny spôsob, akým umožňujeme veľkým jazykovým modelom (LLM) interagovať s nástrojmi. Často uvidíte, že „funkcia“ a „nástroj“ sa používajú zameniteľne, pretože „funkcie“ (bloby znovupoužiteľného kódu) sú „nástroje“, ktoré agenti používajú na vykonávanie úloh. Aby sa mohol kód funkcie zavolať, LLM musí porovnať požiadavku používateľa so špecifikáciou funkcie. Na tento účel sa posiela schéma obsahujúca popisy všetkých dostupných funkcií LLM. LLM potom vyberie najvhodnejšiu funkciu pre úlohu a vráti jej názov a argumenty. Vybraná funkcia sa vykoná, jej odpoveď sa pošle späť LLM, ktorý informáciu použije na zodpovedanie požiadavky používateľa.

Pre vývojárov, ktorí chcú implementovať volanie funkcií pre agentov, budete potrebovať:

  1. LLM model, ktorý podporuje volanie funkcií
  2. Schému obsahujúcu popisy funkcií
  3. Kód pre každú popísanú funkciu

Použime príklad získania aktuálneho času v meste na ilustráciu:

  1. Inicializujte LLM, ktorý podporuje volanie funkcií:

    Nie všetky modely podporujú volanie funkcií, preto je dôležité skontrolovať, či váš LLM túto funkciu má. Azure OpenAI podporuje volanie funkcií. Môžeme začať inicializáciou OpenAI klienta voči Azure OpenAI Responses API (stabilný /openai/v1/ endpoint — bez potreby api_version).

     # Initialize the OpenAI client for Azure OpenAI (Responses API, v1 endpoint)
 client = OpenAI(
     base_url=f"{os.environ['AZURE_OPENAI_ENDPOINT'].rstrip('/')}/openai/v1/",
     api_key=os.environ["AZURE_OPENAI_API_KEY"],
 )
 deployment_name = os.environ["AZURE_OPENAI_DEPLOYMENT"]

  2. Vytvorte schému funkcie:

    Ďalej definujeme JSON schému, ktorá obsahuje názov funkcie, popis čo funkcia robí, a názvy a popisy parametrov funkcie. Túto schému potom odovzdáme klientovi vytvorenému predtým spolu s požiadavkou používateľa na zistenie času v San Franciscu. Dôležité je poznamenať, že volanie nástroja je to, čo sa vráti, nie konečná odpoveď na otázku. Ako už bolo spomenuté, LLM vráti názov funkcie, ktorú vybral na úlohu, a argumenty, ktoré mu budú odovzdané.

     # Function description for the model to read (Responses API flat tool format)
 tools = [
     {
         "type": "function",
         "name": "get_current_time",
         "description": "Get the current time in a given location",
         "parameters": {
             "type": "object",
             "properties": {
                 "location": {
                     "type": "string",
                     "description": "The city name, e.g. San Francisco",
                 },
             },
             "required": ["location"],
         },
     }
 ]

      
 # Initial user message
 messages = [{"role": "user", "content": "What's the current time in San Francisco"}]

 # First API call: Ask the model to use the function
 response = client.responses.create(
     model=deployment_name,
     input=messages,
     tools=tools,
     tool_choice="auto",
     store=False,
 )

 # The Responses API returns tool calls as function_call items in response.output.
 # Append them to the conversation so the model has full context on the next turn.
 messages += response.output

 print("Model's response:")
 print(response.output)
  

     Model's response:
 [ResponseFunctionToolCall(arguments='{"location":"San Francisco"}', call_id='call_pOsKdUlqvdyttYB67MOj434b', name='get_current_time', type='function_call')]

  3. Kód funkcie potrebný na vykonanie úlohy:

    Keď LLM vybral, ktorá funkcia sa má spustiť, treba implementovať a vykonať kód, ktorý úlohu vykoná. Môžeme implementovať kód na získanie aktuálneho času v jazyku Python. Tiež budeme potrebovať napísať kód na extrakciu názvu a argumentov z response_message na získanie konečného výsledku.

       def get_current_time(location):
     """Get the current time for a given location"""
     print(f"get_current_time called with location: {location}")  
     location_lower = location.lower()
        
     for key, timezone in TIMEZONE_DATA.items():
         if key in location_lower:
             print(f"Timezone found for {key}")  
             current_time = datetime.now(ZoneInfo(timezone)).strftime("%I:%M %p")
             return json.dumps({
                 "location": location,
                 "current_time": current_time
             })
      
     print(f"No timezone data found for {location_lower}")  
     return json.dumps({"location": location, "current_time": "unknown"})

     # Handle function calls
 tool_calls = [item for item in response.output if item.type == "function_call"]
 if tool_calls:
     for tool_call in tool_calls:
         if tool_call.name == "get_current_time":

             function_args = json.loads(tool_call.arguments)

             time_response = get_current_time(
                 location=function_args.get("location")
             )

             # Return the tool result as a function_call_output item
             messages.append({
                 "type": "function_call_output",
                 "call_id": tool_call.call_id,
                 "output": time_response,
             })
 else:
     print("No tool calls were made by the model.")

 # Second API call: Get the final response from the model
 final_response = client.responses.create(
     model=deployment_name,
     input=messages,
     tools=tools,
     store=False,
 )

 return final_response.output_text

       get_current_time called with location: San Francisco
   Timezone found for san francisco
   The current time in San Francisco is 09:24 AM.

Volanie funkcií je jadrom väčšiny, ak nie všetkých dizajnov používania nástrojov agentov, avšak jeho implementácia od základu môže byť niekedy náročná. Ako sme sa naučili v Lekcii 2, agentické rámce nám poskytujú predpripravené stavebné kamene na implementáciu používania nástrojov.

Príklady používania nástrojov s agentickými rámcami

Tu sú niektoré príklady, ako môžete implementovať dizajnový vzor používania nástrojov pomocou rôznych agentických rámcov:

Microsoft Agent Framework

Microsoft Agent Framework je open-source AI rámec na tvorbu AI agentov. Zjednodušuje proces používania volania funkcií tým, že umožňuje definovať nástroje ako Python funkcie s dekorátorom @tool. Rámec zabezpečuje komunikáciu medzi modelom a vašim kódom. Tiež poskytuje prístup k predpripraveným nástrojom, ako sú File Search a Code Interpreter cez FoundryChatClient.

Nasledujúci diagram ilustruje proces volania funkcií s Microsoft Agent Framework:

volanie funkcií

V Microsoft Agent Framework sú nástroje definované ako dekorované funkcie. Môžeme premeniť funkciu get_current_time, ktorú sme videli skôr, na nástroj použitím dekorátora @tool. Rámec automaticky serializuje funkciu a jej parametre a vytvorí schému na odoslanie do LLM.

import os
from agent_framework import tool
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

@tool(approval_mode="never_require")
def get_current_time(location: str) -> str:
    """Get the current time for a given location"""
    ...

# Create the client
provider = FoundryChatClient(
    project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=AzureCliCredential(),
)

# Create an agent and run with the tool
agent = provider.as_agent(name="TimeAgent", instructions="Use available tools to answer questions.", tools=get_current_time)
response = await agent.run("What time is it?")

Nástroje zo servera MCP

Nástroje nemusia byť funkcie vo vašom vlastnom kóde. Server, ktorý podporuje Model Context Protocol (MCP, rozpracovaný v Lekcii 11), publikuje svoje nástroje spolu so schémami a rámec ich môže načítať rovnakým spôsobom, ako serializuje dekorovanú funkciu. MCPStreamableHTTPTool sa pripája ku takémuto serveru cez HTTP, číta schémy nástrojov a ponúka ich modelu vedľa akýchkoľvek lokálnych nástrojov.

Príklad nižšie používa webový vyhľadávací server prevádzkovaný Keenable. Je zadarmo na použitie bez účtu alebo API kľúča (požiadavky sú limitované na IP), takže jedinými povereniami, ktoré potrebujete, sú tie pre váš model. Ako pri každom vzdialenom nástroji, dopyty, ktoré model vytvorí, sa odosielajú tomuto serveru.

from agent_framework import MCPStreamableHTTPTool

web_search = MCPStreamableHTTPTool(
    name="Keenable web search",
    url="https://api.keenable.ai/mcp",
)

# Connecting loads the server's tool schemas; the agent decides when to call them
async with web_search:
    agent = provider.as_agent(
        name="ResearchAgent",
        instructions="Use available tools to answer questions.",
        tools=[web_search],
    )
    response = await agent.run("What is new in the latest Python release?")
    print(response.text)

Server publikuje dva nástroje, search_web_pages a fetch_page_content. Keď je potrebná aktuálna informácia, model volá search_web_pages, dostane späť tituly, URL a textové úryvky a z nich vytvára odpoveď, rovnaký cyklus ako v príklade get_current_time vyššie.

Microsoft Foundry Agent Service

Microsoft Foundry Agent Service je novší agentický rámec navrhnutý tak, aby umožnil vývojárom bezpečne vytvárať, nasadzovať a škálovať kvalitné a rozšíriteľné AI agentov bez potreby správy základných výpočtových a úložných zdrojov. Je obzvlášť užitočný pre podnikové aplikácie, pretože je plne manažovaná služba s bezpečnosťou na úrovni podniku.

V porovnaní s vývojom priamo cez LLM API poskytuje Microsoft Foundry Agent Service niekoľko výhod, vrátane:

Nástroje dostupné v Microsoft Foundry Agent Service sa dajú rozdeliť do dvoch kategórií:

  1. Nástroje vedomostí:
  2. Nástroje akcií:

Agent Service nám umožňuje používať tieto nástroje spolu ako toolset. Tiež využíva threads, ktoré sledujú históriu správ z konkrétnej konverzácie.

Predstavte si, že ste obchodný zástupca v spoločnosti Contoso. Chcete vyvinúť konverzačného agenta, ktorý bude odpovedať na otázky o vašich predajných dátach.

Nasledujúci obrázok ilustruje, ako by ste mohli použiť Microsoft Foundry Agent Service na analýzu vašich predajných dát:

Agentická služba v akcii

Pre použitie ktoréhokoľvek z týchto nástrojov so službou môžeme vytvoriť klienta a definovať nástroj alebo nástrojový set. Na praktickú implementáciu môžeme použiť nasledujúci Python kód. LLM bude schopný pozrieť sa na nástrojový set a rozhodnúť, či použije používateľom vytvorenú funkciu fetch_sales_data_using_sqlite_query, alebo predpripravený Code Interpreter v závislosti od požiadavky používateľa.

import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from fetch_sales_data_functions import fetch_sales_data_using_sqlite_query # fetch_sales_data_using_sqlite_query function which can be found in a fetch_sales_data_functions.py file.
from azure.ai.projects.models import ToolSet, FunctionTool, CodeInterpreterTool

project_client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(),
    conn_str=os.environ["PROJECT_CONNECTION_STRING"],
)

# Initialize toolset
toolset = ToolSet()

# Initialize function calling agent with the fetch_sales_data_using_sqlite_query function and adding it to the toolset
fetch_data_function = FunctionTool(fetch_sales_data_using_sqlite_query)
toolset.add(fetch_data_function)

# Initialize Code Interpreter tool and adding it to the toolset. 
code_interpreter = CodeInterpreterTool()toolset.add(code_interpreter)

agent = project_client.agents.create_agent(
    model="gpt-5-mini", name="my-agent", instructions="You are helpful agent", 
    toolset=toolset
)

Aké sú špeciálne úvahy pri používaní dizajnového vzoru používania nástrojov na vytvorenie dôveryhodných AI agentov?

Bežnou obavou pri dynamicky generovanom SQL kóde LLM je bezpečnosť, obzvlášť riziko SQL injection alebo škodlivých akcií, ako vymazanie alebo manipulácia s databázou. Hoci tieto obavy sú opodstatnené, dajú sa účinne zmierniť správnou konfiguráciou prístupových práv k databáze. Pre väčšinu databáz to znamená nastavenie databázy do režimu len na čítanie. Pre databázové služby ako PostgreSQL alebo Azure SQL by mala byť aplikácii pridelená rola len na čítanie (SELECT).

Prevádzka aplikácie v bezpečnom prostredí ďalej zvyšuje ochranu. V podnikových scenároch sa údaje bežne extrahujú a transformujú z operačných systémov do databázy alebo dátového skladu len na čítanie s používateľsky prívetivou schémou. Tento prístup zaručuje, že dáta sú bezpečné, optimalizované pre výkon a prístupnosť a že aplikácia má obmedzený len čítací prístup.

Ukážkové kódy

Máte ďalšie otázky o dizajnovom vzore používania nástrojov?

Pridajte sa do Microsoft Foundry Discord, kde sa stretnete s inými študentmi, zúčastníte sa konzultačných hodín a získate odpovede na svoje otázky o AI agentoch.

Dodatočné zdroje

Základné testovanie tohto agenta (voliteľné)

Po tom, ako sa naučíte nasadzovať agentov v Lekcii 16, môžete základne otestovať TravelToolAgent z tejto lekcie (či stále volá svoje nástroje a odpovedá) pomocou tests/lesson-04-smoke-tests.json. Pozrite si tests/README.md pre návod, ako ho spustiť.

Predchádzajúca lekcia

Pochopenie agentných návrhových vzorov

Nasledujúca lekcia

Agentic RAG

Vyhlásenie o zodpovednosti: Tento dokument bol preložený pomocou AI prekladateľskej služby Co-op Translator. Hoci sa snažíme o presnosť, vezmite prosím na vedomie, že automatické preklady môžu obsahovať chyby alebo nepresnosti. Pôvodný dokument v jeho natívnom jazyku by mal byť považovaný za autoritatívny zdroj. Pre kritické informácie sa odporúča profesionálny ľudský preklad. Nie sme zodpovední za žiadne nedorozumenia alebo nesprávne interpretácie vyplývajúce z použitia tohto prekladu.

This site is open source. Improve this page.