ai-agents-for-beginners

(Bonyeza picha hapo juu kuangalia video ya somo hili)

Muundo wa Matumizi ya Zana

Vifaa ni vya kufurahisha kwa sababu vinamwezesha wakala wa AI kuwa na uwezo mpana zaidi. Badala ya wakala kuwa na seti ndogo ya vitendo anavyoweza kufanya, kwa kuongeza kifaa, wakala sasa anaweza kufanya vitendo vingi. Katika sura hii, tutaangalia Muundo wa Matumizi ya Zana, unaoelezea jinsi wakala wa AI wanavyoweza kutumia zana maalum kufanikisha malengo yao.

Utangulizi

Katika somo hili, tunajaribu kujibu maswali yafuatayo:

• Muundo wa matumizi ya zana ni nini?
• Matumizi gani yanaweza kutumika?
• Ni vipengele/vinara vipi vinavyohitajika kutekeleza muundo huu?
• Ni mambo gani maalum yanayohitajika kwa kutumia Muundo wa Matumizi ya Zana ili kujenga wakala wa AI wanaoweza kuaminika?

Malengo ya Kujifunza

Baada ya kukamilisha somo hili, utaweza:

• Eleza Muundo wa Matumizi ya Zana na kusudi lake.
• Tambua matumizi ambapo Muundo wa Matumizi ya Zana unaweza kutumika.
• Elewa vipengele muhimu vinavyohitajika kutekeleza muundo huu.
• Tambua mambo yanayotakiwa kufikiriwa ili kuhakikisha wakala wa AI wanaaminika wanapotumia muundo huu.

Muundo wa Matumizi ya Zana ni nini?

Muundo wa Matumizi ya Zana unaangazia kuwapa LLM uwezo wa kuingiliana na zana za nje kufanikisha malengo maalum. Zana ni msimbo unaoweza kutekelezwa na wakala kufanya vitendo. Kifaa kinaweza kuwa kazi rahisi kama kalkuleta, au wito wa API kwa huduma ya mkono wa tatu kama vile kutafuta bei ya hisa au hali ya hewa. Katika muktadha wa wakala wa AI, zana zimeundwa kutekelezwa na wakala kama majibu kwa miito ya kazi inayotokana na mfano.

Matumizi gani yanaweza kutumika?

Wakala wa AI wanaweza kutumia zana kukamilisha kazi ngumu, kupata habari, au kufanya maamuzi. Muundo wa matumizi ya zana hutumika mara nyingi katika hali zinazohitaji maingiliano ya nguvu na mifumo ya nje, kama vile hifadhidata, huduma za wavuti, au tafsiri za msimbo. Uwezo huu ni muhimu kwa matumizi mbalimbali kama:

• Kupata Habari kwa Kasi: Wakala wanaweza kuuliza API za nje au hifadhidata kupata data mpya (mfano, kuuliza hifadhidata ya SQLite kwa uchambuzi wa data, kupata bei ya hisa au taarifa ya hali ya hewa).
• Utekelezaji na Tafsiri ya Msimbo: Wakala wanaweza kuendesha misimbo au skripti kutatua matatizo ya hesabu, kutoa ripoti, au kufanya maonesho.
• Otomatiki ya Mchakato wa Kazi: Kuendesha mchakato wa kazi ya kurudia au wa hatua nyingi kwa kuunganisha zana kama ratiba za kazi, huduma za barua pepe, au mitiririko ya data.
• Huduma kwa Wateja: Wakala wanaweza kuingiliana na mifumo ya CRM, majukwaa ya tiketi, au misingi ya maarifa kutatua maswali ya watumiaji.
• Uundaji na Uhariri wa Yaliyomo: Wakala wanaweza kutumia zana kama wakaguzi wa sarufi, muhtasari wa maandishi, au washauri wa usalama wa yaliyomo kusaidia katika kazi za uundaji yaliyomo.

Vipengele/vinara vinavyohitajika kutekeleza muundo wa matumizi ya zana

Vipengele hivi vinamwezesha wakala wa AI kufanya kazi nyingi. Haya ni vipengele muhimu vinavyohitajika kutekeleza Muundo wa Matumizi ya Zana:

• Mipango ya Kazi/Zana: Maelezo ya kina ya zana zinazopatikana, ikiwa ni pamoja na jina la kazi, kusudi, vigezo vinavyohitajika, na matokeo yanayotarajiwa. Mipango hii inamruhusu LLM kuelewa zana zilizo tayari na jinsi ya kuunda maombi halali.

