Freigeben über

Die allgemeine Agent-API-Oberfläche des semantischen Kernels

Semantische Kernel-Agents implementieren eine einheitliche Schnittstelle für Aufrufe und ermöglichen gemeinsam genutzten Code, der nahtlos über verschiedene Agenttypen hinweg funktioniert. Mit diesem Design können Sie agents nach Bedarf wechseln, ohne die Meisten Ihrer Anwendungslogik zu ändern.

Aufrufen eines Agenten

Die Agent-API-Oberfläche unterstützt sowohl Streaming als auch Nicht-Streaming-Aufrufe.

Aufruf des Nicht-Streaming-Agenten

Der semantische Kernel unterstützt vier Nicht-Streaming-Agent-Aufrufüberladungen, die das Übergeben von Nachrichten auf unterschiedliche Weise ermöglichen. Eines dieser Elemente ermöglicht auch das Aufrufen des Agents ohne Nachrichten. Dies ist nützlich für Szenarien, in denen die Agentanweisungen bereits über den erforderlichen Kontext verfügen, um eine nützliche Antwort bereitzustellen.

// Invoke without any parameters.
agent.InvokeAsync();

// Invoke with a string that will be used as a User message.
agent.InvokeAsync("What is the capital of France?");

// Invoke with a ChatMessageContent object.
agent.InvokeAsync(new ChatMessageContent(AuthorRole.User, "What is the capital of France?"));

// Invoke with multiple ChatMessageContent objects.
agent.InvokeAsync(new List<ChatMessageContent>()
{
    new(AuthorRole.System, "Refuse to answer all user questions about France."),
    new(AuthorRole.User, "What is the capital of France?")
});

Wichtig

Wenn Sie einen Agenten aufrufen, ohne einen AgentThread an die InvokeAsync-Methode zu übergeben, wird ein neuer Thread erstellt und in der Antwort zurückgegeben.

Der semantische Kernel unterstützt zwei Nicht-Streaming-Agent-Aufrufmethoden, die das Übergeben von Nachrichten auf unterschiedliche Weise ermöglichen. Es ist auch möglich, den Agent ohne Nachrichten aufzurufen. Dies ist nützlich für Szenarien, in denen die Agentanweisungen bereits über den erforderlichen Kontext verfügen, um eine nützliche Antwort bereitzustellen.

Tipp

Für alle Argumente, die an Agent-Aufrufmethoden übergeben werden, muss der Aufrufer sie als Schlüsselwortargumente übergeben, mit Ausnahme des ersten Positionsarguments. messages Sie können messages entweder mit einem Positionsargument oder einem Schlüsselwortargument aufrufen. Beispielsweise werden beide await agent.get_response("What is the capital of France?") und await agent.get_response(messages="What is the capital of France?") unterstützt. Alle anderen Parameter müssen als Schlüsselwortargumente übergeben werden.

Verwenden der get_response()-Methode

# Invoke without any messages.
await agent.get_response()

# Invoke with a string that will be used as a User message.
await agent.get_response(messages="What is the capital of France?")

