Partilhar via

A superfície da API do Semantic Kernel Common Agent

Os agentes do Kernel Semântico implementam uma interface unificada para invocação, permitindo código compartilhado que opera perfeitamente em diferentes tipos de agentes. Esse design permite que você alterne os agentes conforme necessário sem modificar a maioria da lógica do aplicativo.

Invocar um agente

A superfície da API do Agente suporta invocação de streaming e não streaming.

Invocação de agente não streaming

O Semantic Kernel suporta quatro sobrecargas de invocação de agente que não envolvem streaming, permitindo o envio de mensagens de formas distintas. Um deles também permite invocar o agente sem mensagens. Isso é valioso para cenários em que as instruções do agente já têm todo o contexto necessário para fornecer uma resposta útil.

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

Importante

Invocar um agente sem passar um AgentThread para o InvokeAsync método criará um novo thread e retornará o novo thread na resposta.

O Kernel Semântico suporta dois métodos de invocação de agentes não em fluxo contínuo, que permitem a passagem de mensagens de maneiras diferentes. Também é possível invocar o agente sem mensagens. Isso é valioso para cenários em que as instruções do agente já têm todo o contexto necessário para fornecer uma resposta útil.

Sugestão

Todos os argumentos passados para os métodos de invocação do Agent exigem que o chamador os passe como argumentos de palavra-chave, exceto o primeiro argumento posicional, messages. Você pode invocar com um argumento posicional ou de palavra-chave para messages. Por exemplo, ambos await agent.get_response("What is the capital of France?") e await agent.get_response(messages="What is the capital of France?") são suportados. Todos os outros parâmetros devem ser passados como argumentos de palavra-chave.

Usando o método 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?"),
    ]
)

Usando o método 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

Importante

Invocar um agente sem passar um AgentThread para os métodos get_response() ou invoke() criará um novo tópico e retornará o novo tópico na resposta.

O Semantic Kernel suporta três sobrecargas de invocação de agente, que não são de streaming, que permitem passar mensagens de maneiras diferentes. Um deles também permite invocar o agente sem mensagens. Isso é valioso para cenários em que as instruções do agente já têm todo o contexto necessário para fornecer uma resposta útil.

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

Importante

Invocar um agente sem passar um AgentThread para o invokeAsync método criará um novo thread e retornará o novo thread na resposta.

Invocação do agente de streaming

O Kernel Semântico suporta quatro sobrecargas de invocação do agente de streaming que permitem a passagem de mensagens de maneiras diferentes. Um deles também permite invocar o agente sem mensagens. Isso é valioso para cenários em que as instruções do agente já têm todo o contexto necessário para fornecer uma resposta útil.

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

Importante

Invocar um agente sem passar um AgentThread para o InvokeStreamingAsync método criará um novo thread e retornará o novo thread na resposta.

O Kernel Semântico suporta um método de invocação de agente de streaming que permite passar mensagens de maneiras diferentes. Também é possível invocar o fluxo do agente sem mensagens. Isso é valioso para cenários em que as instruções do agente já têm todo o contexto necessário para fornecer uma resposta útil.

# 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

Importante

Invocar um agente sem passar um AgentThread para o invoke_stream() método criará um novo thread e retornará o novo thread na resposta.

Recurso atualmente indisponível em Java.

Invocar com um AgentThread

Todas as sobrecargas de método de invocação permitem passar um parâmetro AgentThread. Isso é útil para cenários em que você tem uma conversa existente com o agente que deseja continuar.

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

Todos os métodos de invocação também retornam o ativo AgentThread como parte da resposta de invocação.

  1. Caso tenhas passado um AgentThread para o método invoke, o AgentThread retornado será o mesmo que o que foi fornecido a princípio.
  2. Se não passou AgentThread para o método invocar, o valor retornado AgentThread será um novo AgentThread.

O elemento retornado AgentThread está disponível nos itens de resposta individuais dos métodos de invocação juntamente com a mensagem de resposta.

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

