Agentes em segundo plano

Os agentes de antecedentes permitem que um agente pai delegue tarefas independentes a agentes filhos nomeados. Cada tarefa é executada em simultâneo na sua própria sessão child-agent, enquanto o pai mantém um ID de tarefa que pode usar para esperar, obter resultados, continuar o trabalho ou libertar a tarefa.

Importante

Os agentes em segundo plano são experimentais.

Agentes de fundo são diferentes das respostas de fundo. Uma resposta em segundo plano representa um pedido de fornecedor que a aplicação consulta periodicamente ou retoma. Uma tarefa de agente em segundo plano invoca outro agente do Agent Framework e mais tarde envia o resultado de texto desse agente de volta ao pai.

Configurar manualmente os agentes em segundo plano

Cada agente subordinado deve ter um nome não vazio e único, sem distinção entre maiúsculas e minúsculas. Dê aos agentes infantis instruções focadas e apenas as ferramentas necessárias para o seu papel delegado.

Importa BackgroundAgentsProvider e adiciona-o a um agente normal através 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 fornecedor 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 para substituir as instruções deste. Inclua {background_agents} onde deve aparecer a lista formatada de agentes infantis.

Observação

O provedor do agente em segundo plano incluído no pacote, descrito nesta página, não está atualmente disponível em Go.

Ciclo de vida da tarefa

O fornecedor adiciona as mesmas ferramentas orientadas para modelos em .NET e Python:

Tool Ação ao longo do ciclo de vida
background_agents_start_task Inicia uma tarefa não bloqueante num agente nomeado e devolve o ID inteiro da tarefa.
background_agents_wait_for_first_completion Espere até que a primeira tarefa de um conjunto fornecido atinja um estado terminal.
background_agents_get_task_results Devolver mensagem concluída, uma mensagem de falha ou o estado atual.
background_agents_get_all_tasks Liste IDs, estatutos, nomes de agentes e descrições.
background_agents_continue_task Execute o input de seguimento na sessão filho existente após a conclusão ou falha de uma tarefa.
background_agents_clear_completed_task Remova uma tarefa do terminal e liberte a sua sessão filha.

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

  1. Inicia todas as tarefas independentes antes de esperar, para que as tarefas corram em simultâneo.
  2. Esperar pela primeira conclusão, obter esse resultado e repetir até não haver tarefas em execução.
  3. Continuar uma tarefa concluída ou falhada quando o trabalho de seguimento necessita do contexto de conversa existente.
  4. Limpe as tarefas do terminal após obter os resultados, a menos que seja necessário continuá-las.

O estado da tarefa é running, completed, failed, ou lost. Uma tarefa fica perdida quando o seu identificador de tarefa em execução ou a sua sessão subordinada não está disponível, por exemplo, após um reinício do processo ou o restauro da sessão. Metadados de tarefas serializáveis podem permanecer na sessão principal, mas o trabalho em tempo real e os handles de sessão filha não sobrevivem a esse limite.

Não existe nenhuma ferramenta de cancelamento no fornecedor. Deixe as tarefas em execução atingirem um estado terminal antes de as limpar.

Reutilize a mesma sessão principal entre turnos. Cada tarefa recebe uma sessão dedicada ao filho. Continuar uma tarefa do terminal reutiliza essa sessão filha; limpá-la remove os metadados da tarefa e liberta o identificador da sessão filha.

Os resultados da tarefa são devolvidos ao pai como texto. O fornecedor não reencaminha o pedido estruturado de aprovação de ferramentas de um agente filho através do agente principal, por isso configure os agentes filhos para concluírem o trabalho delegado sem aprovação interativa ou para gerirem as aprovações no anfitrião do agente filho.

Adiciona a espera automática manualmente

Envolva o elemento principal criado manualmente com LoopAgent. BackgroundTaskCompletionLoopEvaluator Continua apenas enquanto uma tarefa permanece no Running estado:

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

O avaliador interrompe a avaliação de tarefas concluídas, com falha e perdidas.

Adicione AgentLoopMiddleware ao elemento superior regular e associe o predicado de tarefa em segundo plano à sua função auxiliar da mensagem seguinte:

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 persistente da tarefa ainda indica que a tarefa está em execução.

A integração automática do ciclo de tarefas em segundo plano não está disponível atualmente no Go.

Utilize agentes em segundo plano com o Harness Agent

Utilize esta configuração quando também quiser o pipeline predefinido de planeamento, memória, aprovação e observabilidade do Harness Agent.

Defina HarnessAgentOptions.BackgroundAgents. Adicione o avaliador de conclusão quando o pai deve continuar a funcionar até que o trabalho delegado deixe de estar a funcionar:

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 fornecedor e a formatação da lista de agentes. A omissão de LoopEvaluators mantém disponível a delegação em segundo plano sem nova invocação automática.

Forneça background_agents a create_harness_agent. Emparelha-o com um loop limitado quando o pai deve esperar 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 fornecedor. O harness de Python ativa o middleware de aprovação automática de ferramentas por defeito, por isso, deve passar session em cada execução.

Observação

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

Considerações de segurança

Regista apenas agentes infantis em quem confias. O pai pode enviar-lhes texto derivado de contexto privado ou não confiável, e os seus resultados são adicionados novamente ao contexto do pai. Uma criança comprometida pode exfiltrar a entrada delegada ou devolver conteúdo indireto de injeção de prompt.

Passos seguintes

Planeia o trabalho e acompanha as tarefas

Aprofunde-se

  • Last updated on