ai-agents-for-beginners

Jak navrhnout dobré AI agenty

(Klikněte na obrázek výše pro zobrazení videa této lekce)

Vzor návrhu použití nástroje

Nástroje jsou zajímavé, protože AI agentům umožňují mít širší škálu schopností. Místo toho, aby agent měl omezenou sadu akcí, které může vykonat, přidáním nástroje může agent nyní provádět širokou škálu akcí. V této kapitole se podíváme na vzor návrhu použití nástroje, který popisuje, jak mohou AI agenti používat specifické nástroje k dosažení svých cílů.

Úvod

V této lekci se pokusíme odpovědět na následující otázky:

Cíle učení

Po dokončení této lekce budete schopni:

Co je vzor návrhu použití nástroje?

Vzor návrhu použití nástroje se zaměřuje na umožnění LLM interakce s externími nástroji k dosažení specifických cílů. Nástroje jsou kódy, které může agent spustit, aby provedl akce. Nástrojem může být jednoduchá funkce jako kalkulačka nebo volání API třetí strany, například kontrola ceny akcií nebo předpověď počasí. V kontextu AI agentů jsou nástroje navrženy tak, aby je agenti spouštěli v reakci na modely generované volání funkcí.

Na jaké případy použití lze tento vzor aplikovat?

AI agenti mohou využívat nástroje k dokončení složitých úkolů, získávání informací nebo rozhodování. Vzor návrhu použití nástroje se často používá ve scénářích vyžadujících dynamickou interakci s externími systémy, jako jsou databáze, webové služby nebo interprety kódu. Tato schopnost je užitečná pro různé případy použití, včetně:

Jaké jsou prvky/stavební kameny potřebné k implementaci vzoru použití nástroje?

Tyto stavební kameny umožňují AI agentovi plnit širokou škálu úkolů. Podívejme se na klíčové prvky potřebné k implementaci vzoru návrhu použití nástroje:

Dále si podrobněji probereme volání funkcí/nástrojů.

Volání funkcí/nástrojů

Volání funkcí je primární způsob, jak umožnit velkým jazykovým modelům (LLM) interagovat s nástroji. Často uvidíte výrazy „funkce“ a „nástroj“ používané zaměnitelně, protože „funkce“ (bloky znovupoužitelného kódu) jsou „nástroje“, které agenti používají k vykonávání úkolů. Aby mohla být spuštěna funkce, musí LLM porovnat požadavek uživatele s popisem funkcí. K tomu je odesláno schéma obsahující popisy všech dostupných funkcí. LLM poté vybere nejvhodnější funkci pro úkol a vrátí její název a argumenty. Vybraná funkce je spuštěna, její odpověď je odeslána zpět do LLM, které použije informace k odpovědi na požadavek uživatele.

Pro vývojáře, kteří chtějí implementovat volání funkcí pro agenty, budete potřebovat:

  1. LLM model, který podporuje volání funkcí
  2. Schéma obsahující popisy funkcí
  3. Kód pro každou popsanou funkci

Použijme příklad získání aktuálního času v nějakém městě jako ilustraci:

  1. Inicializujte LLM, které podporuje volání funkcí:

    Ne všechny modely volání funkcí podporují, proto je důležité zkontrolovat, zda to LLM, které používáte, dělá. Azure OpenAI podporuje volání funkcí. Můžeme začít inicializací OpenAI klienta vůči Azure OpenAI Responses API (stabilní endpoint /openai/v1/ — není třeba api_version).

     # Inicializujte klienta OpenAI pro Azure OpenAI (Responses API, koncový bod v1)
 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. Vytvořte schéma funkce:

    Dále definujeme JSON schéma, které obsahuje název funkce, popis toho, co funkce dělá, a názvy a popisy parametrů funkce. Toto schéma pak předáme klientovi vytvořenému dříve spolu s uživatelským požadavkem na zjištění času v San Franciscu. Co je důležité poznamenat, je to, že je vrácen volání nástroje, nikoliv konečná odpověď na otázku. Jak bylo zmíněno dříve, LLM vrátí název funkce, kterou vybral pro úkol, a argumenty, které jí budou předány.

     # Popis funkce pro načtení modelu (formát plochého nástroje Responses API)
 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"],
         },
     }
 ]

      
 # Počáteční uživatelská zpráva
 messages = [{"role": "user", "content": "What's the current time in San Francisco"}]

 # První API volání: Požádejte model, aby použil funkci
 response = client.responses.create(
     model=deployment_name,
     input=messages,
     tools=tools,
     tool_choice="auto",
     store=False,
 )

 # Responses API vrací volání nástrojů jako položky function_call v response.output.
 # Připojte je ke konverzaci, aby měl model plný kontext při dalším tahu.
 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 funkce potřebný k vykonání úkolu:

    Nyní, když LLM vybralo, kterou funkci spustit, je potřeba implementovat a vykonat kód, který úkol vykoná. Můžeme implementovat kód pro zjištění aktuálního času v Pythonu. Budeme také potřebovat napsat kód pro extrahování názvu a argumentů z response_message pro získání 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"})

     # Zpracovat volání funkcí
 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")
             )

             # Vrátit výsledek nástroje jako položku function_call_output
             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.")

 # Druhý API volání: Získat konečnou odpověď od modelu
 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.

Volání funkcí je jádrem většiny, pokud ne všech agentních použití nástrojů, ale jeho implementace od nuly může být někdy náročná. Jak jsme se naučili v Lekci 2, agentní rámce nám poskytují předpřipravené stavební kameny pro implementaci použití nástrojů.

Příklady použití nástroje s agentními rámci

Zde je několik příkladů, jak můžete implementovat vzor návrhu použití nástroje pomocí různých agentních rámců:

