ai-agents-for-beginners

Eksploracja Microsoft Agent Framework

Agent Framework

Wprowadzenie

W tej lekcji omówimy:

Cele nauki

Po ukończeniu tej lekcji będziesz wiedzieć, jak:

Przykłady kodu

Przykłady kodu dla Microsoft Agent Framework (MAF) można znaleźć w tym repozytorium w plikach xx-python-agent-framework i xx-dotnet-agent-framework.

Zrozumienie Microsoft Agent Framework

Framework Intro

Microsoft Agent Framework (MAF) to zunifikowany framework Microsoftu do tworzenia agentów AI. Oferuje elastyczność, aby sprostać szerokiemu wachlarzowi zastosowań agentowych spotykanych zarówno w środowiskach produkcyjnych, jak i badawczych, w tym:

Aby dostarczać agentów AI w produkcji, MAF zawiera też funkcje takie jak:

Microsoft Agent Framework skupia się także na interoperacyjności poprzez:

Przyjrzyjmy się, jak te funkcjonalności stosowane są w niektórych kluczowych koncepcjach Microsoft Agent Framework.

Kluczowe koncepcje Microsoft Agent Framework

Agenty

Agent Framework

Tworzenie agentów

Tworzenie agenta polega na zdefiniowaniu usługi inferencyjnej (dostawcy LLM), zestawu instrukcji, które agent AI ma wykonywać, oraz przypisaniu name:

agent = AzureOpenAIChatClient(credential=AzureCliCredential()).create_agent( instructions="You are good at recommending trips to customers based on their preferences.", name="TripRecommender" )

Powyższy przykład używa Azure OpenAI, ale agentów można tworzyć używając różnych usług, w tym Microsoft Foundry Agent Service:

AzureAIAgentClient(async_credential=credential).create_agent( name="HelperAgent", instructions="You are a helpful assistant." ) as agent

API OpenAI Responses, ChatCompletion

agent = OpenAIResponsesClient().create_agent( name="WeatherBot", instructions="You are a helpful weather assistant.", )

agent = OpenAIChatClient().create_agent( name="HelpfulAssistant", instructions="You are a helpful assistant.", )

lub MiniMax, który oferuje kompatybilne z OpenAI API z dużymi oknami kontekstowymi (do 204K tokenów):

agent = OpenAIChatClient(base_url="https://api.minimax.io/v1", api_key=os.environ["MINIMAX_API_KEY"], model_id="MiniMax-M2.7").create_agent( name="HelpfulAssistant", instructions="You are a helpful assistant.", )

lub agentów zdalnych korzystających z protokołu A2A:

agent = A2AAgent( name=agent_card.name, description=agent_card.description, agent_card=agent_card, url="https://your-a2a-agent-host" )

Uruchamianie agentów

Agenty uruchamia się za pomocą metod .run lub .run_stream dla odpowiedzi nie-strumieniowych lub strumieniowych.

result = await agent.run("What are good places to visit in Amsterdam?")
print(result.text)

async for update in agent.run_stream("What are the good places to visit in Amsterdam?"):
    if update.text:
        print(update.text, end="", flush=True)

Dla każdego uruchomienia agenta można też ustawić opcje dostosowujące parametry takie jak max_tokens używane przez agenta, tools których agent może wywoływać oraz nawet sam model używany przez agenta.

Jest to przydatne, gdy do realizacji zadania użytkownika wymagane są konkretne modele lub narzędzia.

Narzędzia

Narzędzia mogą być definiowane zarówno podczas definiowania agenta:

def get_attractions( location: Annotated[str, Field(description="The location to get the top tourist attractions for")], ) -> str: """Get the top tourist attractions for a given location.""" return f"The top attractions for {location} are." 


# Podczas bezpośredniego tworzenia ChatAgent

