ai-agents-for-beginners

Как да проектираме добри AI агенти

(Кликнете върху изображението по-горе, за да гледате видео на този урок)

Дизайнерски шаблон за използване на инструменти

Инструментите са интересни, защото позволяват на AI агентите да имат по-широк набор от възможности. Вместо агентът да има ограничен набор от действия, които може да изпълнява, чрез добавяне на инструмент агентът сега може да извършва широк набор от действия. В тази глава ще разгледаме дизайна на шаблона за използване на инструменти, който описва как AI агентите могат да използват конкретни инструменти, за да постигнат своите цели.

Въведение

В този урок ще се опитаме да отговорим на следните въпроси:

Цели на обучението

След завършване на този урок ще можете да:

Какво е дизайна на шаблона за използване на инструменти?

Дизайнът на шаблона за използване на инструменти се фокусира върху даването на възможност на LLM (големи езикови модели) да взаимодействат с външни инструменти за постигане на конкретни цели. Инструментите са код, който може да бъде изпълнен от агент за извършване на действия. Инструмент може да бъде проста функция като калкулатор, или API извикване към трета страна, като търсене на цена на акции или прогноза за времето. В контекста на AI агентите, инструментите са проектирани да бъдат изпълнявани от агенти в отговор на функционални извиквания, генерирани от модела.

В какви ситуации може да се приложи?

AI агентите могат да използват инструменти за изпълнение на сложни задачи, извличане на информация или вземане на решения. Дизайнът на шаблона за използване на инструменти често се използва в ситуации, изискващи динамично взаимодействие с външни системи, като бази данни, уеб услуги или интерпретатори на код. Тази възможност е полезна за различни случаи, включително:

Какви са елементите/изграждащите блокове, необходими за прилагането на дизайна на шаблона за използване на инструменти?

Тези изграждащи блокове позволяват на AI агента да изпълнява широк набор от задачи. Нека разгледаме ключовите елементи, необходими за прилагането на дизайна на шаблона за използване на инструменти:

След това нека разгледаме по-подробно извикването на функции/инструменти.

Извикване на функции/инструменти

Извикването на функции е основният начин, по който позволяваме на Големите Езикови Модели (LLMs) да взаимодействат с инструменти. Често ще видите ‘Функция’ и ‘Инструмент’ използвани взаимнозаменяемо, защото ‘функциите’ (блокове с прекомпилируем код) са ‘инструментите’, които агентите използват за изпълнение на задачи. За да се извика кодът на функция, LLM трябва да сравни заявката на потребителя с описанието на функцията. За целта към LLM се изпраща схема, съдържаща описанията на всички налични функции. След това LLM избира най-подходящата функция за задачата и връща името й и аргументите. Избраната функция се извиква, нейният отговор се изпраща обратно към LLM, който използва информацията, за да отговори на заявката на потребителя.

За разработчиците, които искат да реализират извикване на функции за агенти, ще са необходими:

  1. LLM модел, който поддържа извикване на функции
  2. Схема, съдържаща описания на функциите
  3. Кодът за всяка описана функция

Нека използваме примера с получаването на текущото време в даден град, за да илюстрираме:

  1. Инициализирайте LLM, който поддържа извикване на функции:

    Не всички модели поддържат извикване на функции, затова е важно да проверите дали използваният от вас LLM го прави. Azure OpenAI поддържа извикване на функции. Можем да започнем с инициализиране на OpenAI клиент срещу Azure OpenAI Responses API (стабилната /openai/v1/ крайна точка — без необходимост от api_version).

     # Инициализирайте OpenAI клиента за Azure OpenAI (API за отговори, крайна точка 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. Създайте схема на функцията:

    След това ще дефинираме JSON схема, която съдържа името на функцията, описание на това какво прави функцията и имената и описанията на параметрите на функцията. След това ще предадем тази схема на клиента, създаден по-рано, заедно със заявката на потребителя за намиране на време в Сан Франциско. Важно е да се отбележи, че се връща извикване на инструмент, а не окончателният отговор на въпроса. Както беше споменато по-горе, LLM връща името на функцията, която е избрал за задачата, и аргументите, които ще бъдат предадени.

     # Описание на функцията за четене на модела (формат на плосък инструмент за 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"],
         },
     }
 ]

      
 # Първоначално съобщение от потребителя
 messages = [{"role": "user", "content": "What's the current time in San Francisco"}]

 # Първо обаждане на API: Попитайте модела да използва функцията
 response = client.responses.create(
     model=deployment_name,
     input=messages,
     tools=tools,
     tool_choice="auto",
     store=False,
 )

 # API за отговори връща повиквания на инструменти като function_call елементи в response.output.
 # Добавете ги към разговора, за да има моделът пълен контекст при следващото обръщане.
 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. Кодът на функцията, необходим за изпълнение на задачата:

    След като LLM е избрал коя функция трябва да бъде изпълнена, кодът, който изпълнява задачата, трябва да се имплементира и стартира. Можем да имплементираме кода за получаване на текущото време с Python. Също така ще трябва да напишем код, който извлича името и аргументите от response_message, за да получим крайния резултат.

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

     # Обработка на извиквания на функции
 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")
             )

             # Върнете резултата от инструмента като елемент 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.")

 # Второ обаждане до API: Вземете крайния отговор от модела
 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.

