Agentes em segundo plano

Agentes de segundo plano permitem que um agente pai delegue tarefas independentes a agentes filhos nomeados. Cada tarefa é executada simultaneamente em sua própria sessão de agente filho, enquanto o processo pai mantém um ID de tarefa que pode ser utilizado para aguardar, recuperar resultados, dar continuidade ao trabalho ou liberar a tarefa.

Important

Agentes em segundo plano são experimentais.

Os agentes em segundo plano são diferentes das respostas em segundo plano. Uma resposta em segundo plano representa uma solicitação a um provedor que o aplicativo consulta periodicamente ou retoma. Uma tarefa de agente em segundo plano invoca outro agente do Agent Framework e, posteriormente, repassa o resultado em texto desse agente de volta ao agente de origem.

Configurar agentes em segundo plano manualmente

Cada agente filho deve ter um nome não vazio que seja único, independentemente de maiúsculas e minúsculas. Dê aos agentes filhos instruções específicas e apenas as ferramentas necessárias para sua função atribuída.

Importe BackgroundAgentsProvider e adicione-o a um agente regular por meio de 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 personaliza as instruções do provedor e a formatação da lista de agentes.

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

Passe instructions= para BackgroundAgentsProvider para substituir suas instruções. Inclua {background_agents} onde a lista formatada de agentes secundários deve ser exibida.

wait_timeout_seconds define por quanto tempo cada chamada para background_agents_wait_for_first_completion espera. Deve ser um inteiro positivo e o padrão é de 300 segundos. Se o tempo limite expirar, a ferramenta retornará normalmente e deixará as tarefas em execução, para que o pai possa chamá-lo novamente.

Note

O provedor de agente de segundo plano empacotado descrito nesta página não está disponível atualmente em Go.

Ciclo de vida da tarefa

O provedor adiciona as mesmas ferramentas voltadas para modelo em .NET e Python:

Tool Ação de ciclo de vida
background_agents_start_task Inicie uma tarefa não bloqueante em um agente nomeado e retorne o ID inteiro da tarefa.
background_agents_wait_for_first_completion Aguarde até que a primeira tarefa em um conjunto fornecido atinja um estado terminal.
background_agents_get_task_results Retornar o texto concluído, uma mensagem de falha ou o status atual.
background_agents_get_all_tasks Listar IDs, status, nomes de agente e descrições.
background_agents_continue_task Execute a entrada de acompanhamento na sessão filha existente após a conclusão ou falha de uma tarefa.
background_agents_clear_completed_task Remova uma tarefa terminal e libere sua sessão filha.

Uma sequência típica de pai-agente é:

  1. Inicie cada tarefa independente antes de esperar, para que as tarefas sejam executadas simultaneamente.
  2. Aguarde a primeira conclusão, recupere esse resultado e repita até que nenhuma tarefa esteja em execução.
  3. Retome uma tarefa concluída ou que tenha falhado quando o trabalho de acompanhamento exigir o contexto da conversa existente.
  4. Limpe as tarefas no terminal após obter seus resultados, a menos que você vá continuá-las.

O status da tarefa é running, completed, failedou lost. Uma tarefa é perdida quando seu identificador de tarefa em processo ou sessão filha não está disponível, como após uma reinicialização de processo ou restauração de sessão. Metadados de tarefa serializáveis ​​podem permanecer na sessão pai, mas o trabalho em andamento e os identificadores de sessão filha não sobrevivem a essa fronteira.

Não há nenhuma ferramenta de cancelamento no provedor. Permitir que as tarefas em execução atinjam um estado terminal antes de limpá-las.

Reutilize a mesma sessão pai entre turnos. Cada tarefa recebe uma sessão filha dedicada. Continuar uma tarefa de terminal reutiliza essa sessão filha; limpá-la remove os metadados da tarefa e libera o handle da sessão filha.

Os resultados da tarefa são retornados ao pai como texto. O provedor não encaminha a solicitação estruturada de aprovação de ferramenta de um agente filho de volta ao agente pai; portanto, configure os agentes filhos para realizar o trabalho delegado sem necessidade de aprovação interativa ou para gerenciar suas aprovações internamente no host do agente filho.

Liberar uma sessão pai do host

Note

O encerramento de sessão por agente em segundo plano no lado do host não está disponível atualmente no .NET.

Quando o host encerra ou descarta uma sessão pai, libere os identificadores da tarefa em processo e da sessão filha do provedor em um bloco 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) é uma API de ciclo de vida do lado do host, não uma ferramenta voltada para modelos. Por padrão, ele cancela a execução de tarefas filho e aguarda até 30 segundos para cancelamento antes de liberar todo o estado de runtime para a sessão pai. Defina cancel_running=False para rejeitar a liberação enquanto as tarefas estiverem em execução, ou defina timeout=None para aguardar indefinidamente.

Por outro lado, background_agents_clear_completed_task permite que o modelo remova uma tarefa terminal e sua sessão filho durante uma conversa. Ele rejeita a execução de tarefas e não substitui o teardown de sessão pai do lado do host.

Note

O encerramento de sessão pelo agente em segundo plano no lado do host não está disponível atualmente em Go.

Adicionar tempo de espera automático manualmente

Envolva o elemento pai composto manualmente com LoopAgent. BackgroundTaskCompletionLoopEvaluator continua somente enquanto uma tarefa permanece no Running estado:

AIAgent loopingParent = new LoopAgent(
    parentAgent,
    new BackgroundTaskCompletionLoopEvaluator(),
    new LoopAgentOptions { MaxIterations = 10 });

O avaliador para em tarefas concluídas, falhas e perdidas.

Adicione AgentLoopMiddleware ao pai regular e associe o predicado de tarefa em segundo plano ao seu auxiliar de próxima mensagem:

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,
        )
    ],
)

O predicado permanece válido apenas enquanto o estado persistido da tarefa ainda indicar uma tarefa em execução.

A integração automática de loop de tarefa em segundo plano não está disponível no momento no Go.

Usar agentes em segundo plano com o Harness Agent

Use essa configuração quando também quiser o pipeline padrão do Harness Agent para planejamento, memória, aprovação e observabilidade.

Defina HarnessAgentOptions.BackgroundAgents. Adicione o avaliador de conclusão quando o processo pai deve continuar em execução até que o trabalho delegado não esteja mais sendo executado:

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

Use HarnessAgentOptions.BackgroundAgentsProviderOptions para personalizar as instruções do provedor e a formatação da lista de agentes. Omitir LoopEvaluators mantém a delegação em segundo plano disponível sem reinvocação automática.

Forneça background_agents para create_harness_agent. Combine-o com um loop limitado quando o pai deve aguardar automaticamente:

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

Use background_agents_instructions para substituir as instruções do provedor. background_agents_wait_timeout_seconds configura a mesma espera limitada que wait_timeout_seconds em BackgroundAgentsProvider. O harness em Python habilita o middleware de aprovação automática de ferramentas por padrão; portanto, passe session em todas as execuções.

Note

A delegação em segundo plano do Harness Agent não está disponível atualmente no Go.

Considerações de segurança

Registre apenas os agentes filho em que você confia. O processo pai pode enviar texto proveniente de um contexto privado ou não confiável, e os resultados são incorporados novamente ao contexto do processo pai. Um filho comprometido pode exfiltrar entradas delegadas ou retornar conteúdo de injeção de prompt indireta.

Próximas Etapas 

Planeje o trabalho e acompanhe as tarefas

Aprofunde-se

  • Last updated on