Поделиться через

Поверхность API общего агента семантического ядра

Агенты семантического ядра реализуют единый интерфейс для вызова, что позволяет унифицированному коду беспрепятственно работать с различными типами агентов. Эта конструкция позволяет переключать агенты по мере необходимости, не изменяя большую часть логики приложения.

Вызов агента

Интерфейс API агента поддерживает потоковый и непотоковый вызов.

Вызов агента без потоковой передачи

Семантический ядро поддерживает четыре перегрузки вызовов непотоковых агентов, которые позволяют передавать сообщения разными способами. Один из них также позволяет обращаться к агенту без каких-либо сообщений. Это полезно для сценариев, когда инструкции агента уже имеют все необходимые контексты для предоставления полезного ответа.

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

Это важно

Вызов агента без передачи AgentThread методу InvokeAsync создаст новый поток и вернет новый поток в качестве ответа.

Семантическое ядро поддерживает два метода вызова агента, которые не используют потоковую передачу и позволяют передавать сообщения различными способами. Кроме того, можно вызвать агента без сообщений. Это полезно для сценариев, когда инструкции агента уже имеют все необходимые контексты для предоставления полезного ответа.

Подсказка

Все аргументы, переданные в методы вызова агента, требуют, чтобы вызывающий передавал их в качестве именованных аргументов, за исключением первого позиционного аргумента. messages Вы можете вызвать messages, используя либо позиционный, либо ключевой аргумент. Например, оба await agent.get_response("What is the capital of France?") и await agent.get_response(messages="What is the capital of France?") поддерживаются. Все остальные параметры должны передаваться в качестве аргументов ключевых слов.

Использование метода 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?"),
    ]
)

Использование метода 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

Это важно

Вызов агента без передачи AgentThread методам get_response() или invoke() создаст новый поток и вернет новый поток в ответе.

Семантический ядро поддерживает три перегрузки вызовов агента без потоковой передачи, которые позволяют передавать сообщения разными способами. Один из них также позволяет обращаться к агенту без каких-либо сообщений. Это полезно для сценариев, когда инструкции агента уже имеют все необходимые контексты для предоставления полезного ответа.

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

Это важно

Вызов агента без передачи AgentThread методу invokeAsync создаст новый поток и вернет новый поток в качестве ответа.

Вызов стримингового агента

Семантический ядро поддерживает четыре перегрузки вызова агента потоковой передачи, которые позволяют передавать сообщения разными способами. Один из них также позволяет обращаться к агенту без каких-либо сообщений. Это полезно для сценариев, когда инструкции агента уже имеют все необходимые контексты для предоставления полезного ответа.

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

Это важно

Вызов агента без передачи AgentThread методу InvokeStreamingAsync создаст новый поток и вернет новый поток в качестве ответа.

Семантический ядро поддерживает один метод вызова агента потоковой передачи, который позволяет передавать сообщения разными способами. Кроме того, можно вызвать поток агента без сообщений. Это полезно для сценариев, когда инструкции агента уже имеют все необходимые контексты для предоставления полезного ответа.

# 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

Это важно

Вызов агента без передачи AgentThread методу invoke_stream() создаст новый поток и вернет новый поток в качестве ответа.

Функция в настоящее время недоступна в Java.

Вызов с помощью AgentThread

Все перегрузки методов вызова позволяют передавать параметр AgentThread. Это полезно для сценариев, когда у вас есть беседа с агентом, который вы хотите продолжить.

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

Все методы вызова также возвращают активный AgentThread как часть ответа на вызов.

  1. Если вы передали AgentThread методу вызова, возвращенный AgentThread объект будет таким же, как и переданный.
  2. Если вы не передали параметр AgentThread методу invoke, возвращенный объект AgentThread будет новым AgentThread.

Возвращенный объект AgentThread доступен для индивидуальных элементов ответа методов вызова вместе с сообщением ответа.

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

Подсказка

Дополнительные сведения о потоках агента см. в разделе "Архитектура потока агента".

Все аргументы ключевых слов метода вызова допускают передачу параметра AgentThread. Это полезно для сценариев, когда у вас есть беседа с агентом, который вы хотите продолжить.

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

Все методы вызова также возвращают активный AgentThread как часть ответа на вызов.

  1. Если вы передали AgentThread методу вызова, возвращенный AgentThread объект будет таким же, как и переданный.
  2. Если вы не передали параметр AgentThread методу invoke, возвращенный объект AgentThread будет новым AgentThread.

Возвращенный объект AgentThread доступен для индивидуальных элементов ответа методов вызова вместе с сообщением ответа.

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

Подсказка

Дополнительные сведения о потоках агента см. в разделе "Архитектура потока агента".

Два варианта перегрузки метода вызова позволяют передавать параметр AgentThread. Это полезно для сценариев, когда у вас есть беседа с агентом, который вы хотите продолжить.

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

Эти методы вызова также возвращают активный AgentThread в составе ответа вызова.

  1. Если вы передали AgentThread в метод вызова, возвращенный AgentThread будет новым экземпляром с предыдущими и новыми сообщениями.
  2. Если вы не передали параметр AgentThread методу invoke, возвращенный объект AgentThread будет новым AgentThread.

Возвращенный объект AgentThread доступен для индивидуальных элементов ответа методов вызова вместе с сообщением ответа.

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

Подсказка

Дополнительные сведения о потоках агента см. в разделе "Архитектура потока агента".

Вызов с использованием опций

Все перегрузки методов вызова позволяют передавать параметр AgentInvokeOptions. Этот класс параметров позволяет предоставлять любые необязательные параметры.

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

Ниже приведен список поддерживаемых параметров.

Свойство "Option" Описание
Ядро Переопределите ядро по умолчанию, используемое агентом для этого вызова.
Аргументы ядра Переопределите аргументы ядра по умолчанию, используемые агентом для этого вызова.
Дополнительные инструкции Укажите все инструкции в дополнение к исходному набору инструкций агента, которые применяются только к этому вызову.
OnIntermediateMessage Обратный вызов, который может получать все полностью сформированные сообщения, создаваемые внутренними процессами агента, включая вызовы функций и сообщения выполнения функций. Это также можно использовать для получения полных сообщений во время вызова потоковой передачи.

Вызов с использованием опций

Одна перегрузка метода вызова позволяет передавать AgentInvokeOptions параметр. Этот класс параметров позволяет предоставлять любые необязательные параметры.

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

Ниже приведен список поддерживаемых параметров.

Свойство "Option" Описание
Ядро Переопределите ядро по умолчанию, используемое агентом для этого вызова.
Аргументы ядра Переопределите аргументы ядра по умолчанию, используемые агентом для этого вызова.
Дополнительные инструкции Укажите все инструкции в дополнение к исходному набору инструкций агента, которые применяются только к этому вызову.
КонтекстВызова Переопределите контекст вызова по умолчанию, используемый агентом для этого вызова.

Управление экземплярами AgentThread

Вы можете вручную создать AgentThread экземпляр и передать его агенту при вызове или разрешить агенту автоматически создавать AgentThread экземпляр при вызове. Объект AgentThread представляет поток во всех его состояниях, включая: еще не создан, активен и удален.

AgentThread типы с реализацией на стороне сервера будут созданы при первом использовании и не нужно создавать вручную. Однако можно удалить поток с помощью AgentThread класса.

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

# Delete a thread
await agent_thread.delete()

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

Подсказка

Дополнительные сведения о потоках агента см. в разделе "Архитектура потока агента".

Дальнейшие шаги

Настройка агентов с плагинами

Познакомьтесь с агентом завершения чата

  • Last updated on