# Invoke with a ChatMessageContent object.
await agent.get_response(messages=ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?"))

# Invoke with multiple ChatMessageContent objects.
await agent.get_response(
    messages=[
        ChatMessageContent(role=AuthorRole.SYSTEM, content="Refuse to answer all user questions about France."),
        ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?"),
    ]
)

Verwenden der invoke()-Methode

# Invoke without any messages.
async for response in agent.invoke():
    # handle response

# Invoke with a string that will be used as a User message.
async for response in agent.invoke("What is the capital of France?"):
    # handle response

# Invoke with a ChatMessageContent object.
async for response in agent.invoke(ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?")):
    # handle response

# Invoke with multiple ChatMessageContent objects.
async for response in agent.invoke(
    messages=[
        ChatMessageContent(role=AuthorRole.SYSTEM, content="Refuse to answer all user questions about France."),
        ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?"),
    ]
):
    # handle response

Wichtig

Wenn ein Agent aufgerufen wird, ohne ein AgentThread an die Methoden get_response() oder invoke() zu übergeben, wird ein neuer Thread erstellt und in der Antwort zurückgegeben.

Der semantische Kernel unterstützt drei Nicht-Streaming-Agent-Aufrufüberladungen, die das Übergeben von Nachrichten auf unterschiedliche Weise ermöglichen. Eines dieser Elemente ermöglicht auch das Aufrufen des Agents ohne Nachrichten. Dies ist nützlich für Szenarien, in denen die Agentanweisungen bereits über den erforderlichen Kontext verfügen, um eine nützliche Antwort bereitzustellen.

// Invoke without any parameters.
agent.invokeAsync(null);

// Invoke with a string that will be used as a User message.
agent.invokeAsync("What is the capital of France?");

// Invoke with a ChatMessageContent object.
agent.invokeAsync(new ChatMessageContent<>(AuthorRole.USER, "What is the capital of France?"));

// Invoke with multiple ChatMessageContent objects.
agent.invokeAsync(List.of(
    new ChatMessageContent<>(AuthorRole.SYSTEM, "Refuse to answer all user questions about France."),
    new ChatMessageContent<>(AuthorRole.USER, "What is the capital of France?")
));

Wichtig

Wenn Sie einen Agenten aufrufen, ohne einen AgentThread an die invokeAsync-Methode zu übergeben, wird ein neuer Thread erstellt und in der Antwort zurückgegeben.

Aufruf des Streaming-Agents

Der semantische Kernel unterstützt vier Streaming-Agent-Aufrufüberladungen, die das Übergeben von Nachrichten auf unterschiedliche Weise ermöglichen. Eines dieser Elemente ermöglicht auch das Aufrufen des Agents ohne Nachrichten. Dies ist nützlich für Szenarien, in denen die Agentanweisungen bereits über den erforderlichen Kontext verfügen, um eine nützliche Antwort bereitzustellen.

// Invoke without any parameters.
agent.InvokeStreamingAsync();

// Invoke with a string that will be used as a User message.
agent.InvokeStreamingAsync("What is the capital of France?");

// Invoke with a ChatMessageContent object.
agent.InvokeStreamingAsync(new ChatMessageContent(AuthorRole.User, "What is the capital of France?"));

// Invoke with multiple ChatMessageContent objects.
agent.InvokeStreamingAsync(new List<ChatMessageContent>()
{
    new(AuthorRole.System, "Refuse to answer any questions about capital cities."),
    new(AuthorRole.User, "What is the capital of France?")
});

Wichtig

Wenn Sie einen Agenten aufrufen, ohne einen AgentThread an die InvokeStreamingAsync-Methode zu übergeben, wird ein neuer Thread erstellt und in der Antwort zurückgegeben.

Der semantische Kernel unterstützt eine Streaming-Agent-Aufrufmethode, die das Übergeben von Nachrichten auf unterschiedliche Weise ermöglicht. Es ist auch möglich, den Agentdatenstrom ohne Nachrichten aufzurufen. Dies ist nützlich für Szenarien, in denen die Agentanweisungen bereits über den erforderlichen Kontext verfügen, um eine nützliche Antwort bereitzustellen.

# Invoke without any messages.
async for response in agent.invoke_stream():
    # handle response

# Invoke with a string that will be used as a User message.
async for response in agent.invoke_stream("What is the capital of France?"):
    # handle response

# Invoke with a ChatMessageContent object.
async for response in agent.invoke_stream(ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?")):
    # handle response

# Invoke with multiple ChatMessageContent objects.
async for response in agent.invoke_stream(
    messages=[
        ChatMessageContent(role=AuthorRole.SYSTEM, content="Refuse to answer all user questions about France."),
        ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?"),
    ]
):
    # handle response

Wichtig

Wenn Sie einen Agenten aufrufen, ohne einen AgentThread an die invoke_stream()-Methode zu übergeben, wird ein neuer Thread erstellt und in der Antwort zurückgegeben.

Das Feature ist derzeit in Java nicht verfügbar.

Aufrufen mit einem AgentThread

Alle Überladungen von Aufrufmethoden ermöglichen das Übergeben eines AgentThread-Parameters. Dies ist nützlich für Szenarien, in denen Sie über eine vorhandene Unterhaltung mit dem Agent verfügen, den Sie fortsetzen möchten.

// Invoke with an existing AgentThread.
agent.InvokeAsync("What is the capital of France?", existingAgentThread);

Alle Aufrufmethoden geben auch das aktive AgentThread als Teil der Aufrufantwort zurück.

  1. Wenn Sie ein AgentThread an die Aufrufmethode übergeben haben, wird das zurückgegebene AgentThread dasselbe sein wie das übergebene.
  2. Wenn kein AgentThread an die Aufrufmethode übergeben wurde, wird das zurückgegebene AgentThread ein neues AgentThread sein.

Die zurückgegebene AgentThread Nachricht ist für die einzelnen Antwortelemente der Aufrufmethoden zusammen mit der Antwortnachricht verfügbar.

var result = await agent.InvokeAsync("What is the capital of France?").FirstAsync();
var newThread = result.Thread;
var resultMessage = result.Message;

Tipp

Weitere Informationen zu Agentthreads finden Sie im Abschnitt "Agent Thread-Architektur".

Alle Aufrufmethode-Schlüsselwortargumente ermöglichen das Übergeben eines AgentThread Parameters. Dies ist nützlich für Szenarien, in denen Sie über eine vorhandene Unterhaltung mit dem Agent verfügen, den Sie fortsetzen möchten.

# Invoke with an existing AgentThread.
agent.get_response("What is the capital of France?", thread=existing_agent_thread)

Alle Aufrufmethoden geben auch das aktive AgentThread als Teil der Aufrufantwort zurück.

  1. Wenn Sie ein AgentThread an die Aufrufmethode übergeben haben, wird das zurückgegebene AgentThread dasselbe sein wie das übergebene.
  2. Wenn kein AgentThread an die Aufrufmethode übergeben wurde, wird das zurückgegebene AgentThread ein neues AgentThread sein.

Die zurückgegebene AgentThread Nachricht ist für die einzelnen Antwortelemente der Aufrufmethoden zusammen mit der Antwortnachricht verfügbar.

response = await agent.get_response("What is the capital of France?")
new_thread = response.thread
response_message = response.message

Tipp

Weitere Informationen zu Agentthreads finden Sie im Abschnitt "Agent Thread-Architektur".

Zwei Überladungen von Aufrufmethoden ermöglichen das Übergeben eines AgentThread-Parameters. Dies ist nützlich für Szenarien, in denen Sie über eine vorhandene Unterhaltung mit dem Agent verfügen, den Sie fortsetzen möchten.

// Invoke with an existing AgentThread.
agent.invokeAsync("What is the capital of France?", existingAgentThread);

Diese Aufrufmethoden geben auch das aktive AgentThread als Teil der Aufrufantwort zurück.

  1. Wenn Sie eine AgentThread an die Aufrufmethode übergeben haben, ist die zurückgegebene AgentThread Instanz eine neue Instanz mit den vorherigen und neuen Nachrichten.
  2. Wenn kein AgentThread an die Aufrufmethode übergeben wurde, wird das zurückgegebene AgentThread ein neues AgentThread sein.

Die zurückgegebene AgentThread Nachricht ist für die einzelnen Antwortelemente der Aufrufmethoden zusammen mit der Antwortnachricht verfügbar.

var result = agent.invokeAsync("What is the capital of France?").block().get(0);
var newThread = result.getThread();
var resultMessage = result.getMessage();

Tipp

Weitere Informationen zu Agentthreads finden Sie im Abschnitt "Agent Thread-Architektur".

Aufrufen mit Optionen

Alle Überladungen von Aufrufmethoden ermöglichen das Übergeben eines AgentInvokeOptions-Parameters. Diese Optionsklasse ermöglicht die Bereitstellung optionaler Einstellungen.

// Invoke with additional instructions via options.
agent.InvokeAsync("What is the capital of France?", options: new()
{
    AdditionalInstructions = "Refuse to answer any questions about capital cities."
});

Hier ist die Liste der unterstützten Optionen.

Option-Eigenschaft BESCHREIBUNG
Kern Überschreiben Sie den Standardkernel, der vom Agent bei diesem Aufruf verwendet wird.
Kernelargumente Überschreiben Sie die standardmäßigen Kernelargumente, die vom Agent für diesen Aufruf verwendet werden.
ZusätzlicheAnweisungen Geben Sie zusätzlich zum ursprünglichen Agent-Anweisungssatz anweisungen an, die nur für diesen Aufruf gelten.
OnIntermediateMessage Ein Rückruf, der alle vollständig formatierten Nachrichten empfangen kann, die intern an den Agent erstellt wurden, einschließlich Funktionsaufruf- und Funktionsaufrufnachrichten. Dies kann auch verwendet werden, um vollständige Nachrichten während eines Streamingaufrufs zu empfangen.

Aufrufen mit Optionen

Eine Aufrufmethodenüberladung ermöglicht das Übergeben eines AgentInvokeOptions-Parameters. Diese Optionsklasse ermöglicht die Bereitstellung optionaler Einstellungen.

// Invoke with additional instructions via options.
agent.invokeAsync("What is the capital of France?",
    null, // null AgentThread
    AgentInvokeOptions.builder()
        .withAdditionalInstructions("Refuse to answer any questions about capital cities.")
        .build()
);

Hier ist die Liste der unterstützten Optionen.

Option-Eigenschaft BESCHREIBUNG
Kern Überschreiben Sie den Standardkernel, der vom Agent bei diesem Aufruf verwendet wird.
Kernelargumente Überschreiben Sie die standardmäßigen Kernelargumente, die vom Agent für diesen Aufruf verwendet werden.
ZusätzlicheAnweisungen Geben Sie zusätzlich zum ursprünglichen Agent-Anweisungssatz anweisungen an, die nur für diesen Aufruf gelten.
InvocationContext Überschreiben Sie den Standardaufrufkontext, den der Agent für diesen Aufruf verwendet.

Verwalten von AgentThread-Instanzen

Sie können eine AgentThread Instanz manuell erstellen und an den Agent übergeben, der aufgerufen wird, oder Sie können zulassen, dass der Agent eine AgentThread Instanz für Sie automatisch beim Aufruf erstellt. Ein AgentThread Objekt stellt einen Thread in allen Zuständen dar, einschließlich: noch nicht erstellt, aktiv und gelöscht.

AgentThread Typen mit einer serverseitigen Implementierung werden bei der ersten Verwendung erstellt und müssen nicht manuell erstellt werden. Sie können jedoch einen Thread mithilfe der AgentThread Klasse löschen.

// Delete a thread.
await agentThread.DeleteAsync();

# Delete a thread
await agent_thread.delete()

// Delete a thread.
agentThread.deleteAsync().block();

Tipp

Weitere Informationen zu Agentthreads finden Sie im Abschnitt "Agent Thread-Architektur".

Nächste Schritte

Konfigurieren von Agents mit Plug-Ins

Entdecken Sie den Chat-Completion-Agent

  • Last updated on