Sdílet prostřednictvím

Sémantické jádro – Rozhraní API pro běžné agenty

Sémantické agenty jádra implementují jednotné rozhraní pro vyvolání, což umožňuje bezproblémový provoz sdíleného kódu napříč různými typy agentů. Tento návrh umožňuje podle potřeby přepínat agenty beze změny většiny logiky aplikace.

Vyvolání agenta

Rozhraní API agenta podporuje streamování i volání bez streamování.

Volání agenta bez použití streamování

Sémantické jádro podporuje čtyři přetížení volání agenta, která nevyužívají streamování a umožňují předávání zpráv různými způsoby. Jedním z těchto možností je také vyvolání agenta bez zpráv. To je užitečné pro scénáře, ve kterých už pokyny agenta mají veškerý požadovaný kontext, aby poskytovaly užitečnou odpověď.

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

Důležité

Vyvolání agenta bez předání AgentThread do metody InvokeAsync vytvoří nové vlákno a nové vlákno vrátí v odpovědi.

Sémantické jádro podporuje dvě nestreamované metody volání agenta, umožňující zprávy předávat různými způsoby. Agenta je také možné vyvolat bez zpráv. To je užitečné pro scénáře, ve kterých už pokyny agenta mají veškerý požadovaný kontext, aby poskytovaly užitečnou odpověď.

Návod

Všechny argumenty předané metodám vyvolání agenta vyžadují, aby je volající předal jako argumenty klíčového slova s výjimkou prvního pozičního argumentu. messages Můžete použít buď poziční argument, nebo argument klíčového slova pro messages. Například, jak await agent.get_response("What is the capital of France?"), tak await agent.get_response(messages="What is the capital of France?") jsou podporovány. Všechny ostatní parametry musí být předány jako argumenty klíčových slov.

Použití 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?"),
    ]
)

Použití 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

Důležité

Vyvolání agenta bez předání AgentThread do metod get_response() nebo invoke() vytvoří nové vlákno a nové vlákno se vrátí v odpovědi.

Sémantické jádro podporuje tři přetížení volání agenta bez streamování, které umožňuje předávání zpráv různými způsoby. Jedním z těchto možností je také vyvolání agenta bez zpráv. To je užitečné pro scénáře, ve kterých už pokyny agenta mají veškerý požadovaný kontext, aby poskytovaly užitečnou odpověď.

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

Důležité

Vyvolání agenta bez předání AgentThread do metody invokeAsync vytvoří nové vlákno a nové vlákno vrátí v odpovědi.

Vyvolání streamovacího agenta

Sémantické jádro podporuje čtyři přetížení funkcí pro vyvolání streamovacích agentů, které umožňují předávání zpráv různými způsoby. Jedním z těchto možností je také vyvolání agenta bez zpráv. To je užitečné pro scénáře, ve kterých už pokyny agenta mají veškerý požadovaný kontext, aby poskytovaly užitečnou odpověď.

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

Důležité

Vyvolání agenta bez předání AgentThread do metody InvokeStreamingAsync vytvoří nové vlákno a nové vlákno vrátí v odpovědi.

Sémantické jádro podporuje jednu metodu vyvolání agenta streamování, která umožňuje předávání zpráv různými způsoby. Je také možné vyvolat datový proud agenta bez zpráv. To je užitečné pro scénáře, ve kterých už pokyny agenta mají veškerý požadovaný kontext, aby poskytovaly užitečnou odpověď.

# 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

Důležité

Vyvolání agenta bez předání AgentThread do metody invoke_stream() vytvoří nové vlákno a nové vlákno vrátí v odpovědi.

Funkce aktuálně není dostupná v Javě.

Vyvolání pomocí AgentThread

Všechna přetížení metody vyvolání umožňují předání parametru AgentThread . To je užitečné ve scénářích, ve kterých máte existující konverzaci s agentem, ve které chcete pokračovat.

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

V rámci odpovědi na vyvolání všechny metody vyvolání vrací také aktivní AgentThread.

  1. Pokud jste předali AgentThread metodě invoke, vrácená AgentThread bude stejná jako ta, která byla předána.
  2. Pokud jste nepředali žádné AgentThread do metody vyvolání, vrácená AgentThread bude nový AgentThread.