agent = ChatAgent( chat_client=OpenAIChatClient(), instructions="You are a helpful assistant", tools=[get_attractions]

jak i podczas uruchamiania agenta:


result1 = await agent.run( "What's the best place to visit in Seattle?", tools=[get_attractions] # Narzędzie udostępnione tylko na ten jeden uruchomienie )

Wątki agenta

Wątki agenta służą do obsługi rozmów wieloetapowych. Wątki można tworzyć na dwa sposoby:

Kod tworzący wątek wygląda tak:

# Utwórz nowy wątek.
thread = agent.get_new_thread() # Uruchom agenta z wątkiem.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Następnie wątek można zserializować, aby przechować go na później:

# Utwórz nowy wątek.
thread = agent.get_new_thread() 

# Uruchom agenta z tym wątkiem.

response = await agent.run("Hello, how are you?", thread=thread) 

# Zserializuj wątek do przechowywania.

serialized_thread = await thread.serialize() 

# Deserializuj stan wątku po załadowaniu z magazynu.

resumed_thread = await agent.deserialize_thread(serialized_thread)

Middleware agenta

Agenty współpracują z narzędziami i LLM, aby zrealizować zadania użytkownika. W pewnych scenariuszach chcemy wykonywać akcje lub śledzić je pomiędzy tymi interakcjami. Middleware agenta pozwala to robić poprzez:

Middleware funkcji

Ten middleware pozwala wykonać akcję pomiędzy agentem a funkcją/narzędziem, które będzie wywoływane. Przykładem zastosowania jest logowanie wywołań funkcji.

W poniższym kodzie next definiuje, czy powinien zostać wywołany następny middleware czy faktyczna funkcja.

async def logging_function_middleware(
    context: FunctionInvocationContext,
    next: Callable[[FunctionInvocationContext], Awaitable[None]],
) -> None:
    """Function middleware that logs function execution."""
    # Wstępne przetwarzanie: logowanie przed wykonaniem funkcji
    print(f"[Function] Calling {context.function.name}")

    # Kontynuuj do następnego middleware lub wykonania funkcji
    await next(context)

    # Przetwarzanie po wykonaniu: logowanie po wykonaniu funkcji
    print(f"[Function] {context.function.name} completed")

Middleware czatu

Ten middleware pozwala wykonać lub zalogować akcję pomiędzy agentem a zapytaniami do LLM.

Zawiera ważne informacje takie jak messages wysyłane do usługi AI.

async def logging_chat_middleware(
    context: ChatContext,
    next: Callable[[ChatContext], Awaitable[None]],
) -> None:
    """Chat middleware that logs AI interactions."""
    # Wstępne przetwarzanie: Log przed wywołaniem AI
    print(f"[Chat] Sending {len(context.messages)} messages to AI")

    # Kontynuuj do następnego oprogramowania pośredniczącego lub usługi AI
    await next(context)

    # Post-przetwarzanie: Log po odpowiedzi AI
    print("[Chat] AI response received")

Pamięć agenta

Jak omówiono w lekcji Agentic Memory, pamięć jest ważnym elementem umożliwiającym agentowi działanie w różnych kontekstach. MAF oferuje kilka typów pamięci:

Pamięć w pamięci operacyjnej

To pamięć przechowywana w wątkach podczas działania aplikacji.

# Utwórz nowy wątek.
thread = agent.get_new_thread() # Uruchom agenta z tym wątkiem.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Wiadomości trwałe

Ta pamięć służy do przechowywania historii konwersacji w różnych sesjach. Definiowana jest za pomocą chat_message_store_factory:

from agent_framework import ChatMessageStore

# Utwórz niestandardowy magazyn wiadomości
def create_message_store():
    return ChatMessageStore()

agent = ChatAgent(
    chat_client=OpenAIChatClient(),
    instructions="You are a Travel assistant.",
    chat_message_store_factory=create_message_store
)

Pamięć dynamiczna

Ta pamięć jest dodawana do kontekstu przed uruchomieniem agentów. Może być przechowywana w zewnętrznych usługach jak mem0:

from agent_framework.mem0 import Mem0Provider

# Używanie Mem0 do zaawansowanych możliwości pamięciowych
memory_provider = Mem0Provider(
    api_key="your-mem0-api-key",
    user_id="user_123",
    application_id="my_app"
)

agent = ChatAgent(
    chat_client=OpenAIChatClient(),
    instructions="You are a helpful assistant with memory.",
    context_providers=memory_provider
)

Obserwowalność agenta

Obserwowalność jest ważna przy budowaniu niezawodnych i możliwych do utrzymania systemów agentowych. MAF integruje się z OpenTelemetry, aby zapewnić śledzenie i mierniki dla lepszej obserwowalności.

from agent_framework.observability import get_tracer, get_meter

tracer = get_tracer()
meter = get_meter()
with tracer.start_as_current_span("my_custom_span"):
    # zrobić coś
    pass
counter = meter.create_counter("my_custom_counter")
counter.add(1, {"key": "value"})

Przepływy pracy

MAF oferuje przepływy pracy, czyli predefiniowane kroki do realizacji zadania, które zawierają agentów AI jako komponenty tych kroków.

Przepływy pracy składają się z różnych elementów umożliwiających lepszą kontrolę przepływu. Pozwalają również na orkiestrację wielu agentów i punktów kontrolnych, które zapisują stany przepływu pracy.

Podstawowe elementy przepływu pracy to:

Wykonawcy

Wykonawcy otrzymują wiadomości wejściowe, wykonują przypisane im zadania, a następnie generują wiadomości wyjściowe. Dzięki temu przepływ pracy postępuje w kierunku ukończenia większego zadania. Wykonawcami mogą być agenty AI lub logika niestandardowa.

Krawędzie

Krawędzie służą do definiowania przepływu wiadomości w przepływie pracy. Mogą to być:

Bezpośrednie krawędzie – proste połączenia jeden-do-jednego pomiędzy wykonawcami:

from agent_framework import WorkflowBuilder

builder = WorkflowBuilder()
builder.add_edge(source_executor, target_executor)
builder.set_start_executor(source_executor)
workflow = builder.build()

Krawędzie warunkowe – aktywowane po spełnieniu określonego warunku. Na przykład, gdy pokoje hotelowe są niedostępne, wykonawca może zasugerować inne opcje.

Krawędzie typu switch-case – kierują wiadomości do różnych wykonawców na podstawie zdefiniowanych warunków. Na przykład, klient podróży z priorytetowym dostępem może mieć swoje zadania obsługiwane innym przepływem.

Krawędzie rozgałęziające (fan-out) – wysyłają jedną wiadomość do wielu celów.

Krawędzie zbierające (fan-in) – zbierają wiele wiadomości od różnych wykonawców i przesyłają je do jednego celu.

Zdarzenia

Aby zapewnić lepszą obserwowalność przepływów pracy, MAF oferuje wbudowane zdarzenia wykonania, takie jak:

Zaawansowane wzorce MAF

Powyższe sekcje omawiają kluczowe koncepcje Microsoft Agent Framework. Budując bardziej zaawansowane agenty, warto rozważyć następujące wzorce:

Przykłady kodu

Przykłady kodu dla Microsoft Agent Framework można znaleźć w tym repozytorium w plikach xx-python-agent-framework i xx-dotnet-agent-framework.

Masz więcej pytań dotyczących Microsoft Agent Framework?

Dołącz do Microsoft Foundry Discord, aby spotkać się z innymi uczącymi się, uczestniczyć w godzinach konsultacji i uzyskać odpowiedzi na pytania dotyczące agentów AI.

Zastrzeżenie:
Ten dokument został przetłumaczony za pomocą usługi tłumaczeń AI Co-op Translator. Chociaż dążymy do dokładności, prosimy pamiętać, że automatyczne tłumaczenia mogą zawierać błędy lub niedokładności. Oryginalny dokument w jego języku źródłowym powinien być uznawany za autorytatywne źródło. W przypadku kluczowych informacji zalecane jest skorzystanie z profesjonalnego tłumaczenia wykonanego przez człowieka. Nie ponosimy odpowiedzialności za jakiekolwiek nieporozumienia lub błędne interpretacje wynikające z korzystania z tego tłumaczenia.

This site is open source. Improve this page.