Udostępnij za pośrednictwem

Powierzchnia interfejsu API wspólnego agenta jądra semantycznego

Agenci jądra semantycznego implementują ujednolicony interfejs do wywoływania, umożliwiając współużytkowany kod, który działa bezproblemowo w różnych typach agentów. Ten projekt umożliwia przełączanie agentów zgodnie z potrzebami bez modyfikowania większości logiki aplikacji.

Wywoływanie agenta

Interfejs API agenta obsługuje wywołania strumieniowe i niestrumieniowe.

Wywołanie agenta spoza przesyłania strumieniowego

Semantyczne jądro obsługuje cztery przeciążenia agenta spoza przesyłania strumieniowego, które umożliwiają przekazywanie komunikatów na różne sposoby. Jeden z nich umożliwia również wywoływanie agenta bez komunikatów. Jest to przydatne w scenariuszach, w których instrukcje agenta mają już cały wymagany kontekst, aby zapewnić przydatną odpowiedź.

// 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?")
});

Ważne

Wywołanie agenta bez przekazania AgentThread argumentu do metody InvokeAsync spowoduje utworzenie nowego wątku i zwrócenie nowego wątku w zwróconej odpowiedzi.

Semantyczne jądro obsługuje dwie metody wywołania agenta spoza przesyłania strumieniowego, które umożliwiają przekazywanie komunikatów na różne sposoby. Można również wywołać agenta bez komunikatów. Jest to przydatne w scenariuszach, w których instrukcje agenta mają już cały wymagany kontekst, aby zapewnić przydatną odpowiedź.

Wskazówka

Wszystkie argumenty przekazane do metod wywołania agenta wymagają, aby obiekt wywołujący przekazał je jako argumenty kluczowe, z wyjątkiem pierwszego argumentu pozycyjnego . messages Można wywołać element messages za pomocą argumentu pozycyjnego lub kluczowego. Na przykład obsługiwane są zarówno metody, jak await agent.get_response("What is the capital of France?") i await agent.get_response(messages="What is the capital of France?") . Wszystkie inne parametry muszą być przekazywane jako argumenty słowa kluczowego.

Używanie metody get_response()

# 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?"),
    ]
)

Używanie metody invoke()

# 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

Ważne

Wywołanie agenta bez przekazania AgentThread do metod get_response() lub invoke() spowoduje utworzenie nowego wątku i zwrócenie nowego wątku w odpowiedzi.

Semantyczne jądro obsługuje trzy przeciążenia agenta spoza przesyłania strumieniowego, które umożliwiają przekazywanie komunikatów na różne sposoby. Jeden z nich umożliwia również wywoływanie agenta bez komunikatów. Jest to przydatne w scenariuszach, w których instrukcje agenta mają już cały wymagany kontekst, aby zapewnić przydatną odpowiedź.

// 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?")
));

Ważne

Wywołanie agenta bez przekazania AgentThread argumentu do metody invokeAsync spowoduje utworzenie nowego wątku i zwrócenie nowego wątku w zwróconej odpowiedzi.

Uruchomienie agenta przesyłania strumieniowego

Semantyczne jądro obsługuje cztery przeciążenia wywołania agenta przesyłania strumieniowego, które umożliwiają przekazywanie komunikatów na różne sposoby. Jeden z nich umożliwia również wywoływanie agenta bez komunikatów. Jest to przydatne w scenariuszach, w których instrukcje agenta mają już cały wymagany kontekst, aby zapewnić przydatną odpowiedź.

// 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?")
});

Ważne

Wywołanie agenta bez przekazania AgentThread argumentu do metody InvokeStreamingAsync spowoduje utworzenie nowego wątku i zwrócenie nowego wątku w zwróconej odpowiedzi.

Semantyczne jądro obsługuje jedną metodę wywołania agenta przesyłania strumieniowego, która umożliwia przekazywanie komunikatów na różne sposoby. Istnieje również możliwość uruchomienia strumienia agenta bez komunikatów. Jest to przydatne w scenariuszach, w których instrukcje agenta mają już cały wymagany kontekst, aby zapewnić przydatną odpowiedź.

# 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

Ważne

Wywołanie agenta bez przekazania AgentThread argumentu do metody invoke_stream() spowoduje utworzenie nowego wątku i zwrócenie nowego wątku w zwróconej odpowiedzi.

Funkcja jest obecnie niedostępna w języku Java.

Wywoływanie za pomocą elementu AgentThread

Wszystkie przeciążenia metody wywołania umożliwiają przekazywanie parametru AgentThread . Jest to przydatne w scenariuszach, w których masz istniejącą konwersację z agentem, który chcesz kontynuować.

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

Wszystkie metody wywołania zwracają również aktywne AgentThread w odpowiedzi na wywołanie.

  1. Jeśli przekażesz AgentThread do metody wywołania, zwrócony AgentThread będzie taki sam jak ten, który został przekazany.
  2. Jeśli nie przekazano żadnego argumentu do metody AgentThread, zwrócony AgentThread będzie nowym AgentThread.