• Mantiki ya Utekelezaji wa Kazi: Inasimamia jinsi na lini zana zinapotumika kulingana na nia ya mtumiaji na muktadha wa mazungumzo. Hii inaweza kujumuisha moduli za mpango, mifumo ya usambazaji, au mtiririko wa masharti unaotambua matumizi ya zana kwa wakati halisi.

• Mfumo wa Kudhibiti Ujumbe: Vipengele vinavyosimamia mtiririko wa mazungumzo kati ya maingizo ya mtumiaji, majibu ya LLM, miito ya zana, na matokeo ya zana.

• Muunganisho wa Zana: Miundombinu inayounganisha wakala na zana mbalimbali, iwe ni kazi rahisi au huduma za nje ngumu.

• Usimamizi wa Makosa na Uhakiki: Mbinu za kushughulikia makosa katika utekelezaji wa zana, kuthibitisha vigezo, na kudhibiti majibu yasiyotegemewa.

• Usimamizi wa Hali: Kufuatilia muktadha wa mazungumzo, mwingiliano ya awali ya zana, na data inayodumu ili kuhakikisha uthabiti katika mazungumzo yenye mizunguko mingi.

Sasa, tuangalie kwa undani zaidi kuhusu Kupigia Simu Kazi/Zana.

Kupigia Simu Kazi/Zana

Kupigia simu kazi ndiyo njia kuu tunayowawezesha Mifano Mikubwa ya Lugha (LLMs) kuingiliana na zana. Mara nyingi utaona maneno ‘Kazi’ na ‘Kifaa’ yakitumiwa kwa muktadha mmoja kwa sababu ‘kazi’ (viepengo vya msimbo vinavyoweza kutumika tena) ndiyo ‘zana’ wakala wanazitumia kufanya kazi. Ili msimbo wa kazi ipigwe simu, LLM lazima linganishe ombi la mtumiaji na maelezo ya kazi. Hili hufanyika kwa kutumia muundo unaoelezea kazi zote zinazopatikana ambao hutumwa kwa LLM. Kisha LLM huchagua kazi inayofaa zaidi kwa kazi na kurudisha jina na hoja zake. Kazi iliyochaguliwa hupigiwa simu, jibu lake hurudishwa kwa LLM, ambalo hutumia taarifa hiyo kujibu ombi la mtumiaji.

Kwa waendelezaji kutekeleza kupigia simu kazi kwa wakala, utahitaji:

1. Mfano wa LLM unaounga mkono kupigia simu kazi
2. Muundo unaoeleza kazi
3. Msimbo wa kila kazi ulioelezwa

Tuchukue mfano wa kupata wakati wa sasa katika mji kama maelezo:

1. Anzisha LLM unaounga mkono kupigia simu kazi:

   Sio modeli zote zinazounga mkono kupigia simu kazi, hivyo ni muhimu kuangalia kama LLM unayotumia inaunga mkono. Azure OpenAI inaunga mkono kupigia simu kazi. Tunaweza kuanza kwa kuanzisha mteja wa OpenAI dhidi ya Azure OpenAI API ya Majibu (muktadha thabiti wa /openai/v1/ — hauna haja ya api_version).

    # Anzisha mteja wa OpenAI kwa ajili ya Azure OpenAI (API ya Majibu, mwisho wa 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. Tengeneza Muundo wa Kazi:

   Sasa tutaeleza muundo wa JSON unaoelezea jina la kazi, maelezo ya kazi inavyofanya, na majina pamoja na maelezo ya vigezo vya kazi hiyo. Kisha tutapeleka muundo huu kwa mteja tuliyemuumba awali, pamoja na ombi la mtumiaji kupata wakati katika San Francisco. Muhimu kuelewa ni kwamba miito ya zana ndiyo huletwa, sio jibu la mwisho la swali. Kama ilivyosemwa awali, LLM hurejesha jina la kazi iliyochaguliwa na hoja zitakazotumwa kwa kazi hiyo.

    # Maelezo ya kazi kwa mfano kusoma (Muundo wa zana tambarare za API za Majibu)
    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"],
            },
        }
    ]
   

     
    # Ujumbe wa mwanzo wa mtumiaji
    messages = [{"role": "user", "content": "What's the current time in San Francisco"}]
   
    # Kuitisha API kwa mara ya kwanza: Muulize modeli itumie kazi hiyo
    response = client.responses.create(
        model=deployment_name,
        input=messages,
        tools=tools,
        tool_choice="auto",
        store=False,
    )
   
    # API ya Majibu hurudisha kuitwa kwa zana kama vitu vya function_call katika response.output.
    # Ziambatisha kwenye mazungumzo ili modeli iwe na muktadha kamili katika zamu inayofuata.
    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. Msimbo wa kazi unaohitajika kutekeleza kazi:

   Sasa LLM imethibitisha kazi inayohitajika kufanyika, msimbo unaotekeleza kazi hiyo lazima uandikwe na utekelezwe. Tunaweza kuandika msimbo wa kupata wakati wa sasa kwa Python. Pia tutahitaji kuandika msimbo wa kutoa jina na hoja kutoka kwa response_message kupata matokeo ya mwisho.

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

    # Shughulikia miito ya kazi
    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")
                )
   
                # Rudisha matokeo ya zana kama kipengee cha 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.")
   
    # Mwito wa pili wa API: Pata jibu la mwisho kutoka kwa mfano
    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.
   

