Agenten#
AutoGen AgentChat bietet eine Reihe von vordefinierten Agenten, von denen jeder Variationen in der Art und Weise aufweist, wie ein Agent auf Nachrichten reagieren kann. Alle Agenten teilen die folgenden Attribute und Methoden
name: Der eindeutige Name des Agenten.description: Die Beschreibung des Agenten in Textform.run: Die Methode, die den Agenten mit einer Aufgabe als String oder einer Liste von Nachrichten ausführt und einTaskResultzurückgibt. Agenten werden als zustandsbehaftet erwartet und diese Methode sollte mit neuen Nachrichten, nicht mit der vollständigen Historie aufgerufen werden.run_stream: Identisch mitrun(), gibt aber einen Iterator von Nachrichten zurück, die vonBaseAgentEventoderBaseChatMessageableiten, gefolgt von einemTaskResultals letztes Element.
Weitere Informationen zu AgentChat-Nachrichtentypen finden Sie unter autogen_agentchat.messages.
Assistent-Agent#
AssistantAgent ist ein integrierter Agent, der ein Sprachmodell verwendet und die Fähigkeit hat, Werkzeuge zu nutzen.
Warnung
AssistantAgent ist ein „Allzweck“-Agent für Prototypen und Bildungszwecke – er ist sehr allgemein gehalten. Lesen Sie unbedingt die Dokumentation und die Implementierung, um die Designentscheidungen zu verstehen. Sobald Sie das Design vollständig verstanden haben, möchten Sie vielleicht Ihren eigenen Agenten implementieren. Siehe Benutzerdefinierte Agenten.
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.messages import StructuredMessage
from autogen_agentchat.ui import Console
from autogen_ext.models.openai import OpenAIChatCompletionClient
# Define a tool that searches the web for information.
# For simplicity, we will use a mock function here that returns a static string.
async def web_search(query: str) -> str:
"""Find information on the web"""
return "AutoGen is a programming framework for building multi-agent applications."
# Create an agent that uses the OpenAI GPT-4o model.
model_client = OpenAIChatCompletionClient(
model="gpt-4.1-nano",
# api_key="YOUR_API_KEY",
)
agent = AssistantAgent(
name="assistant",
model_client=model_client,
tools=[web_search],
system_message="Use tools to solve tasks.",
)
Ergebnis erhalten#
Wir können die Methode run() verwenden, um den Agenten für eine gegebene Aufgabe ausführen zu lassen.
# Use asyncio.run(agent.run(...)) when running in a script.
result = await agent.run(task="Find information on AutoGen")
print(result.messages)
[TextMessage(source='user', models_usage=None, metadata={}, content='Find information on AutoGen', type='TextMessage'), ToolCallRequestEvent(source='assistant', models_usage=RequestUsage(prompt_tokens=61, completion_tokens=16), metadata={}, content=[FunctionCall(id='call_703i17OLXfztkuioUbkESnea', arguments='{"query":"AutoGen"}', name='web_search')], type='ToolCallRequestEvent'), ToolCallExecutionEvent(source='assistant', models_usage=None, metadata={}, content=[FunctionExecutionResult(content='AutoGen is a programming framework for building multi-agent applications.', name='web_search', call_id='call_703i17OLXfztkuioUbkESnea', is_error=False)], type='ToolCallExecutionEvent'), ToolCallSummaryMessage(source='assistant', models_usage=None, metadata={}, content='AutoGen is a programming framework for building multi-agent applications.', type='ToolCallSummaryMessage')]
Der Aufruf der Methode run() gibt ein TaskResult mit der Liste der Nachrichten im Attribut messages zurück, welches den „Gedankenprozess“ des Agenten sowie die endgültige Antwort speichert.
Hinweis
Es ist wichtig zu beachten, dass run() den internen Zustand des Agenten aktualisiert – es fügt die Nachrichten der Nachrichtenhistorie des Agenten hinzu. Sie können run() auch ohne Aufgabe aufrufen, damit der Agent auf Basis seines aktuellen Zustands Antworten generiert.
Hinweis
Im Gegensatz zu v0.2 AgentChat werden die Werkzeuge vom selben Agenten direkt im selben Aufruf von run() ausgeführt. Standardmäßig gibt der Agent das Ergebnis des Werkzeugaufrufs als endgültige Antwort zurück.
Multimodale Eingabe#
Der AssistantAgent kann multimodale Eingaben verarbeiten, indem die Eingabe als MultiModalMessage bereitgestellt wird.
from io import BytesIO
import PIL
import requests
from autogen_agentchat.messages import MultiModalMessage
from autogen_core import Image
# Create a multi-modal message with random image and text.
pil_image = PIL.Image.open(BytesIO(requests.get("https://picsum.photos/300/200").content))
img = Image(pil_image)
multi_modal_message = MultiModalMessage(content=["Can you describe the content of this image?", img], source="user")
img
# Use asyncio.run(...) when running in a script.
result = await agent.run(task=multi_modal_message)
print(result.messages[-1].content) # type: ignore
The image depicts a scenic mountain landscape under a clear blue sky. There are several rugged mountain peaks in the background, with some clouds scattered across the sky. In the valley below, there is a body of water, possibly a lake or river, surrounded by greenery. The overall scene conveys a sense of natural beauty and tranquility.
Nachrichten-Streaming#
Wir können auch jede Nachricht streamen, sobald sie vom Agenten generiert wird, indem wir die Methode run_stream() verwenden und Console verwenden, um die Nachrichten anzuzeigen, sobald sie auf der Konsole erscheinen.
async def assistant_run_stream() -> None:
# Option 1: read each message from the stream (as shown in the previous example).
# async for message in agent.run_stream(task="Find information on AutoGen"):
# print(message)
# Option 2: use Console to print all messages as they appear.
await Console(
agent.run_stream(task="Find information on AutoGen"),
output_stats=True, # Enable stats printing.
)
# Use asyncio.run(assistant_run_stream()) when running in a script.
await assistant_run_stream()
---------- TextMessage (user) ----------
Find information on AutoGen
---------- ToolCallRequestEvent (assistant) ----------
[FunctionCall(id='call_HOTRhOzXCBm0zSqZCFbHD7YP', arguments='{"query":"AutoGen"}', name='web_search')]
[Prompt tokens: 61, Completion tokens: 16]
---------- ToolCallExecutionEvent (assistant) ----------
[FunctionExecutionResult(content='AutoGen is a programming framework for building multi-agent applications.', name='web_search', call_id='call_HOTRhOzXCBm0zSqZCFbHD7YP', is_error=False)]
---------- ToolCallSummaryMessage (assistant) ----------
AutoGen is a programming framework for building multi-agent applications.
---------- Summary ----------
Number of messages: 4
Finish reason: None
Total prompt tokens: 61
Total completion tokens: 16
Duration: 0.52 seconds
Die Methode run_stream() gibt einen asynchronen Generator zurück, der jede vom Agenten generierte Nachricht liefert, gefolgt von einem TaskResult als letztes Element.
Anhand der Nachrichten können Sie beobachten, dass der Assistentenagent das Werkzeug web_search verwendet hat, um Informationen zu sammeln und basierend auf den Suchergebnissen geantwortet hat.
Werkzeuge und Workbench verwenden#
Große Sprachmodelle (LLMs) sind typischerweise auf die Generierung von Text- oder Code-Antworten beschränkt. Viele komplexe Aufgaben profitieren jedoch von der Möglichkeit, externe Werkzeuge zu nutzen, die spezifische Aktionen ausführen, wie z. B. das Abrufen von Daten aus APIs oder Datenbanken.
Um diese Einschränkung zu überwinden, können moderne LLMs nun eine Liste verfügbarer Werkzeugschemata (Beschreibungen von Werkzeugen und ihren Argumenten) akzeptieren und eine Werkzeugaufrufnachricht generieren. Diese Fähigkeit ist als Tool Calling oder Function Calling bekannt und wird zu einem beliebten Muster beim Erstellen intelligenter agentenbasierter Anwendungen. Weitere Informationen zum Aufruf von Werkzeugen in LLMs finden Sie in der Dokumentation von OpenAI und Anthropic.
In AgentChat kann der AssistantAgent Werkzeuge verwenden, um spezifische Aktionen auszuführen. Das Werkzeug web_search ist ein solches Werkzeug, das es dem Assistentenagenten ermöglicht, das Web nach Informationen zu durchsuchen. Ein einzelnes benutzerdefiniertes Werkzeug kann eine Python-Funktion oder eine Unterklasse von BaseTool sein.
Auf der anderen Seite ist eine Workbench eine Sammlung von Werkzeugen, die Zustand und Ressourcen gemeinsam nutzen.
Hinweis
Informationen zur direkten Verwendung von Modellclients mit Werkzeugen und Workbenches finden Sie in den Abschnitten Werkzeuge und Workbench im Core-Benutzerhandbuch.
Standardmäßig gibt der AssistantAgent, wenn er ein Werkzeug ausführt, das Ergebnis des Werkzeugs als String in einer ToolCallSummaryMessage in seiner Antwort zurück. Wenn Ihr Werkzeug keinen gut formulierten String in natürlicher Sprache zurückgibt, können Sie einen Reflexionsschritt hinzufügen, um das Modell die Ausgabe des Werkzeugs zusammenfassen zu lassen, indem Sie den Parameter reflect_on_tool_use=True im Konstruktor von AssistantAgent setzen.
Integrierte Werkzeuge und Workbench#
AutoGen Extension bietet eine Reihe von integrierten Werkzeugen, die mit dem Assistentenagenten verwendet werden können. Navigieren Sie zur API-Dokumentation, um alle verfügbaren Werkzeuge im Namensraum autogen_ext.tools zu finden. Sie finden dort zum Beispiel folgende Werkzeuge
Funktionswerkzeug#
Der AssistantAgent wandelt eine Python-Funktion automatisch in ein FunctionTool um, das als Werkzeug für den Agenten verwendet werden kann, und generiert automatisch das Werkzeugschema aus der Funktionssignatur und der Docstring.
Das Werkzeug web_search_func ist ein Beispiel für ein Funktionswerkzeug. Das Schema wird automatisch generiert.
from autogen_core.tools import FunctionTool
# Define a tool using a Python function.
async def web_search_func(query: str) -> str:
"""Find information on the web"""
return "AutoGen is a programming framework for building multi-agent applications."
# This step is automatically performed inside the AssistantAgent if the tool is a Python function.
web_search_function_tool = FunctionTool(web_search_func, description="Find information on the web")
# The schema is provided to the model during AssistantAgent's on_messages call.
web_search_function_tool.schema
{'name': 'web_search_func',
'description': 'Find information on the web',
'parameters': {'type': 'object',
'properties': {'query': {'description': 'query',
'title': 'Query',
'type': 'string'}},
'required': ['query'],
'additionalProperties': False},
'strict': False}
Model Context Protocol (MCP) Workbench#
Der AssistantAgent kann auch Werkzeuge verwenden, die von einem Model Context Protocol (MCP) Server über McpWorkbench() bereitgestellt werden.
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.messages import TextMessage
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_ext.tools.mcp import McpWorkbench, StdioServerParams
# Get the fetch tool from mcp-server-fetch.
fetch_mcp_server = StdioServerParams(command="uvx", args=["mcp-server-fetch"])
# Create an MCP workbench which provides a session to the mcp server.
async with McpWorkbench(fetch_mcp_server) as workbench: # type: ignore
# Create an agent that can use the fetch tool.
model_client = OpenAIChatCompletionClient(model="gpt-4.1-nano")
fetch_agent = AssistantAgent(
name="fetcher", model_client=model_client, workbench=workbench, reflect_on_tool_use=True
)
# Let the agent fetch the content of a URL and summarize it.
result = await fetch_agent.run(task="Summarize the content of https://en.wikipedia.org/wiki/Seattle")
assert isinstance(result.messages[-1], TextMessage)
print(result.messages[-1].content)
# Close the connection to the model client.
await model_client.close()
Seattle is a major city located in the state of Washington, United States. It was founded on November 13, 1851, and incorporated as a town on January 14, 1865, and later as a city on December 2, 1869. The city is named after Chief Seattle. It covers an area of approximately 142 square miles, with a population of around 737,000 as of the 2020 Census, and an estimated 755,078 residents in 2023. Seattle is known by nicknames such as The Emerald City, Jet City, and Rain City, and has mottos including The City of Flowers and The City of Goodwill. The city operates under a mayor–council government system, with Bruce Harrell serving as mayor. Key landmarks include the Space Needle, Pike Place Market, Amazon Spheres, and the Seattle Great Wheel. It is situated on the U.S. West Coast, with a diverse urban and metropolitan area that extends to a population of over 4 million in the greater metropolitan region.
Agent als Werkzeug#
Jeder BaseChatAgent kann als Werkzeug verwendet werden, indem er in ein AgentTool eingepackt wird. Dies ermöglicht einen dynamischen, modellgesteuerten Multi-Agenten-Workflow, bei dem der Agent andere Agenten als Werkzeuge aufrufen kann, um Aufgaben zu lösen.
Parallele Werkzeugaufrufe#
Einige Modelle unterstützen parallele Werkzeugaufrufe, was für Aufgaben nützlich sein kann, die das gleichzeitige Aufrufen mehrerer Werkzeuge erfordern. Standardmäßig ruft der AssistantAgent die Werkzeuge parallel auf, wenn der Modellclient mehrere Werkzeugaufrufe erzeugt.
Sie möchten möglicherweise parallele Werkzeugaufrufe deaktivieren, wenn die Werkzeuge Nebeneffekte haben, die sich gegenseitig stören könnten, oder wenn das Agentenverhalten über verschiedene Modelle hinweg konsistent sein soll. Dies sollte auf Ebene des Modellclients erfolgen.
Wichtig
Bei der Verwendung von AgentTool oder TeamTool müssen Sie parallele Werkzeugaufrufe deaktivieren, um Nebenläufigkeitsprobleme zu vermeiden. Diese Werkzeuge können nicht gleichzeitig ausgeführt werden, da Agenten und Teams interne Zustände aufrechterhalten, die mit paralleler Ausführung kollidieren würden.
Für OpenAIChatCompletionClient und AzureOpenAIChatCompletionClient setzen Sie parallel_tool_calls=False, um parallele Werkzeugaufrufe zu deaktivieren.
model_client_no_parallel_tool_call = OpenAIChatCompletionClient(
model="gpt-4o",
parallel_tool_calls=False, # type: ignore
)
agent_no_parallel_tool_call = AssistantAgent(
name="assistant",
model_client=model_client_no_parallel_tool_call,
tools=[web_search],
system_message="Use tools to solve tasks.",
)
Werkzeug-Iterationen#
Ein Modellaufruf gefolgt von einem Werkzeugaufruf oder parallelen Werkzeugaufrufen ist eine einzelne Werkzeug-Iteration. Standardmäßig führt der AssistantAgent höchstens eine Iteration aus.
Der Agent kann so konfiguriert werden, dass er mehrere Iterationen ausführt, bis das Modell keine weiteren Werkzeugaufrufe mehr generiert oder die maximale Anzahl von Iterationen erreicht ist. Sie können die maximale Anzahl von Iterationen steuern, indem Sie den Parameter max_tool_iterations im Konstruktor von AssistantAgent setzen.
agent_loop = AssistantAgent(
name="assistant_loop",
model_client=model_client_no_parallel_tool_call,
tools=[web_search],
system_message="Use tools to solve tasks.",
max_tool_iterations=10, # At most 10 iterations of tool calls before stopping the loop.
)
Strukturierte Ausgabe#
Strukturierte Ausgabe ermöglicht es Modellen, strukturierte JSON-Texte mit vordefinierten Schemata, die von der Anwendung bereitgestellt werden, zurückzugeben. Im Gegensatz zum JSON-Modus kann das Schema als Pydantic BaseModel-Klasse bereitgestellt werden, die auch zur Validierung der Ausgabe verwendet werden kann.
Sobald Sie die Basisklassen in den Parameter output_content_type des Konstruktors von AssistantAgent einfügen, wird der Agent mit einer StructuredMessage antworten, deren content den Typ der Basisklassen hat.
Auf diese Weise können Sie die Antwort des Agenten direkt in Ihre Anwendung integrieren und die Ausgabe des Modells als strukturiertes Objekt verwenden.
Hinweis
Wenn output_content_type gesetzt ist, wird standardmäßig erwartet, dass der Agent die Werkzeugnutzung reflektiert und eine strukturierte Ausgabenachricht basierend auf dem Ergebnis des Werkzeugaufrufs zurückgibt. Sie können dieses Verhalten deaktivieren, indem Sie reflect_on_tool_use=False explizit setzen.
Strukturierte Ausgabe ist auch nützlich, um Chain-of-Thought-Argumentation in die Antworten des Agenten zu integrieren. Sehen Sie sich das folgende Beispiel an, wie Sie strukturierte Ausgabe mit dem Assistentenagenten verwenden.
from typing import Literal
from pydantic import BaseModel
# The response format for the agent as a Pydantic base model.
class AgentResponse(BaseModel):
thoughts: str
response: Literal["happy", "sad", "neutral"]
# Create an agent that uses the OpenAI GPT-4o model.
model_client = OpenAIChatCompletionClient(model="gpt-4o")
agent = AssistantAgent(
"assistant",
model_client=model_client,
system_message="Categorize the input as happy, sad, or neutral following the JSON format.",
# Define the output content type of the agent.
output_content_type=AgentResponse,
)
result = await Console(agent.run_stream(task="I am happy."))
# Check the last message in the result, validate its type, and print the thoughts and response.
assert isinstance(result.messages[-1], StructuredMessage)
assert isinstance(result.messages[-1].content, AgentResponse)
print("Thought: ", result.messages[-1].content.thoughts)
print("Response: ", result.messages[-1].content.response)
await model_client.close()
---------- user ----------
I am happy.
---------- assistant ----------
{
"thoughts": "The user explicitly states they are happy.",
"response": "happy"
}
Thought: The user explicitly states they are happy.
Response: happy
Token-Streaming#
Sie können die vom Modellclient generierten Tokens streamen, indem Sie model_client_stream=True setzen. Dies bewirkt, dass der Agent ModelClientStreamingChunkEvent-Nachrichten in run_stream() liefert.
Die zugrunde liegende Modell-API muss das Streaming von Tokens unterstützen, damit dies funktioniert. Bitte prüfen Sie bei Ihrem Modellprovider, ob dies unterstützt wird.
model_client = OpenAIChatCompletionClient(model="gpt-4o")
streaming_assistant = AssistantAgent(
name="assistant",
model_client=model_client,
system_message="You are a helpful assistant.",
model_client_stream=True, # Enable streaming tokens.
)
# Use an async function and asyncio.run() in a script.
async for message in streaming_assistant.run_stream(task="Name two cities in South America"): # type: ignore
print(message)
source='user' models_usage=None metadata={} content='Name two cities in South America' type='TextMessage'
source='assistant' models_usage=None metadata={} content='Two' type='ModelClientStreamingChunkEvent'
source='assistant' models_usage=None metadata={} content=' cities' type='ModelClientStreamingChunkEvent'
source='assistant' models_usage=None metadata={} content=' in' type='ModelClientStreamingChunkEvent'
source='assistant' models_usage=None metadata={} content=' South' type='ModelClientStreamingChunkEvent'
source='assistant' models_usage=None metadata={} content=' America' type='ModelClientStreamingChunkEvent'
source='assistant' models_usage=None metadata={} content=' are' type='ModelClientStreamingChunkEvent'
source='assistant' models_usage=None metadata={} content=' Buenos' type='ModelClientStreamingChunkEvent'
source='assistant' models_usage=None metadata={} content=' Aires' type='ModelClientStreamingChunkEvent'
source='assistant' models_usage=None metadata={} content=' in' type='ModelClientStreamingChunkEvent'
source='assistant' models_usage=None metadata={} content=' Argentina' type='ModelClientStreamingChunkEvent'
source='assistant' models_usage=None metadata={} content=' and' type='ModelClientStreamingChunkEvent'
source='assistant' models_usage=None metadata={} content=' São' type='ModelClientStreamingChunkEvent'
source='assistant' models_usage=None metadata={} content=' Paulo' type='ModelClientStreamingChunkEvent'
source='assistant' models_usage=None metadata={} content=' in' type='ModelClientStreamingChunkEvent'
source='assistant' models_usage=None metadata={} content=' Brazil' type='ModelClientStreamingChunkEvent'
source='assistant' models_usage=None metadata={} content='.' type='ModelClientStreamingChunkEvent'
source='assistant' models_usage=RequestUsage(prompt_tokens=0, completion_tokens=0) metadata={} content='Two cities in South America are Buenos Aires in Argentina and São Paulo in Brazil.' type='TextMessage'
messages=[TextMessage(source='user', models_usage=None, metadata={}, content='Name two cities in South America', type='TextMessage'), TextMessage(source='assistant', models_usage=RequestUsage(prompt_tokens=0, completion_tokens=0), metadata={}, content='Two cities in South America are Buenos Aires in Argentina and São Paulo in Brazil.', type='TextMessage')] stop_reason=None
Sie können die Streaming-Chunks in der obigen Ausgabe sehen. Die Chunks werden vom Modellclient generiert und vom Agenten geliefert, sobald sie empfangen werden. Die endgültige Antwort, die Verkettung aller Chunks, wird direkt nach dem letzten Chunk geliefert.
Modellkontext verwenden#
Der AssistantAgent verfügt über einen Parameter model_context, mit dem ein ChatCompletionContext-Objekt übergeben werden kann. Dies ermöglicht es dem Agenten, verschiedene Modellkontexte zu verwenden, wie z. B. BufferedChatCompletionContext, um den an das Modell gesendeten Kontext zu begrenzen.
Standardmäßig verwendet der AssistantAgent den UnboundedChatCompletionContext, der die vollständige Konversationshistorie an das Modell sendet. Um den Kontext auf die letzten n Nachrichten zu beschränken, können Sie den BufferedChatCompletionContext verwenden. Um den Kontext nach Token-Anzahl zu begrenzen, können Sie den TokenLimitedChatCompletionContext verwenden.
from autogen_core.model_context import BufferedChatCompletionContext
# Create an agent that uses only the last 5 messages in the context to generate responses.
agent = AssistantAgent(
name="assistant",
model_client=model_client,
tools=[web_search],
system_message="Use tools to solve tasks.",
model_context=BufferedChatCompletionContext(buffer_size=5), # Only use the last 5 messages in the context.
)
Andere vordefinierte Agenten#
Die folgenden vordefinierten Agenten sind verfügbar
UserProxyAgent: Ein Agent, der Benutzereingaben entgegennimmt und diese als Antworten zurückgibt.CodeExecutorAgent: Ein Agent, der Code ausführen kann.OpenAIAssistantAgent: Ein Agent, der von einem OpenAI-Assistenten unterstützt wird und benutzerdefinierte Werkzeuge nutzen kann.MultimodalWebSurfer: Ein multimodaler Agent, der das Web durchsuchen und Webseiten nach Informationen besuchen kann.FileSurfer: Ein Agent, der lokale Dateien nach Informationen durchsuchen und durchsuchen kann.VideoSurfer: Ein Agent, der Videos nach Informationen ansehen kann.
Nächster Schritt#
Nachdem wir die Verwendung des AssistantAgent untersucht haben, können wir nun zum nächsten Abschnitt übergehen, um mehr über die Teams-Funktion in AgentChat zu erfahren.