ai-agents-for-beginners

Kako oblikovati dobre AI agente

(Kliknite zgornjo sliko za ogled videa te lekcije)

Vzorec oblikovanja uporabe orodij

Orodja so zanimiva, ker omogočajo AI agentom širši nabor zmogljivosti. Namesto da bi imel agent omejen nabor dejanj, ki jih lahko izvede, lahko z dodajanjem orodja agent zdaj opravlja širok spekter dejanj. V tem poglavju si bomo ogledali Vzorec oblikovanja uporabe orodij, ki opisuje, kako lahko AI agenti uporabljajo določena orodja za doseganje svojih ciljev.

Uvod

V tej lekciji želimo odgovoriti na naslednja vprašanja:

Cilji učenja

Po zaključku te lekcije boste znali:

Kaj je vzorec oblikovanja uporabe orodij?

Vzorec oblikovanja uporabe orodij se osredotoča na omogočanje LLM-jem, da komunicirajo z zunanjimi orodji za doseganje specifičnih ciljev. Orodja so koda, ki jo lahko agent izvede za opravljanje dejanj. Orodje je lahko preprosta funkcija, kot je kalkulator, ali klic API-ja do zunanje storitve, kot je poizvedba o ceni delnic ali vremenska napoved. V kontekstu AI agentov so orodja zasnovana tako, da jih agenti izvajajo kot odgovor na klice funkcij, ki jih generira model.

Za katere primere uporabe ga lahko uporabimo?

AI agenti lahko izkoristijo orodja za dokončanje kompleksnih nalog, pridobivanje informacij ali sprejemanje odločitev. Vzorec uporabe orodij se pogosto uporablja v scenarijih, kjer je potrebna dinamična interakcija z zunanjimi sistemi, kot so baze podatkov, spletne storitve ali tolmači kode. Ta sposobnost je uporabna za številne primere uporabe, med drugim:

Kateri so elementi/gradniki, potrebni za implementacijo vzorca uporabe orodij?

Ti gradniki omogočajo AI agentu, da opravi širok spekter nalog. Oglejmo si ključne elemente, potrebne za implementacijo vzorca uporabe orodij:

Naslednje si oglejmo podrobneje klice funkcij/orodij.

Klicanje funkcij/orodij

Klic funkcije je glavni način, s katerim omogočimo velikim jezikovnim modelom (LLM), da komunicirajo z orodji. Pogosto boste videli, da se ‘funkcija’ in ‘orodje’ uporabljata izmenično, ker so ‘funkcije’ (bloki ponovno uporabne kode) orodja, ki jih agenti uporabljajo za opravljanje nalog. Da se lahko koda funkcije pokliče, mora LLM primerjati uporabnikovo zahtevo z opisom funkcije. Za to se pošlje shema, ki vsebuje opise vseh razpoložljivih funkcij LLM-ju. LLM nato izbere najprimernejšo funkcijo za nalogo in vrne njeno ime ter argumente. Izbrana funkcija se pokliče, njen odgovor se pošlje nazaj LLM-ju, ki informacije uporabi za odgovor uporabniku.

Za razvoj funkcionalnosti klicanja funkcij za agente boste potrebovali:

  1. Model LLM, ki podpira klic funkcij
  2. Shemo z opisi funkcij
  3. Kodo za vsako opisano funkcijo