Vrácený prvek AgentThread je dostupný u jednotlivých odpovědních položek při použití metod vyvolání společně se zprávou o odpovědi.

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

Návod

Další informace o vláknech agenta naleznete v části Architektura vláken agenta.

Všechny argumenty klíčového slova metody vyvolání umožňují předání parametru AgentThread . To je užitečné ve scénářích, ve kterých máte existující konverzaci s agentem, ve které chcete pokračovat.

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

V rámci odpovědi na vyvolání všechny metody vyvolání vrací také aktivní AgentThread.

  1. Pokud jste předali AgentThread metodě invoke, vrácená AgentThread bude stejná jako ta, která byla předána.
  2. Pokud jste nepředali žádné AgentThread do metody vyvolání, vrácená AgentThread bude nový AgentThread.

Vrácený prvek AgentThread je dostupný u jednotlivých odpovědních položek při použití metod vyvolání společně se zprávou o odpovědi.

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

Návod

Další informace o vláknech agenta naleznete v části Architektura vláken agenta.

Dvě přetížení vyvolávacích metod umožňují předání parametru AgentThread. To je užitečné ve scénářích, ve kterých máte existující konverzaci s agentem, ve které chcete pokračovat.

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

Tyto metody vyvolání také vracejí aktivní AgentThread v rámci odpovědi na vyvolání.

  1. Pokud jste předali AgentThread metodě invoke, vrácená AgentThread se stane novou instancí s předchozími a novými zprávami.
  2. Pokud jste nepředali žádné AgentThread do metody vyvolání, vrácená AgentThread bude nový AgentThread.

Vrácený prvek AgentThread je dostupný u jednotlivých odpovědních položek při použití metod vyvolání společně se zprávou o odpovědi.

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

Návod

Další informace o vláknech agenta naleznete v části Architektura vláken agenta.

Vyvolání s možnostmi

Všechna přetížení metody vyvolání umožňují předání parametru AgentInvokeOptions . Tato třída možností umožňuje poskytovat všechna volitelná nastavení.

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

Tady je seznam podporovaných možností.

Vlastnost volby Popis
jádro Přepište výchozí jádro používané agentem pro toto vyvolání.
Jádrové argumenty Přepište výchozí argumenty jádra používané agentem pro toto vyvolání.
Další pokyny Kromě původní sady instrukcí agenta uveďte všechny pokyny, které platí jenom pro toto vyvolání.
OnIntermediateMessage Zpětné volání, které může přijímat všechny plně vytvořené zprávy produkované interně agentem, včetně zpráv o volání funkcí a vyvolání funkcí. Dá se také použít k příjmu celých zpráv během spuštění streamování.

Vyvolání s možnostmi

Jedno přetížení metody vyvolání umožňuje předání parametru AgentInvokeOptions . Tato třída možností umožňuje poskytovat všechna volitelná nastavení.

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

Tady je seznam podporovaných možností.

Vlastnost volby Popis
jádro Přepište výchozí jádro používané agentem pro toto vyvolání.
Jádrové argumenty Přepište výchozí argumenty jádra používané agentem pro toto vyvolání.
Další pokyny Kromě původní sady instrukcí agenta uveďte všechny pokyny, které platí jenom pro toto vyvolání.
KontextVolání Přepište výchozí kontext vyvolání, který agent používá pro toto vyvolání.

Správa instancí AgentThread

Můžete ručně vytvořit AgentThread instanci a předat ji agentovi při vyvolání, nebo můžete nechat agenta vytvořit AgentThread instanci pro vás automaticky při vyvolání. Objekt AgentThread představuje vlákno ve všech jeho stavech, včetně: ještě není vytvořeno, aktivní a odstraněno.

AgentThread typy, které mají implementaci na straně serveru, se vytvoří při prvním použití a není nutné je vytvářet ručně. Vlákno však můžete odstranit pomocí AgentThread třídy.

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

# Delete a thread
await agent_thread.delete()

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

Návod

Další informace o vláknech agenta naleznete v části Architektura vláken agenta.

Další kroky

Konfigurace agentů pomocí modulů plug-in

Prozkoumejte agenta pro dokončování chatu

  • Last updated on