Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Los agentes en segundo plano permiten a un agente principal delegar tareas independientes en agentes secundarios identificados por nombre. Cada tarea se ejecuta de forma simultánea en su propia sesión de agente secundario, mientras que el agente principal conserva un identificador de tarea que puede utilizar para esperar, recuperar resultados, continuar el trabajo o liberar la tarea.
Important
Los agentes en segundo plano son experimentales.
Los agentes en segundo plano son diferentes de las respuestas en segundo plano. Una respuesta en segundo plano representa una solicitud de proveedor que la aplicación sondea o reanuda. Una tarea de agente en segundo plano invoca a otro agente del Marco de Agentes y, posteriormente, envía el resultado de texto de ese agente al agente principal.
Configuración manual de agentes en segundo plano
Cada agente secundario debe tener un nombre no vacío y único, sin distinción entre mayúsculas y minúsculas. Proporcione a los agentes secundarios instrucciones concretas y solo las herramientas necesarias para su función delegada.
Importe BackgroundAgentsProvider y agréguelo a un agente normal mediante 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 las instrucciones del proveedor y el formato de 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()
Pase instructions= a BackgroundAgentsProvider para reemplazar sus instrucciones. Incluya {background_agents} donde deba aparecer la lista formateada de agentes secundarios.
wait_timeout_seconds establece cuánto tiempo espera cada llamada a background_agents_wait_for_first_completion. Debe ser un entero positivo y el valor predeterminado es de 300 segundos. Si expira el tiempo de espera, la herramienta devuelve normalmente y deja las tareas en ejecución, por lo que el elemento primario puede llamarlo de nuevo.
Note
El proveedor de agente en segundo plano empaquetado descrito en esta página no está disponible actualmente en Go.
Ciclo de vida de la tarea
El proveedor agrega las mismas herramientas orientadas al modelo en .NET y Python:
| Herramienta | Acción de ciclo de vida |
|---|---|
background_agents_start_task |
Inicie una tarea no bloqueante en un agente especificado por nombre y devuelva el identificador entero de la tarea. |
background_agents_wait_for_first_completion |
Espere hasta que la primera tarea de un conjunto proporcionado alcance un estado terminal. |
background_agents_get_task_results |
Devuelve texto completado, un mensaje de error o el estado actual. |
background_agents_get_all_tasks |
Enumera los identificadores, los estados, los nombres de agente y las descripciones. |
background_agents_continue_task |
Ejecuta la entrada de seguimiento en la sesión secundaria existente una vez que la tarea se haya completado o haya fallado. |
background_agents_clear_completed_task |
Elimina una tarea terminal y libera su sesión secundaria. |
Una secuencia típica de agente principal es la siguiente:
- Inicie todas las tareas independientes antes de esperar, por lo que las tareas se ejecutan simultáneamente.
- Espere a la primera finalización, recupere ese resultado y repita hasta que no se ejecute ninguna tarea.
- Continúe una tarea completada o fallida cuando el trabajo posterior requiera el contexto de conversación existente.
- Borra las tareas terminales tras recuperar sus resultados, a menos que vayan a continuarse.
El estado de la tarea es running, completed, failedo lost. Una tarea se pierde cuando su identificador de tarea en proceso o la sesión secundaria no está disponible, como después de reiniciar un proceso o restaurar la sesión. Los metadatos de las tareas serializables pueden permanecer en la sesión principal, pero el trabajo en curso y los identificadores de las sesiones secundarias no sobreviven a ese límite.
No hay ninguna herramienta de cancelación en el proveedor. Deje que las tareas en ejecución lleguen a un estado de terminal antes de borrarlas.
Reutiliza la misma sesión principal en cada turno. Cada tarea recibe una sesión secundaria dedicada. Continuar con una tarea de terminal reutiliza esa sesión secundaria; borrarlo quita los metadatos de la tarea y libera el identificador de sesión secundaria.
Los resultados de las tareas se devuelven al agente principal en forma de texto. El proveedor no reenvía a través del agente principal la solicitud estructurada de aprobación de herramientas de una sesión secundaria, por lo que hay que configurar los agentes secundarios para que completen el trabajo delegado sin aprobación interactiva o administren sus aprobaciones dentro del host del agente secundario.
Libera una sesión principal desde el host
Note
La liberación de sesiones del agente en segundo plano por parte del host no está disponible actualmente en .NET.
Cuando el host expulsa o descarta una sesión principal, libera la tarea en proceso del proveedor y los identificadores de la sesión secundaria en un bloque 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) es una API de ciclo de vida del lado host, no una herramienta orientada al modelo. De forma predeterminada, cancela las tareas secundarias en ejecución y espera hasta 30 segundos a que se cancelen antes de liberar todo el estado de ejecución de la sesión principal. Establezca cancel_running=False para rechazar la publicación mientras se estén ejecutando tareas, o establezca timeout=None para esperar indefinidamente.
En cambio, background_agents_clear_completed_task permite al modelo eliminar una tarea terminal y su sesión hija durante una conversación. Rechaza las tareas en ejecución y no sustituye al cierre de la sesión principal por parte del host.
Note
Actualmente, la liberación de la sesión del agente en segundo plano por parte del host no está disponible en Go.
Agregar la espera automática manualmente
Envuelve la sesión principal compuesta manualmente con LoopAgent.
BackgroundTaskCompletionLoopEvaluator continúa solo mientras una tarea permanece en estado Running :
AIAgent loopingParent = new LoopAgent(
parentAgent,
new BackgroundTaskCompletionLoopEvaluator(),
new LoopAgentOptions { MaxIterations = 10 });
El evaluador se detiene en las tareas completadas, fallidas y perdidas.
Añade AgentLoopMiddleware a la sesión principal habitual y empareja el predicado de tarea en segundo plano con su ayudante de mensaje siguiente:
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,
)
],
)
El predicado solo continúa mientras el estado persistido de la tarea siga indicando que la tarea está en ejecución.
La integración automática del bucle de tareas en segundo plano no está disponible actualmente en Go.
Usar agentes en segundo plano con Harness Agent
Utiliza esta configuración cuando también desees el proceso predeterminado de planificación, memoria, aprobación y observabilidad del agente Harness.
Establezca HarnessAgentOptions.BackgroundAgents. Añade el evaluador de finalización cuando la sesión principal deba seguir ejecutándose hasta que el trabajo delegado ya no se esté ejecutando:
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 las instrucciones del proveedor y el formato de lista de agentes. Omitir LoopEvaluators hace que la delegación en segundo plano siga estando disponible sin que se vuelva a invocar automáticamente.
Proporcione background_agents a create_harness_agent. Combínalo con un bucle acotado cuando el agente principal deba esperar automáticamente:
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 reemplazar las instrucciones del proveedor.
background_agents_wait_timeout_seconds configura la misma espera limitada que wait_timeout_seconds en BackgroundAgentsProvider. El entorno de ejecución de Python activa de forma predeterminada el middleware de aprobación automática de herramientas, por lo que debes pasar session en cada ejecución.
Note
La delegación en segundo plano del agente de Harness no está disponible actualmente en Go.
Consideraciones de seguridad
Registra únicamente agentes secundarios en los que confíes. El agente principal puede enviarles texto derivado de un contexto privado o no fiable, y sus resultados se añaden de nuevo al contexto del agente principal. Un elemento secundario comprometido puede filtrar entradas delegadas o devolver contenido con inyección indirecta de prompts.