Uporabimo primer pridobivanja trenutnega časa v mestu za ilustracijo:

  1. Inicializacija LLM, ki podpira klic funkcij:

    Ne vsi modeli podpirajo klic funkcij, zato je pomembno preveriti, ali vaš LLM to omogoča. Azure OpenAI podpira klic funkcij. Začnemo lahko z zagonom OpenAI odjemalca proti storitvi Azure OpenAI Responses API (stabilna pot /openai/v1/ — ni potreben api_version).

     # Inicializirajte OpenAI odjemalca za Azure OpenAI (API za odgovore, v1 končna točka)
 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. Ustvarite shemo funkcije:

    Nato definiramo JSON shemo, ki vsebuje ime funkcije, opis, kaj funkcija počne, ter imena in opise funkcijskih parametrov. To shemo pošljemo prej ustvarjenemu odjemalcu skupaj z uporabnikovo zahtevo za čas v San Franciscu. Pomembno je poudariti, da je vrnjen klic orodja, ne končni odgovor na vprašanje. Kot smo že omenili, LLM vrne ime funkcije, ki jo je izbral za nalogo, in argumente, ki jih bo prejel.

     # Opis funkcije za branje modela (format orodja API za odzive v ravni obliki)
 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"],
         },
     }
 ]

      
 # Začetno sporočilo uporabnika
 messages = [{"role": "user", "content": "What's the current time in San Francisco"}]

 # Prvi klic API-ja: Prosite model, da uporabi funkcijo
 response = client.responses.create(
     model=deployment_name,
     input=messages,
     tools=tools,
     tool_choice="auto",
     store=False,
 )

 # API za odgovore vrne klice orodij kot elemente function_call v response.output.
 # Dodajte jih v pogovor, da ima model popoln kontekst v naslednjem koraku.
 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. Koda funkcije, potrebna za izvedbo naloge:

    Ko LLM izbere, katera funkcija se mora izvesti, je potrebno implementirati in izvesti kodo, ki opravilo izvede. Kodo za pridobivanje trenutnega časa lahko napišemo v Pythonu. Prav tako moramo napisati kodo za izluščitev imena in argumentov iz response_message za dobitev končnega rezultata.

       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"})

     # Ravnajte s klici funkcij
 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")
             )

             # Vrni rezultat orodja kot element 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.")

 # Drugi klic API-ja: Pridobite končni odgovor modela
 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.

Klic funkcij je jedro večine, če ne vseh vzorcev uporabe orodij pri agentih, vendar je njegova implementacija iz nič pogosto izziv. Kot smo se naučili v Lekcija 2 nam agenti okviri ponujajo predpripravljene gradnike za implementacijo uporabe orodij.

Primeri uporabe orodij z agentnimi okviri

Tukaj je nekaj primerov, kako lahko izvedete vzorec uporabe orodij z različnimi agentnimi okviri:

Microsoft Agent Framework

Microsoft Agent Framework je odprtokodni AI okvir za gradnjo AI agentov. Poenostavi proces uporabe klica funkcij z možnostjo definiranja orodij kot Python funkcij z dekoratorjem @tool. Okvir upravlja komunikacijo med modelom in vašo kodo. Prav tako omogoča dostop do predpripravljenih orodij, kot sta File Search in Code Interpreter prek FoundryChatClient.

Naslednji diagram ponazarja proces klica funkcij z Microsoft Agent Framework:

klic funkcije

