Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Фоновые агенты позволяют родительскому агенту делегировать независимые задачи именованным дочерним агентам. Каждая задача выполняется параллельно в собственном сеансе дочернего агента, а родитель сохраняет идентификатор задачи, который он может использовать для ожидания, получения результатов, продолжения работы или выпуска задачи.
Это важно
Фоновые агенты являются экспериментальными.
Фоновые агенты отличаются от фоновых ответов. Ответ в фоновом режиме соответствует одному запросу к поставщику, который приложение опрашивает или возобновляет. Задача фонового агента вызывает другого агента Agent Framework, а затем передаёт текстовый результат этого агента обратно родительскому агенту.
Настройка фоновых агентов вручную
Каждый дочерний агент должен иметь непустое имя, уникальное без учёта регистра. Предоставьте дочерним агентам четкие инструкции и только те инструменты, которые необходимы для их порученной роли.
Импортируйте BackgroundAgentsProvider и добавьте его в обычный агент с помощью ChatClientAgentOptions.AIContextProviders:
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
var backgroundProvider = new BackgroundAgentsProvider(
[webSearchAgent, codeAnalysisAgent]);
AIAgent parentAgent = chatClient.AsAIAgent(new ChatClientAgentOptions
{
Name = "research-coordinator",
AIContextProviders = [backgroundProvider],
});
AgentSession session = await parentAgent.CreateSessionAsync();
BackgroundAgentsProviderOptions настраивает инструкции поставщика и форматирование списка агентов.
from agent_framework import Agent, BackgroundAgentsProvider
background_provider = BackgroundAgentsProvider(
[web_search_agent, code_analysis_agent],
wait_timeout_seconds=30,
)
parent_agent = Agent(
client=client,
name="research-coordinator",
context_providers=[background_provider],
)
session = parent_agent.create_session()
Передайте instructions= в BackgroundAgentsProvider, чтобы заменить его инструкции. Включите {background_agents} , где должен появиться отформатированный список дочерних агентов.
wait_timeout_seconds задает время ожидания каждого вызова background_agents_wait_for_first_completion . Оно должно быть положительным целым числом и по умолчанию — 300 секунд. Если истекает время ожидания, средство возвращается обычно и покидает выполняемые задачи, чтобы родитель смог снова вызвать его.
Замечание
Упакованный поставщик фонового агента, описанный на этой странице, в настоящее время недоступен в Go.
Жизненный цикл задач
Поставщик добавляет те же средства, доступные для модели, в .NET и Python:
| инструмент | Действие жизненного цикла |
|---|---|
background_agents_start_task |
Запустите неблокирующую задачу на именованном агенте и верните её целочисленный идентификатор. |
background_agents_wait_for_first_completion |
Подождите, пока первая из задач в указанном наборе не достигнет конечного состояния. |
background_agents_get_task_results |
Возвращает завершенный текст, сообщение об ошибке или текущее состояние. |
background_agents_get_all_tasks |
Список идентификаторов, состояний, имен агентов и описаний. |
background_agents_continue_task |
Выполните последующий ввод в существующем дочернем сеансе после завершения задачи или ее сбоя. |
background_agents_clear_completed_task |
Удалите задачу терминала и отпустите его дочерний сеанс. |
Типичная последовательность родительского агента следующая:
- Запускайте каждую независимую задачу до перехода в режим ожидания, чтобы задачи выполнялись параллельно.
- Дождитесь первого завершения, получите этот результат и повторяйте эти действия, пока не останется выполняющихся задач.
- Продолжить завершённую задачу или задачу, завершившуюся сбоем, если для дальнейшей работы требуется имеющийся контекст беседы.
- Удалять задачи терминала после получения их результатов, если их не планируется продолжать.
Состояние задачи : running, completedfailedили lost. Задача становится потерянной, когда дескриптор задачи внутри процесса или дочерний сеанс недоступен, например после перезапуска процесса или восстановления сеанса. Метаданные сериализуемой задачи могут оставаться в родительском сеансе, но выполняемая в этот момент работа и дескрипторы дочерних сеансов не переносятся через эту границу.
В поставщике нет средства отмены. Дождитесь, пока задачи достигнут конечного состояния, прежде чем очищать их.
Используйте тот же родительский сеанс на разных ходах. Каждая задача получает выделенный дочерний сеанс. При продолжении задачи в терминале повторно используется этот дочерний сеанс; при очистке удаляются метаданные задачи и освобождается дескриптор дочернего сеанса.
Результаты задачи возвращаются родительскому объекту в текстовом виде. Поставщик не перенаправляет структурированный запрос дочернего агента на утверждение использования инструмента обратно через родительский агент, поэтому настройте дочерние агенты так, чтобы они выполняли делегированную работу без интерактивного подтверждения, либо обрабатывайте такие подтверждения в хосте дочернего агента.
Освободить родительский сеанс на хосте
Замечание
Выпуск сеанса фонового агента на стороне узла в настоящее время недоступен в .NET.
Когда хост вытесняет или удаляет родительский сеанс, освободите выполняемую в процессе задачу поставщика и дескрипторы дочерних сеансов в блоке finally:
session = parent_agent.create_session()
try:
await parent_agent.run("Coordinate the research.", session=session)
finally:
await background_provider.release_session(session)
release_session(session, *, cancel_running=True, timeout=30.0) — это API жизненного цикла на стороне хоста, а не инструмент, предназначенный для модели. По умолчанию отменяется выполнение дочерних задач, и система ожидает до 30 секунд, пока отмена не завершится, прежде чем освободить все состояние среды выполнения родительского сеанса. Установите cancel_running=False, чтобы отклонять выпуск, пока выполняются задачи, или установите timeout=None, чтобы ждать неограниченно долго.
В отличие от этого, background_agents_clear_completed_task позволяет модели удалить одну терминальную задачу и её дочерний сеанс в ходе беседы. Отклоняет выполняющиеся задачи и не заменяет завершение родительского сеанса на стороне узла.
Замечание
Выпуск сеанса фонового агента на стороне узла в настоящее время недоступен в Go.
Добавление автоматического ожидания вручную
Оберните родительский элемент, созданный вручную, в LoopAgent.
BackgroundTaskCompletionLoopEvaluator продолжается только в то время, пока задача остается в Running состоянии:
AIAgent loopingParent = new LoopAgent(
parentAgent,
new BackgroundTaskCompletionLoopEvaluator(),
new LoopAgentOptions { MaxIterations = 10 });
Оценщик останавливается для завершённых, неудачно завершившихся и потерянных задач.
Добавьте AgentLoopMiddleware в обычный родитель и свяжите предикат фоновой задачи с его вспомогательной функцией next-message:
from agent_framework import (
Agent,
AgentLoopMiddleware,
background_tasks_running,
background_tasks_running_message,
)
parent_agent = Agent(
client=client,
context_providers=[background_provider],
middleware=[
AgentLoopMiddleware(
background_tasks_running(),
next_message=background_tasks_running_message,
max_iterations=10,
)
],
)
Предикат остаётся истинным только пока сохранённое состояние задачи по-прежнему указывает, что задача всё ещё выполняется.
Автоматическая интеграция цикла фоновых задач в настоящее время недоступна в Go.
Используйте фоновые агенты с Harness Agent
Используйте эту конфигурацию, если вам также нужен стандартный конвейер планирования, памяти, согласования и наблюдаемости агента Harness.
Задайте HarnessAgentOptions.BackgroundAgents. Добавьте средство оценки завершения, когда родитель должен продолжать работать до тех пор, пока делегированная работа больше не выполняется:
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
var options = new HarnessAgentOptions
{
Name = "research-coordinator",
BackgroundAgents = [webSearchAgent, codeAnalysisAgent],
LoopEvaluators = [new BackgroundTaskCompletionLoopEvaluator()],
LoopAgentOptions = new LoopAgentOptions { MaxIterations = 10 },
};
HarnessAgent parentAgent = chatClient.AsHarnessAgent(options);
// Equivalent construction: new HarnessAgent(chatClient, options)
AgentSession session = await parentAgent.CreateSessionAsync();
Используется HarnessAgentOptions.BackgroundAgentsProviderOptions для настройки инструкций поставщика и форматирования списка агентов. Если опустить LoopEvaluators, фоновое делегирование останется доступным без автоматического повторного вызова.
Подайте background_agents на create_harness_agent. Соедините его с привязанным циклом, когда родитель должен автоматически ждать:
from agent_framework import (
background_tasks_running,
background_tasks_running_message,
create_harness_agent,
)
parent_agent = create_harness_agent(
client=client,
name="research-coordinator",
background_agents=[web_search_agent, code_analysis_agent],
background_agents_wait_timeout_seconds=30,
loop_should_continue=background_tasks_running(),
loop_next_message=background_tasks_running_message,
loop_max_iterations=10,
)
session = parent_agent.create_session()
Используйте background_agents_instructions для замены инструкций поставщика.
background_agents_wait_timeout_seconds настраивает то же ограниченное ожидание, что и wait_timeout_seconds в BackgroundAgentsProvider. Среда выполнения Python по умолчанию включает промежуточный слой для автоматического одобрения инструментов, поэтому передавайте session при каждом запуске.
Замечание
В настоящее время фоновое делегирование в Harness Agent недоступно в Go.
Вопросы безопасности
Регистрируйте только дочерних агентов, которым вы доверяете. Родитель может отправлять им текст, полученный из закрытого или ненадёжного контекста, а полученные результаты добавляются обратно в контекст родителя. Скомпрометированный дочерний объект может эксфильтровать делегированные входные данные или возвращать непрямое содержимое внедрения запроса.