Erste Schritte mit einem Notebook
Machen Sie mit dem Agent Framework in einem Notebook erste Schritte mit einem „Hello World“-Agenten.
Beispiel-Kundenservicemitarbeiter
Wenn Sie sich Beispielcode für Beispiel-Kundenservicemitarbeiter ansehen möchten, laden Sie die ZIP-Datei aus diesem Google Drive-Ordner in Ihre lokale Entwicklungsumgebung herunter.
Im Verzeichnis „samples“ befinden sich Demo-Kundenservicemitarbeiter. Installieren Sie die Abhängigkeiten in der requirements.txt-Datei für einen bestimmten Demo-Agenten:
pip install -r samples/anthropic_demo/requirements.txt
Führen Sie folgende Befehle aus:
af web samples
af run samples/hello_world
Tutorials
Auf dieser Seite finden Sie Schritt-für-Schritt-Anleitungen für gängige Aufgaben bei der Arbeit mit dem Agent Framework. Wählen Sie ein Tutorial aus, um loszulegen.
Anleitung: Eigene Daten in einen Agenten einbinden
In dieser Anleitung werden verschiedene Methoden beschrieben, wie Sie Ihre eigenen Daten, Ihr Wissen oder Dokumente an Ihren Kundenservicemitarbeiter weitergeben können. Der beste Ansatz hängt von der Größe und Art Ihrer Daten sowie vom gewünschten Gleichgewicht zwischen Latenz und Genauigkeit ab.
Eigene Daten bereitstellen
Je nach Größe, Typ und gewünschtem Kompromiss zwischen Latenz und Genauigkeit gibt es verschiedene Möglichkeiten, dem Kundenservicemitarbeiter eigene Daten, Informationen oder Dokumente zur Verfügung zu stellen.
| Typ | Kleiner Betrag | Großer Betrag |
|---|---|---|
| Nur Text | In Anleitung oder RAG einbetten | RAG |
| Dokumente | In Anleitung oder RAG einbetten | RAG |
| Andere Medien (Bilder, Audios, Videos usw.) |
WIP | WIP |
In den folgenden Anleitungen finden Sie weitere Informationen zu den einzelnen Ansätzen.
Daten in Anleitungen einbetten
Eine einfache Möglichkeit, dem Kundenservicemitarbeiter eine kleine Anzahl von Dokumenten zur Verfügung zu stellen, besteht darin, sie in die Anleitung einzubetten.
PDF- oder andere Textdateien können in Nur-Text konvertiert und in die Anleitung eingebettet werden.
Hinweise
Der Inhalt der Dateien wird an das Modell gesendet. Je größer die Datei, desto höher sind die Latenz und die Kosten.
Die Inhalte werden für alle Anfragen an das Modell gesendet, unabhängig davon, ob die Suchanfrage des Nutzers etwas mit den Inhalten zu tun hat.
Sie können für Ihre Datei Nur-Text oder ein beliebiges lesbares Textformat wie Markdown verwenden.
Sicherheitsrisiken
Das Einbetten von Inhalten auf diese Weise birgt einige Sicherheitsrisiken, da der Server den Inhalt der eingebetteten Dokumente als eigene Anweisungen behandeln kann.
Dieses Sicherheitsrisiko kann bis zu einem gewissen Grad verringert werden, indem Anfang und Ende der eingebetteten Inhalte deutlich gekennzeichnet werden, wie im Beispiel unten gezeigt.
Aufgrund dieses Risikos sollten Sie keine Inhalte einbetten, denen Sie nicht vertrauen, z.B. von Nutzern erstellte Inhalte.
Beispiel
Um die Anleitung lesbar zu machen, wird häufig die Datei geladen und mithilfe der F-String-Syntax von Python in die Anleitung eingefügt.
Beachten Sie, dass der Inhalt der Datei mithilfe von XML-Tags vom Rest der Anleitung getrennt wird. Sie können auch andere Trennlinien verwenden, solange sie für das Modell klar erkennbar sind. z.B. Tags wie BEGIN_USER_GUIDE / END_USER_GUIDE.
def read_file(filename):
file_path = os.path.join(os.path.dirname(__file__), filename)
with open(file_path, 'r') as f:
return f.read()
agent_framework_bot = Agent(
# ...
instruction=f"""You are an agent that answers user's questions about the Agent Framework.
You answer users' questions based on the user guide below:
<user_guide>
{read_file('user_guide.md')}
</user_guide>
"""
)
RAG verwenden
Die Retrieval-Augmented Generation ist ein gängiges Muster, um Modellantworten mit Ihren eigenen Daten zu ergänzen. Sie ist besonders nützlich für große Datenmengen, da die Daten indexiert und nur ein kleiner Teil der Daten abgerufen wird, der für die Abfrage relevant ist.
Das Agent Framework bietet verschiedene Möglichkeiten zur Integration in verschiedene RAG-Systeme.
| Szenarien | Empfehlungen |
|---|---|
| Demos / Prototypen | FilesRetrieval |
| Kleine Datenmenge (ein paar Dokumente) |
FilesRetrieval |
| Vollständig verwaltete RAG-Lösung | VertexRagRetrieval |
| DIY- oder andere RAG-Lösungen | LlamaIndexRetrieval |
FilesRetrieval
FilesRetrieval erstellt beim Starten des Agents einen In-Memory-Vektorspeicher. Dies erhöht die Latenz und ist auf den Arbeitsspeicher und die Leistung der API-Hosting-Umgebung beschränkt. Daher eignet sich diese Option nur für Demos / Prototypen oder die Produktion mit sehr wenigen Dokumenten.
FilesRetrieval basiert auf LlamaIndex. Sie müssen es gemäß der LlamaIndex-Dokumentation einrichten.
Nach der Einrichtung können Sie Ihre Dokumente in einen Ordner legen und so ein Abruftool erstellen:
company_policies_retrieval = FilesRetrieval(
name='company_policies',
description='Company policies about flight cancelation and rebooking.',
input_dir=os.path.join(os.path.dirname(__file__), 'company_policies'),
)
root_agent = Agent(
# ...
tools=[company_policies_retrieval],
)
VertexRagRetrieval
Die Vertex RAG-Engine ist ein vollständig verwalteter Dienst, der die Datenaufnahme, ‑transformation, ‑einbettung, ‑indexierung und ‑abfrage verarbeitet.
Folgen Sie der Kurzanleitung, um den Corpus einzurichten und Dokumente zu importieren. Fügen Sie das Tool dann Ihrem Kundenservicemitarbeiter hinzu.
company_policies_retrieval = VertexRagRetrieval(
name='company_policies',
description='Company policies about flight cancelation and rebooking.',
rag_corpus_name='projects/.../locations/.../ragCorpora/...',
)
root_agent = Agent(
# ...
tools=[company_policies_retrieval],
)
Google Suche verwenden
So kann er in Echtzeit auf aktuelles Wissen zugreifen und Fragen mithilfe der Google Suche recherchieren.
Hinweise
- Für die Fundierung mit der Google Suche können zusätzliche Gebühren anfallen.
- Für Gemini 1.5:
- Wenn Sie einem Kundenservicemitarbeiter das Google-Suchtool hinzufügen, können Sie für diesen Kundenservicemitarbeiter keine anderen Tools verwenden.
- Das Google-Suchtool wird immer ausgeführt, unabhängig davon, ob für die Suchanfrage die Google Suche erforderlich ist oder nicht.
- Gemini 2.0 und höher:
- Sie können andere Tools verwenden, während Sie das Google-Suchtool nutzen.
- Das Google-Suchtool wird nur ausgeführt, wenn das Modell es für erforderlich hält.
- Drittanbietermodelle unterstützen keine Google-Suchtools.
- Wenn Sie das Google-Suchtool verwenden möchten, müssen Sie die Richtlinien unter Google-Suchvorschläge verwenden einhalten. Dazu gehört auch, dass Sie immer ein Banner anzeigen, in dem ähnliche Suchanfragen in der Google Suche präsentiert werden. Diese Regeln gelten auch für die Entwickleroberfläche.
Beispiel
Das Google-Suchtool lässt sich ganz einfach aktivieren. Fügen Sie dazu einfach google_search zu Ihrer Toolliste hinzu.
from agents.tools import google_search
root_agent = Agent(
# ...
tools=[google_search],
)
Anleitung: Leistung des Kundenservicemitarbeiters bewerten
Die Bewertung Ihres Kundenservicemitarbeiters ist wichtig, damit er wie erwartet funktioniert und Ihren Qualitätsstandards entspricht. Das Agent Framework bietet mehrere Möglichkeiten, die Leistung von Kundenservicemitarbeitern mithilfe von Testdateien und Bewertungskriterien zu bewerten.
So funktioniert die Bewertung
Jede Testdatei enthält eine Liste von Abfragen, erwartete Tool-Trajektorien und Referenzantworten. Testdateien können in Ordnern organisiert werden. Optional kann ein Ordner eine test_config.json-Datei enthalten, in der die Bewertungskriterien angegeben sind.
Beispiel für eine Testdatei
Eine Testdatei enthält eine Sitzung mit Abfragen, der erwarteten Toolnutzung und Referenzantworten. Hier ein Beispiel:
[
{
"query": "hi",
"expected_tool_use": [],
"reference": "Hello! What can I do for you?\n"
},
{
"query": "roll a die for me",
"expected_tool_use": [
{
"tool_name": "roll_die",
"tool_input": {
"sides": 6
}
}
]
},
{
"query": "what's the time now?",
"expected_tool_use": [],
"reference": "I'm sorry, I cannot access real-time information, including the current time. My capabilities are limited to rolling dice and checking prime numbers.\n"
}
]
Bewertungskriterien
Die Bewertungskriterien in test_config.json legen fest, wie die Leistung des Kundenservicemitarbeiters gemessen wird:
tool_trajectory_avg_score: Bewerten Sie die Werkzeugbahnen.response_match_score: Antworten auswerten.
Wenn keine Bewertungskriterien angegeben werden, wird eine Standardkonfiguration angewendet.
Beispiel für Bewertungskriterien (test_config.json)
Hier sehen Sie ein Beispiel für eine test_config.json-Datei mit benutzerdefinierten Bewertungskriterien:
{
"criteria": {
"tool_trajectory_avg_score": 1.0,
"response_match_score": 0.8
}
}
tool_trajectory_avg_score: Ist auf „1.0“ festgelegt, wird eine perfekte Tool-Bahn erwartet.response_match_score: Ist auf 0,8 festgelegt, was einen kleinen Fehlertoleranzbereich bei den Antworten des Kundenservicemitarbeiters ermöglicht.
Möglichkeiten zur Ausführung der Bewertung
1. af web – Bewertungen über die Web-UI ausführen
Sie können Kundenservicemitarbeiter über unsere webbasierte Benutzeroberfläche interaktiv bewerten.
Schritte:
- Starten Sie den Webserver mit dem Befehl
bash af web. - In der Weboberfläche:
- Wählen Sie einen Agent aus.
- Klicken Sie auf Sitzung als Testdatei speichern, um eine Sitzung als Testdatei zu speichern.
- Klicken Sie auf Testdatei ausführen, um ein Pop-up-Fenster mit Testdateien im Ordner des Kundenservicemitarbeiters aufzurufen.
Testdateien:
Testdateien werden im selben Ordner wie der Agent gespeichert. Sie können Testdateien bei Bedarf manuell aktualisieren oder hinzufügen.
2. af test – Tests über die Befehlszeile ausführen
Mit dem Befehl af test können Sie alle Testdateien in einem bestimmten Ordner ausführen.
Der Ordner sollte die Agentendefinition und die Testdateien enthalten.
Beispiel:
af test samples/agent_folder
Mit diesem Befehl werden alle Testdateien (*.test.json) im angegebenen Ordner gefunden und ausgeführt.
3. pytest – Tests programmatisch ausführen
Sie können pytest auch verwenden, um Testdateien im Rahmen Ihrer Integrationstests auszuführen.
Beispielbefehl:
pytest tests/integrations/
Beispiel für Testcode:
Hier ist ein Beispiel für einen pytest-Testfall, mit dem eine einzelne Testdatei ausgeführt wird:
def test_with_single_test_file():
"""Test the agent's basic ability via a session file."""
AgentEvaluator.evaluate(
"tests.integration.fixture.home_automation_agent",
"tests/integration/fixture/home_automation_agent/simple_test.test.json",
)
Mit diesem Ansatz können Sie Agentenbewertungen in Ihre CI/CD-Pipelines oder größeren Test-Suites einbinden.