V Microsoft Agent Framework so orodja definirana kot dekorirane funkcije. Funkcijo get_current_time, ki smo jo videli prej, lahko pretvorimo v orodje z dekoratorjem @tool. Okvir bo samodejno serializiral funkcijo in njene parametre ter ustvaril shemo za pošiljanje LLM-ju.

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"""
    ...

# Ustvari odjemalca
provider = FoundryChatClient(
    project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=AzureCliCredential(),
)

# Ustvari agenta in ga zaženi s orodjem
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 novejši agentni okvir, zasnovan za omogočanje razvijalcem varne gradnje, uvajanja in razširitve visokokakovostnih in razširljivih AI agentov brez potrebe po upravljanju osnovnih računalniških in shranjevalnih virov. Še posebej koristen je za podjetniške aplikacije, saj gre za popolnoma upravljano storitev z varnostjo na podjetniški ravni.

V primerjavi z razvojem neposredno prek LLM API-ja, Microsoft Foundry Agent Service ponuja nekaj prednosti, med drugim:

Orodja, na voljo v Microsoft Foundry Agent Service, lahko razdelimo v dve kategoriji:

  1. Orodja za znanje:
  2. Orodja za delovanje:

Agent Service nam omogoča uporabo teh orodij skupaj kot orodjarno. Prav tako uporablja niti, ki beležijo zgodovino sporočil posameznega pogovora.

Predstavljajte si, da ste prodajni agent v podjetju Contoso. Želite razviti pogovornega agenta, ki zna odgovarjati na vprašanja o vaših prodajnih podatkih.

Naslednja slika prikazuje, kako lahko uporabite Microsoft Foundry Agent Service za analizo prodajnih podatkov:

Agentna storitev v akciji

Za uporabo katerega koli izmed teh orodij s storitvijo lahko ustvarimo odjemalca in definiramo orodje ali orodjarno. Za praktično izvedbo lahko uporabimo naslednjo Python kodo. LLM bo lahko pogledal orodjarno in odločil, ali bo uporabil uporabniško funkcijo fetch_sales_data_using_sqlite_query ali predpripravljeni Tolmač kode, odvisno od uporabnikove zahteve.

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 funkcija, ki jo najdete v datoteki 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"],
)

# Inicializiraj orodja
toolset = ToolSet()

# Inicializiraj agent za klic funkcij s funkcijo fetch_sales_data_using_sqlite_query in jo dodaj k orodjem
fetch_data_function = FunctionTool(fetch_sales_data_using_sqlite_query)
toolset.add(fetch_data_function)

# Inicializiraj orodje za interpretacijo kode in ga dodaj k orodjem.
code_interpreter = CodeInterpreterTool()toolset.add(code_interpreter)

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

Katere so posebne premisleke pri uporabi vzorca uporabe orodij za gradnjo zaupanja vrednih AI agentov?

Pogosta skrb pri dinamično generirani SQL kodi z LLM-ji je varnost, zlasti tveganje za SQL injekcije ali zlonamerna dejanja, kot so brisanje ali spreminjanje baze podatkov. Čeprav so te skrbi na mestu, jih je mogoče učinkovito ublažiti z ustrezno konfiguracijo dovoljenj za dostop do baze podatkov. Za večino baz podatkov to vključuje nastavitev baze v način samo za branje. Za baze podatkov, kot sta PostgreSQL ali Azure SQL, naj bo aplikaciji dodeljena vloga samo za branje (SELECT).

Zagon aplikacije v varnem okolju še dodatno izboljša zaščito. V podjetniških scenarijih se podatki običajno ekstrahirajo in transformirajo iz operativnih sistemov v bazo podatkov ali podatkovno skladišče samo za branje z uporabniku prijazno shemo. Tak pristop zagotavlja, da so podatki varni, optimizirani za zmogljivost in dostopnost ter da ima aplikacija omejen, samo za branje dostop.

Primeri kode

Imate več vprašanj o vzorcu uporabe orodij?

Pridružite se Microsoft Foundry Discord, kjer se lahko srečate z drugimi učenci, udeležite ur uradne podpore in dobite odgovore na vprašanja o AI agentih.

Dodatni viri

Osnovno testiranje tega agenta (neobvezno)

Ko se naučite nameščati agente v Lekcija 16, lahko z osnovnim testiranjem preverite TravelToolAgent iz te lekcije (ali še vedno kliče svoje orodje in odgovarja?) s tests/lesson-04-smoke-tests.json. Oglejte si tests/README.md za navodila, kako ga zagnati.

Prejšnja lekcija

Razumevanje agentnih oblikovalskih vzorcev

Naslednja lekcija

Agentic RAG

Omejitev odgovornosti: Ta dokument je bil preveden z uporabo AI prevajalske storitve Co-op Translator. Čeprav si prizadevamo za natančnost, vas prosimo, da upoštevate, da avtomatizirani prevodi lahko vsebujejo napake ali netočnosti. Izvirni dokument v njegovem izvirnem jeziku je treba obravnavati kot avtoritativni vir. Za kritične informacije je priporočljiv strokovni človeški prevod. Ne odgovarjamo za morebitna nesporazume ali napačne interpretacije, ki izhajajo iz uporabe tega prevoda.

This site is open source. Improve this page.