Microsoft Agent Framework

Microsoft Agent Framework je open-source AI rámec pro tvorbu AI agentů. Zjednodušuje proces používání volání funkcí tím, že umožňuje definovat nástroje jako Python funkce s dekorátorem @tool. Rámec zajišťuje obousměrnou komunikaci mezi modelem a vaším kódem. Nabízí také přístup k předpřipraveným nástrojům jako File Search a Code Interpreter přes FoundryChatClient.

Následující diagram znázorňuje proces volání funkcí v Microsoft Agent Framework:

function calling

V Microsoft Agent Framework jsou nástroje definovány jako dekorované funkce. Můžeme převést funkci get_current_time, kterou jsme viděli dříve, na nástroj použitím dekorátoru @tool. Rámec automaticky serializuje funkci a její parametry, vytváří schéma pro odeslání 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"""
    ...

# Vytvořit klienta
provider = FoundryChatClient(
    project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=AzureCliCredential(),
)

# Vytvořit agenta a spustit nástrojem
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?")

Microsoft Foundry Agent Service

Microsoft Foundry Agent Service je novější agentní rámec, navržený pro umožnění vývojářům bezpečně vytvářet, nasazovat a škálovat vysoce kvalitní a rozšiřitelné AI agenty bez nutnosti spravovat základní výpočetní a úložné zdroje. Je zvláště vhodný pro podnikové aplikace, protože je plně spravovaná služba s bezpečností na úrovni podniku.

V porovnání s vývojem přímo pomocí LLM API poskytuje Microsoft Foundry Agent Service některé výhody, včetně:

Nástroje dostupné v Microsoft Foundry Agent Service lze rozdělit do dvou kategorií:

  1. Nástroje znalostí:
  2. Akční nástroje:

Agent Service nám umožňuje používat tyto nástroje společně jako sadu nástrojů. Také využívá vlákna, která sledují historii zpráv z konkrétní konverzace.

Představte si, že jste obchodní agent ve firmě Contoso. Chcete vyvinout konverzačního agenta, který může odpovídat na otázky o vašich prodejních datech.

Následující obrázek znázorňuje, jak byste mohli použít Microsoft Foundry Agent Service k analýze vašich prodejních dat:

Agentní služba v akci

Pro použití těchto nástrojů se službou můžeme vytvořit klienta a definovat nástroj nebo sadu nástrojů. K praktické implementaci můžeme použít následující Python kód. LLM bude schopné nahlédnout na sadu nástrojů a rozhodnout, zda použije uživatelem vytvořenou funkci fetch_sales_data_using_sqlite_query nebo předpřipravený Code Interpreter v závislosti na uživatelské žádosti.

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 # funkce fetch_sales_data_using_sqlite_query, kterou najdete v souboru fetch_sales_data_functions.py.
from azure.ai.projects.models import ToolSet, FunctionTool, CodeInterpreterTool

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

# Inicializovat nástroje
toolset = ToolSet()

# Inicializovat agenta volajícího funkce s функí fetch_sales_data_using_sqlite_query a přidat ji do nástrojů
fetch_data_function = FunctionTool(fetch_sales_data_using_sqlite_query)
toolset.add(fetch_data_function)

# Inicializovat nástroj Code Interpreter a přidat ho do nástrojů.
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
)

Jaká jsou zvláštní opatření pro použití vzoru návrhu použití nástroje k vytvoření důvěryhodných AI agentů?

Častou obavou u SQL dynamicky generovaného LLM je bezpečnost, zejména riziko SQL injekce nebo škodlivých akcí, jako je odstranění nebo úprava databáze. I když jsou tyto obavy oprávněné, lze je účinně zmírnit správným nastavením oprávnění přístupu k databázi. U většiny databází to zahrnuje nastavení databáze jako pouze pro čtení. U databázových služeb jako PostgreSQL nebo Azure SQL by měla mít aplikace přiřazenou roli pouze pro čtení (SELECT).

Spuštění aplikace v zabezpečeném prostředí dále zvyšuje ochranu. V podnikových scénářích se data typicky extrahují a transformují z provozních systémů do databáze nebo datového skladu pouze pro čtení s uživatelsky přívětivým schématem. Tento přístup zajišťuje, že data jsou bezpečná, optimalizovaná pro výkon a přístupnost, a že aplikace má omezený, jen pro čtení přístup.

Ukázkové kódy

Máte další otázky ohledně vzoru návrhu použití nástroje?

Připojte se k Microsoft Foundry Discord, kde se můžete setkat s dalšími studenty, zúčastnit se konzultací a získat odpovědi na své otázky o AI agentech.

Dodatečné zdroje

Rychlý test tohoto agenta (volitelné)

Poté, co se naučíte nasazovat agenty v Lekci 16, můžete rychle otestovat TravelToolAgent z této lekce (zda stále volá své nástroje a odpovídá) pomocí tests/lesson-04-smoke-tests.json. Viz tests/README.md pro návod, jak jej spustit.

Předchozí lekce

Porozumění agentním návrhovým vzorům

Následující lekce

Agentní RAG

Prohlášení o omezení odpovědnosti: Tento dokument byl přeložen pomocí AI překladatelské služby Co-op Translator. Přestože usilujeme o co největší přesnost, mějte prosím na paměti, že automatizované překlady mohou obsahovat chyby nebo nepřesnosti. Originální dokument v jeho mateřském jazyce by měl být považován za autoritativní zdroj. Pro kritické informace se doporučuje profesionální lidský překlad. Nejsme odpovědní za jakékoli nedorozumění nebo nesprávné interpretace vzniklé použitím tohoto překladu.

This site is open source. Improve this page.