Извикването на функции е в основата на повечето, ако не и на всички, дизайни за използването на инструменти от агенти; въпреки това, имплементацията му от нулата понякога може да бъде предизвикателна. Както научихме в Урок 2, агентските рамки ни предоставят предварително изградени компоненти за реализиране на използването на инструменти.

Примери за използване на инструменти с агентски рамки

Ето някои примери за това как може да се реализира дизайна на шаблона за използване на инструменти с различни агентски рамки:

Microsoft Agent Framework

Microsoft Agent Framework е с отворен код AI рамка за създаване на AI агенти. Тя улеснява процеса на използване на извикване на функции, като ви позволява да дефинирате инструменти като Python функции с декоратора @tool. Рамката обработва комуникацията между модела и вашия код. Освен това предоставя достъп до предварително изградени инструменти като Търсене на файлове и Интерпретатор на код чрез FoundryChatClient.

Следната диаграма илюстрира процеса на извикване на функции с Microsoft Agent Framework:

извикване на функции

В Microsoft Agent Framework инструментите се дефинират като декорирани функции. Можем да преобразуваме функцията get_current_time, която видяхме по-рано, в инструмент, като използваме декоратора @tool. Рамката автоматично сериализира функцията и нейните параметри, създавайки схемата, която да се изпрати към 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"""
    ...

# Създайте клиента
provider = FoundryChatClient(
    project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=AzureCliCredential(),
)

# Създайте агент и стартирайте с инструмента
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 е по-нова агентска рамка, проектирана да даде възможност на разработчиците сигурно да изграждат, разгръщат и мащабират висококачествени и разширяеми AI агенти без да е необходимо да управляват основните изчисления и съхранение. Особено полезна е за корпоративни приложения, тъй като е напълно управлявана услуга с корпоративно ниво на сигурност.

В сравнение с разработването директно с LLM API, Microsoft Foundry Agent Service предоставя някои предимства, включително:

Инструментите, налични в Microsoft Foundry Agent Service, могат да се разделят на две категории:

  1. Инструменти за знания:
  2. Инструменти за действия:

Агентската услуга ни позволява да използваме тези инструменти заедно като toolset. Тя също използва нишки, които следят историята на съобщенията от даден разговор.

Представете си, че сте търговски агент във фирма, наречена Contoso. Искате да разработите разговорен агент, който може да отговаря на въпроси за вашите данни за продажби.

Следващото изображение илюстрира как бихте могли да използвате Microsoft Foundry Agent Service, за да анализирате данните си за продажби:

Agentic Service In Action

За да използваме някой от тези инструменти с услугата, можем да създадем клиент и да дефинираме инструмент или набор от инструменти. За практическата реализация можем да използваме следния Python код. LLM ще може да разгледа наборa от инструменти и да реши дали да използва създадената от потребителя функция fetch_sales_data_using_sqlite_query или предварително изградения Интерпретатор на код в зависимост от заявката на потребителя.

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, която може да бъде намерена във файла 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"],
)

# Инициализиране на набор от инструменти
toolset = ToolSet()

# Инициализиране на агент за извикване на функции с функцията fetch_sales_data_using_sqlite_query и добавянето ѝ в набора от инструменти
fetch_data_function = FunctionTool(fetch_sales_data_using_sqlite_query)
toolset.add(fetch_data_function)

# Инициализиране на инструмента Code Interpreter и добавянето му в набора от инструменти.
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
)

Какви са специалните съображения при използване на дизайна на шаблона за изграждане на доверени AI агенти?

Често срещан проблем с динамично генериран SQL от LLM е сигурността, особено рискът от SQL инжекция или злонамерени действия, като изтриване или манипулиране на базата данни. Въпреки че тези опасения са основателни, те могат да бъдат ефективно смекчени чрез правилна конфигурация на разрешенията за достъп до базата данни. За повечето бази данни това включва конфигуриране на базата данни като само за четене. За бази данни като PostgreSQL или Azure SQL, приложението трябва да има роля само за четене (SELECT).

Стартирането на приложението в защитена среда допълнително повишава защитата. В корпоративни сценарии данните обикновено се извличат и трансформират от оперативните системи в база данни или склад за данни само за четене с удобна за потребителя схема. Този подход гарантира, че данните са защитени, оптимизирани за производителност и достъпност, и че приложението има ограничен, само за четене достъп.

Примери за код

Имате ли още въпроси относно шаблоните за използване на инструменти?

Присъединете се към Microsoft Foundry Discord, за да се срещнете с други учащи, да участвате в часове за консултации и да получите отговори на вашите въпроси за AI агенти.

Допълнителни ресурси

Смоук-тест на този агент (по избор)

След като научите как да разгръщате агенти в Урок 16, можете да направите смоук-тест на TravelToolAgent от този урок (дали все още извиква инструментите си и отговаря?) с tests/lesson-04-smoke-tests.json. Вижте tests/README.md за инструкции как да го стартирате.

Предишен урок

Разбиране на агентско дизайнерско моделиране

Следващ урок

Agentic RAG

Отказ от отговорност: Този документ е преведен с помощта на AI преводачески услуга Co-op Translator. Въпреки че се стремим към точност, моля имайте предвид, че автоматизираните преводи могат да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Ние не носим отговорност за каквито и да е недоразумения или неправилни тълкувания, произтичащи от използването на този превод.

This site is open source. Improve this page.