Kupigia simu kazi ni kiini cha muundo mzima wa matumizi ya zana za wakala, hata hivyo kuutekeleza kutoka mwanzo kunaweza kuwa changamoto wakati mwingine. Kama tulivyojifunza katika Somo la 2 mifumo ya wakala hutupatia vipengele vilivyotengenezwa tayari kutekeleza matumizi ya zana.

Mifano ya Matumizi ya Zana na Mifumo ya Wakala

Hapa kuna mifano ya jinsi unavyoweza kutekeleza Muundo wa Matumizi ya Zana kwa kutumia mifumo tofauti ya wakala:

Mfumo wa Microsoft Agent

Mfumo wa Microsoft Agent ni mfumo wa AI wa chanzo huria kwa ajili ya kujenga wakala wa AI. Unarahisisha mchakato wa kupigia simu kazi kwa kuruhusu ueleze zana kama kazi za Python zilizo na @tool halisi. Mfumo husimamia mawasiliano ya zamu mbili kati ya mfano na msimbo wako. Pia unatoa zana zilizotengenezwa tayari kama Utafutaji wa Faili na Mtafiti wa Msimbo kupitia FoundryChatClient.

Mchoro ufuatao unaonyesha mchakato wa kupigia simu kazi kwa Mfumo wa Microsoft Agent:

