Agentes em segundo plano

Os agentes em segundo plano permitem que um agente pai delega tarefas independentes a agentes filho nomeados. Cada tarefa é executada simultaneamente em sua própria sessão de agente filho, enquanto o pai mantém uma ID de tarefa que pode usar para aguardar, recuperar resultados, continuar o trabalho ou liberar a tarefa.

Importante

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 de provedor que o aplicativo sonda ou retoma. Uma tarefa de agente em segundo plano invoca outro agente do Agent Framework e, posteriormente, alimenta o resultado de texto do agente de volta para o pai.

Configurar agentes em segundo plano manualmente

Cada agente filho deve ter um nome único sem diferenciação de maiúsculas de minúsculas. Dê aos agentes filho instruções focadas e apenas as ferramentas necessárias para sua função delegada.

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

parent_agent = Agent(
    client=client,
    name="research-coordinator",
    context_providers=[background_provider],
)
session = parent_agent.create_session()

Passe instructions= para BackgroundAgentsProvider substituir suas instruções. Inclua {background_agents} onde a lista de agente filho formatado deve aparecer.

Note

O provedor de agente de plano de fundo empacotado descrito nesta página não está disponível no momento no Go.

Ciclo de vida da tarefa

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

Tool Ação do ciclo de vida
background_agents_start_task Inicie uma tarefa sem bloqueio em um agente nomeado e retorne sua ID de tarefa inteiro.
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 filho existente depois que uma tarefa for concluída ou falhar.
background_agents_clear_completed_task Remova uma tarefa de terminal e libere sua sessão filho.

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. Continue uma tarefa concluída ou com falha quando o trabalho de acompanhamento precisar de seu contexto de conversa existente.
  4. Desmarque as tarefas do terminal depois de recuperar seus resultados, a menos que elas continuem.

O status da tarefa é running, completed, failedou lost. Uma tarefa se perde quando seu identificador de tarefa em processo ou sessão filho não está disponível, como após uma reinicialização do processo ou restauração da sessão. Metadados de tarefa serializáveis podem permanecer na sessão pai, mas os identificadores de trabalho em voo e de sessão filho não sobrevivem a esse limite.

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 filho dedicada. Continuar uma tarefa de terminal reutiliza essa sessão filho; desmarcar remove os metadados da tarefa e libera o identificador de sessão filho.

Os resultados da tarefa são retornados ao pai como texto. O provedor não faz proxy da solicitação de aprovação de ferramenta estruturada de uma criança por meio do pai, portanto, configure os agentes filho para concluir o trabalho delegado sem aprovação interativa ou lidar com suas aprovações dentro do host do agente filho.

Adicionar espera automática manualmente

Encapsular o 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 tarefas concluídas, com falha e perdidas.

Adicione AgentLoopMiddleware ao pai regular e emparelhe o predicado de tarefa em segundo plano com 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 continua apenas enquanto o estado de tarefa persistente ainda relata 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 você também quiser o pipeline padrão de planejamento, memória, aprovação e observabilidade do Harness Agent.

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

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 invocação automática.

Fornecer background_agents para create_harness_agent. Emparelhe-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],
    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. O Python harness habilita o middleware de aprovação automática da ferramenta por padrão, portanto, passe session todas as execuções.

Note

No momento, a delegação em segundo plano do Harness Agent não está disponível no Go.

Considerações de segurança

Registre apenas os agentes filho em que você confia. O pai pode enviar-lhes texto derivado de contexto privado ou não confiável e seus resultados são adicionados de volta ao contexto do pai. Um filho comprometido pode exfiltrar a entrada delegada ou retornar conteúdo indireto de injeção de prompt.

Próximas Etapas 

Planejar o trabalho e acompanhar todos

Aprofunde-se

  • Last updated on