Sugestão

Para obter mais informações sobre threads de agente, consulte a seção Arquitetura de threads de agente.

Todos os argumentos de palavra-chave do método de invocação permitem passar um AgentThread parâmetro. Isso é útil para cenários em que você tem uma conversa existente com o agente que deseja continuar.

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

Todos os métodos de invocação também retornam o ativo AgentThread como parte da resposta de invocação.

  1. Caso tenhas passado um AgentThread para o método invoke, o AgentThread retornado será o mesmo que o que foi fornecido a princípio.
  2. Se não passou AgentThread para o método invocar, o valor retornado AgentThread será um novo AgentThread.

O elemento retornado AgentThread está disponível nos itens de resposta individuais dos métodos de invocação juntamente com a mensagem de resposta.

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

Sugestão

Para obter mais informações sobre threads de agente, consulte a seção Arquitetura de threads de agente.

Duas sobrecargas de método de invocação permitem passar um AgentThread parâmetro. Isso é útil para cenários em que você tem uma conversa existente com o agente que deseja continuar.

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

Esses métodos de invocação também retornam o ativo AgentThread como parte da resposta de invocação.

  1. Se você passou um AgentThread para o método invoke, o retornado AgentThread será uma nova instância com as mensagens anteriores e novas.
  2. Se não passou AgentThread para o método invocar, o valor retornado AgentThread será um novo AgentThread.

O elemento retornado AgentThread está disponível nos itens de resposta individuais dos métodos de invocação juntamente com a mensagem de resposta.

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

Sugestão

Para obter mais informações sobre threads de agente, consulte a seção Arquitetura de threads de agente.

Invocação com Opções

Todas as sobrecargas de método de invocação permitem passar um parâmetro AgentInvokeOptions. Esta classe de opções permite fornecer quaisquer configurações opcionais.

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

Aqui está a lista das opções suportadas.

Propriedade de Opção Descrição
Núcleo Substitua o kernel padrão usado pelo agente para essa invocação.
Argumentos do Núcleo Substitua os argumentos padrão do kernel usados pelo agente para essa invocação.
Instruções adicionais Forneça quaisquer instruções, além do conjunto de instruções do agente original, que só se apliquem a esta invocação.
OnIntermediateMessage Um callback que pode receber todas as mensagens totalmente formadas produzidas internamente pelo Agente, incluindo chamadas de função e mensagens de invocação de função. Isso também pode ser usado para receber mensagens completas durante uma chamada de streaming.

Invocação com Opções

Uma sobrecarga de método de invocação permite passar um AgentInvokeOptions parâmetro. Esta classe de opções permite fornecer quaisquer configurações opcionais.

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

Aqui está a lista das opções suportadas.

Propriedade de Opção Descrição
Núcleo Substitua o kernel padrão usado pelo agente para essa invocação.
Argumentos do Núcleo Substitua os argumentos padrão do kernel usados pelo agente para essa invocação.
Instruções adicionais Forneça quaisquer instruções, além do conjunto de instruções do agente original, que só se apliquem a esta invocação.
InvocaçãoContexto Substitua o contexto de invocação padrão que o agente usa para essa invocação.

Gerenciando instâncias do AgentThread

Você pode criar manualmente uma AgentThread instância e passá-la para o agente ao invocar, ou pode permitir que o agente crie uma AgentThread instância para você automaticamente na chamada. Um AgentThread objeto representa um thread em todos os seus estados, incluindo: ainda não criado, ativo e excluído.

AgentThread Os tipos que têm uma implementação do lado do servidor serão criados no primeiro uso e não precisam ser criados manualmente. No entanto, você pode excluir um thread usando a AgentThread classe.

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

# Delete a thread
await agent_thread.delete()

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

Sugestão

Para obter mais informações sobre threads de agente, consulte a seção Arquitetura de threads de agente.

Próximos passos

Configurar agentes com plug-ins

Explore o Agente de Conclusão de Chat

  • Last updated on