백그라운드 에이전트를 사용하면 부모 에이전트가 독립적인 작업을 명명된 자식 에이전트에 위임할 수 있습니다. 각 작업은 자체 자식 에이전트 세션에서 동시에 실행되며, 부모는 대기, 결과 검색, 작업을 계속하거나 작업을 해제하는 데 사용할 수 있는 작업 ID를 유지합니다.
중요합니다
백그라운드 에이전트는 실험적입니다.
백그라운드 에이전트는 백그라운드 응답과 다릅니다. 백그라운드 응답은 애플리케이션이 폴링하거나 다시 시작하는 하나의 공급자 요청을 나타냅니다. 백그라운드 에이전트 작업은 다른 에이전트 프레임워크 에이전트를 호출하고 나중에 해당 에이전트의 텍스트 결과를 부모에 다시 공급합니다.
백그라운드 에이전트를 수동으로 설정
각 자식 에이전트는 비어 있지 않고 대/소문자를 구분하지 않고도 고유한 이름을 가져야 합니다. 자식 에이전트에 포커스가 있는 지침과 위임된 역할에 필요한 도구만 제공합니다.
ChatClientAgentOptions.AIContextProviders을 통해 BackgroundAgentsProvider을 가져와 일반 에이전트에 추가합니다:
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에 동일한 모델용 도구를 추가합니다.
| Tool | 수명 주기 작업 |
|---|---|
background_agents_start_task |
명명된 에이전트에서 차단 해제 작업을 시작하고 정수 작업 ID를 반환합니다. |
background_agents_wait_for_first_completion |
제공된 집합의 첫 번째 작업이 터미널 상태에 도달할 때까지 기다립니다. |
background_agents_get_task_results |
완료된 텍스트, 오류 메시지 또는 현재 상태를 반환합니다. |
background_agents_get_all_tasks |
ID, 상태, 에이전트 이름 및 설명을 나열합니다. |
background_agents_continue_task |
작업이 완료되거나 실패한 후 기존 자식 세션에서 후속 입력을 실행합니다. |
background_agents_clear_completed_task |
터미널 작업을 제거하고 자식 세션을 해제합니다. |
일반적인 부모 에이전트 시퀀스는 다음과 같습니다.
- 대기하기 전에 모든 독립적인 작업을 시작하므로 태스크가 동시에 실행됩니다.
- 첫 번째 완료를 기다린 후 해당 결과를 검색하고 작업이 실행되지 않을 때까지 반복합니다.
- 후속 작업에 기존 대화 컨텍스트가 필요한 경우 완료되거나 실패한 작업을 계속합니다.
- 결과를 가져온 후, 계속 진행할 터미널 작업이 아닌 경우 해당 작업을 지우세요.
작업 상태가 running, completed또는 failedlost. 프로세스 다시 시작 또는 세션 복원 후와 같이 In-Process 작업 핸들 또는 자식 세션을 사용할 수 없는 경우 작업이 손실됩니다. 직렬화 가능한 작업 메타데이터는 부모 세션에 남아 있을 수 있지만 진행 중인 작업 및 자식 세션 핸들은 해당 경계에서 유지되지 않습니다.
공급자에는 취소 도구가 없습니다. 작업을 지우기 전에 실행 중인 작업이 터미널 상태에 도달하도록 합니다.
동일한 부모 세션을 번갈아 다시 사용하세요. 각 작업은 전용 자식 세션을 받습니다. 터미널 작업을 계속하면 해당 자식 세션이 재사용됩니다. 지우면 작업 메타데이터가 제거되고 자식 세션 핸들이 해제됩니다.
작업 결과는 부모에 텍스트로 반환됩니다. 공급자는 자식의 구조적 도구 승인 요청을 부모를 통해 다시 프록시하지 않으므로 자식 에이전트가 대화형 승인 없이 위임된 작업을 완료하거나 자식 에이전트 호스트 내에서 승인을 처리하도록 구성합니다.
호스트에서 부모 세션 해제
비고
호스트 측 백그라운드 에이전트 세션 해제는 현재 .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를 일반 부모에 추가하고 백그라운드 작업 조건자를 다음 메시지 도우미와 연결합니다.
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 에이전트에서 백그라운드 에이전트 사용
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를 생략하면 자동 재호출 없이 백그라운드 위임을 계속 사용할 수 있습니다.
create_harness_agent에 background_agents을 공급하십시오. 부모가 자동으로 대기해야 하는 경우 바인딩된 루프와 페어링합니다.
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은(는) BackgroundAgentsProvider에서 wait_timeout_seconds와 동일한 제한된 대기를 구성합니다. Python 하네스는 기본적으로 도구 자동 승인 미들웨어를 활성화하므로 실행할 때마다 session를 전달하세요.
비고
Harness 에이전트 백그라운드 위임은 현재 Go에서 사용할 수 없습니다.
보안 고려 사항
신뢰할 수 있는 자식 에이전트만 등록하세요. 부모는 프라이빗 또는 신뢰할 수 없는 컨텍스트에서 파생된 텍스트를 보낼 수 있으며, 결과는 부모의 컨텍스트에 다시 추가됩니다. 손상된 자식은 위임된 입력을 반출하거나 간접 프롬프트 삽입 콘텐츠를 반환할 수 있습니다.