Zwrócony AgentThread element jest dostępny dla poszczególnych elementów odpowiedzi metod wywołania wraz z komunikatem odpowiedzi.

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

Wskazówka

Aby uzyskać więcej informacji na temat wątków agentów, zobacz sekcję Architektura wątku agenta.

Wszystkie argumenty słowa kluczowego metody wywołania zezwalają na przekazywanie parametru AgentThread . Jest to przydatne w scenariuszach, w których masz istniejącą konwersację z agentem, który chcesz kontynuować.

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

Wszystkie metody wywołania zwracają również aktywne AgentThread w odpowiedzi na wywołanie.

  1. Jeśli przekażesz AgentThread do metody wywołania, zwrócony AgentThread będzie taki sam jak ten, który został przekazany.
  2. Jeśli nie przekazano żadnego argumentu do metody AgentThread, zwrócony AgentThread będzie nowym AgentThread.

Zwrócony AgentThread element jest dostępny dla poszczególnych elementów odpowiedzi metod wywołania wraz z komunikatem odpowiedzi.

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

Wskazówka

Aby uzyskać więcej informacji na temat wątków agentów, zobacz sekcję Architektura wątku agenta.

Dwa przeciążenia metody wywołania umożliwiają przekazanie parametru AgentThread . Jest to przydatne w scenariuszach, w których masz istniejącą konwersację z agentem, który chcesz kontynuować.

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

Te metody wywołania zwracają również aktywne AgentThread jako część odpowiedzi na wywołanie.

  1. Jeśli przekazano argument AgentThread do metody invoke, zwrócona AgentThread będzie nową instancją zawierającą zarówno poprzednie, jak i nowe komunikaty.
  2. Jeśli nie przekazano żadnego argumentu do metody AgentThread, zwrócony AgentThread będzie nowym AgentThread.

Zwrócony AgentThread element jest dostępny dla poszczególnych elementów odpowiedzi metod wywołania wraz z komunikatem odpowiedzi.

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

Wskazówka

Aby uzyskać więcej informacji na temat wątków agentów, zobacz sekcję Architektura wątku agenta.

Wywoływanie przy użyciu opcji

Wszystkie przeciążenia metody wywołania umożliwiają przekazywanie parametru AgentInvokeOptions . Ta klasa opcji umożliwia udostępnianie dowolnych ustawień opcjonalnych.

// 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."
});

Oto lista obsługiwanych opcji.

Właściwość Opcji Opis
Jądro Zastąpi domyślne jądro używane przez agenta dla tego wywołania.
ArgumentyJądra Zastąpij domyślne argumenty jądra używane przez agenta dla tego wywołania.
Dodatkowe instrukcje Podaj wszelkie instrukcje oprócz oryginalnego zestawu instrukcji agenta, które mają zastosowanie tylko do tego wywołania.
OnIntermediateMessage Funkcja zwrotna, która może odbierać wszystkie w pełni sformułowane wiadomości generowane wewnętrznie przez agenta, w tym wywołania funkcji i wiadomości wywołania funkcji. Można tego również użyć do odbierania pełnych komunikatów podczas wywołania przesyłania strumieniowego.

Wywoływanie przy użyciu opcji

Jedno z przeciążeń metod wywołania pozwala na przekazywanie parametru AgentInvokeOptions. Ta klasa opcji umożliwia udostępnianie dowolnych ustawień opcjonalnych.

// 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()
);

Oto lista obsługiwanych opcji.

Właściwość Opcji Opis
Jądro Zastąpi domyślne jądro używane przez agenta dla tego wywołania.
ArgumentyJądra Zastąpij domyślne argumenty jądra używane przez agenta dla tego wywołania.
Dodatkowe instrukcje Podaj wszelkie instrukcje oprócz oryginalnego zestawu instrukcji agenta, które mają zastosowanie tylko do tego wywołania.
KontekstWywołania Zastąpij domyślny kontekst wywołania, który agent używa na potrzeby tego wywołania.

Zarządzanie instancjami AgentThread

Możesz ręcznie utworzyć wystąpienie AgentThread i przekazać je agentowi podczas wywołania lub pozwolić agentowi automatycznie utworzyć dla ciebie wystąpienie AgentThread podczas wywołania. Obiekt AgentThread reprezentuje wątek we wszystkich jego stanach, w tym: nieutworzony, aktywny i usunięty.

AgentThread typy, które mają implementację po stronie serwera, zostaną utworzone przy pierwszym użyciu i nie trzeba ich tworzyć ręcznie. Można jednak usunąć wątek przy użyciu AgentThread klasy .

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

# Delete a thread
await agent_thread.delete()

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

Wskazówka

Aby uzyskać więcej informacji na temat wątków agentów, zobacz sekcję Architektura wątku agenta.

Dalsze kroki

Konfigurowanie agentów z wtyczkami

Eksplorowanie agenta uzupełniania czatu