Katika Mfumo wa Microsoft Agent, zana zinafafanuliwa kama kazi zilizo na alama maalum. Tunaweza kubadilisha kazi get_current_time tuliyoiangalia kabla na kuitengeneza kuwa kifaa kwa kutumia @tool halisi. Mfumo uta serialize kazi na vigezo vyake moja kwa moja, ukitengeneza muundo wa kupeleka kwa 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"""
    ...

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

# Unda wakala na uendeshe na chombo hicho
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?")

Huduma ya Microsoft Foundry Agent

Huduma ya Microsoft Foundry Agent ni mfumo mpya wa wakala ulioundwa kuwawezesha waendelezaji kujenga, kupeleka, na kupanua wakala wa AI wa hali ya juu kwa usalama bila hitaji la kusimamia rasilimali za kompyuta na hifadhi za msingi. Ni muhimu hasa kwa maombi ya biashara kwa kuwa ni huduma inayosimamiwa kikamilifu na usalama wa ngazi ya biashara.

Ukiwa ukilinganisha na maendeleo kwa API ya LLM moja kwa moja, Huduma ya Microsoft Foundry Agent hutoa faida kadhaa, ikiwa ni pamoja na:

• Kupigia simu zana kiotomatiki – huna haja ya kutafsiri simu ya zana, kuituma, na kushughulikia majibu; yote haya hufanywa sehemu ya seva
• Usimamizi salama wa data – badala ya kusimamia hali ya mazungumzo kwa mikono, unaweza kutumia ‘ftuufu’ kuhifadhi taarifa zote unazohitaji
• Zana zilizotengenezwa tayari – Zana za kuingiliana na vyanzo vyako vya data kama Bing, Azure AI Search, na Azure Functions.

Zana zinazopatikana katika Huduma ya Microsoft Foundry Agent zinaweza kugawanywa katika makundi mawili:

1. Zana za Maarifa:
   • Msingi na Bing Search
   • Utafutaji wa Faili
   • Azure AI Search
2. Zana za Vitendo:
   • Kupigia Simu Kazi
   • Mtafiti wa Msimbo
   • Zana Zilizoundwa kwa OpenAPI
   • Azure Functions

Huduma ya Wakala inatupa uwezo wa kutumia zana hizi pamoja kama seti ya zana. Pia inatumia ftuufu ambazo hufuata historia ya ujumbe kutoka kwa mazungumzo maalum.

Fikiria wewe ni wakala wa mauzo katika kampuni inayoitwa Contoso. Unataka kuunda wakala wa mazungumzo unaoweza kujibu maswali kuhusu data zako za mauzo.

Picha ifuatayo inaonyesha jinsi unavyoweza kutumia Huduma ya Microsoft Foundry Agent kuchambua data zako za mauzo:

Ili kutumia zana yoyote ya huduma hii tunaweza kuunda mteja na kufafanua kifaa au seti ya zana. Kutekeleza hili kimkakati tunaweza kutumia msimbo wa Python ulio hapa chini. LLM itakuwa na uwezo wa kuangalia seti ya zana na kuamua ikiwa itatumia kazi iliyoundwa na mtumiaji, fetch_sales_data_using_sqlite_query, au Mtafiti wa Msimbo aliyejengwa tayari kulingana na ombi la mtumiaji.

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 # kipengele cha fetch_sales_data_using_sqlite_query kinachopatikana katika faili la 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"],
)

# Anzisha seti ya zana
toolset = ToolSet()

# Anzisha wakala wa kupiga simu za kazi ukitumia kipengele cha fetch_sales_data_using_sqlite_query na kuingiza kwenye seti ya zana
fetch_data_function = FunctionTool(fetch_sales_data_using_sqlite_query)
toolset.add(fetch_data_function)

# Anzisha zana ya Mfasiri wa Msimbo na kuiingiza kwenye seti ya zana.
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
)

Ni mambo gani maalum yanayochukuliwa kwa kutumia Muundo wa Matumizi ya Zana kujenga wakala wa AI wanaoweza kuaminika?

Wasiwasi wa kawaida unaohusiana na SQL inayotengenezwa kwa nguvu na LLM ni usalama, hasa hatari ya sindano ya SQL au vitendo vya kuharibu, kama kufuta au kubadilisha hifadhidata. Ingawa wasiwasi huu ni halali, unaweza kupunguzwa kwa ufanisi kwa kusanidi vibali vya upatikanaji kwa hifadhidata ipasavyo. Kwa hifadhidata nyingi hii inahusisha kusanidi hifadhidata kuwa ya kusoma tu. Kwa huduma za hifadhidata kama PostgreSQL au Azure SQL, programu inapaswa kupewa jukumu la kusoma tu (SELECT).

Kuendesha programu katika mazingira ya usalama zaidi huongeza ulinzi zaidi. Katika mazingira ya biashara, data kawaida hutolewa na kubadilishwa kutoka kwa mifumo ya uendeshaji kwenda hifadhidata au ghala la data la kusoma tu lenye muundo wa kirafiki kwa mtumiaji. Njia hii huhakikisha data iko salama, imesanifiwa kwa utendaji na upatikanaji, na programu inaweza kupata data kwa njia ya kusoma tu kwa mujibu wa vikwazo vilivyowekwa.

Mifano ya Msimbo

• Python: Mfumo wa Wakala
• .NET: Mfumo wa Wakala

Je, Una Maswali Zaidi Kuhusu Mipango ya Matumizi ya Zana?

Jiunge na Microsoft Foundry Discord ili kukutana na wanafunzi wengine, kuhudhuria saa za ofisi na kupata majibu ya maswali yako kuhusu Wakala wa AI.

Rasilimali Zaidi

• Warsha ya Huduma ya Wakala wa Azure AI
• Warsha ya Waandishi wa Uumbaji wa Contoso Multi-Agent
• Muhtasari wa Mfumo wa Microsoft Agent

Kupima Haraka Wakala Huyu (Hiari)

Baada ya kujifunza kuweka maajenti kazi katika Somo la 16, unaweza kupima haraka TravelToolAgent wa somo hili (je, bado inaita vyombo vyake na kujibu?) kwa kutumia tests/lesson-04-smoke-tests.json. Angalia tests/README.md kujifunza jinsi ya kuendesha.

Somo Lililopita

Kuelewa Mifumo ya Ubunifu wa Ajenti

Somo Linalofuata

Agentic RAG

---

Kionyozo: Hati hii imetafsiriwa kwa kutumia huduma ya tafsiri ya AI Co-op Translator. Ingawa tunajitahidi kupata usahihi, tafadhali fahamu kwamba tafsiri za kiotomatiki zinaweza kuwa na makosa au upungufu wa usahihi. Hati ya asili katika lugha yake halisi inapaswa kuchukuliwa kama chanzo cha mamlaka. Kwa taarifa muhimu, tafsiri ya kitaalamu inayofanywa na binadamu inapendekezwa. Hatutojibu kwa kuelewa vibaya au tafsiri potofu zinazotokea kutokana na matumizi ya tafsiri hii.

This site is open source. Improve this page.