Agen latar belakang

Agen latar belakang memungkinkan agen induk mendelegasikan tugas independen ke agen anak bernama. Setiap tugas berjalan bersamaan dalam sesi agen anaknya sendiri, sementara induk menyimpan ID tugas yang dapat digunakan untuk menunggu, mengambil hasil, melanjutkan pekerjaan, atau melepaskan tugas.

Penting

Agen latar belakang bersifat eksperimental.

Agen latar belakang berbeda dari respons latar belakang. Respons latar belakang mewakili satu permintaan penyedia yang dijajaki atau dilanjutkan oleh aplikasi. Tugas agen latar belakang memanggil agen Agent Framework lain dan kemudian meneruskan hasil teks agen tersebut kembali ke agen induk.

Menyiapkan agen latar belakang secara manual

Setiap agen anak harus memiliki nama yang tidak boleh kosong dan unik tanpa membedakan huruf besar/kecil. Berikan instruksi yang berfokus pada agen anak dan hanya alat yang diperlukan untuk peran yang didelegasikan.

Impor BackgroundAgentsProvider dan tambahkan ke agen reguler melalui 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 menyesuaikan instruksi penyedia dan pemformatan daftar agen.

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

Teruskan instructions= ke BackgroundAgentsProvider untuk mengganti instruksinya. Sertakan {background_agents} di tempat daftar subagen yang telah diformat akan ditampilkan.

wait_timeout_seconds mengatur berapa lama setiap panggilan menunggu pada background_agents_wait_for_first_completion. Ini harus berupa bilangan bulat positif dan nilai bawaannya adalah 300 detik. Jika batas waktu habis, alat akan kembali secara normal dan membiarkan tugas berjalan, sehingga induk dapat memanggilnya lagi.

Nota

Penyedia agen latar belakang paket yang dijelaskan di halaman ini saat ini tidak tersedia di Go.

Siklus hidup tugas

Penyedia menambahkan alat yang berinteraksi dengan model yang sama di .NET dan Python:

Alat Tindakan siklus hidup
background_agents_start_task Mulai tugas nonblocking pada agen bernama dan kembalikan ID tugas bilangan bulatnya.
background_agents_wait_for_first_completion Tunggu sampai tugas pertama dalam kumpulan yang diberikan mencapai keadaan akhir.
background_agents_get_task_results Mengembalikan teks lengkap, pesan kegagalan, atau status saat ini.
background_agents_get_all_tasks Mencantumkan ID, status, nama agen, dan deskripsi.
background_agents_continue_task Jalankan input tindak lanjut di sesi anak yang ada setelah tugas selesai atau gagal.
background_agents_clear_completed_task Hapus tugas terminal dan lepaskan sesi anaknya.

Urutan agen induk yang khas adalah:

  1. Mulai setiap tugas independen sebelum menunggu, sehingga tugas berjalan bersamaan.
  2. Tunggu hingga penyelesaian pertama, ambil hasil tersebut, dan ulangi hingga tidak ada tugas yang berjalan.
  3. Lanjutkan tugas yang telah selesai atau gagal saat pekerjaan lanjutan memerlukan konteks percakapan yang sudah ada.
  4. Hapus tugas terminal setelah hasilnya diambil, kecuali jika tugas tersebut akan dilanjutkan.

Status tugas adalah running, , completedfailed, atau lost. Tugas menjadi hilang ketika handel tugas dalam proses atau sesi anak tidak tersedia, seperti setelah proses dimulai ulang atau pemulihan sesi. Metadata tugas yang dapat diserialisasikan dapat tetap berada di sesi induk, tetapi handel pekerjaan dalam penerbangan dan sesi anak tidak bertahan dari batas tersebut.

Tidak ada alat pembatalan di penyedia. Biarkan menjalankan tugas mencapai status terminal sebelum menghapusnya.

Gunakan kembali sesi induk yang sama antar-giliran. Setiap tugas menerima sesi anak khusus. Melanjutkan tugas terminal akan menggunakan kembali sesi turunan tersebut; menghapusnya akan menghapus metadata tugas dan melepaskan handel sesi turunan.

Hasil tugas dikembalikan ke induk sebagai teks. Penyedia tidak mem-proksi permintaan persetujuan alat terstruktur anak kembali melalui induk, jadi konfigurasikan agen anak untuk menyelesaikan pekerjaan yang didelegasikan tanpa persetujuan interaktif atau menangani persetujuan mereka di dalam host agen anak.

Lepaskan sesi induk dari host

Nota

Rilis sesi agen latar belakang sisi host saat ini tidak tersedia di .NET.

Saat host menghapus atau membuang sesi induk, lepaskan tugas penyedia yang sedang berjalan dan handle sesi anak dalam blok 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) adalah API siklus hidup di sisi host, bukan alat yang ditujukan untuk model. Secara bawaan, ini membatalkan tugas anak yang sedang berjalan dan menunggu hingga 30 detik agar pembatalan selesai sebelum melepaskan seluruh status runtime untuk sesi induk. Atur cancel_running=False untuk menolak rilis saat tugas sedang berjalan, atau atur timeout=None untuk menunggu tanpa batas waktu.

Sebaliknya, background_agents_clear_completed_task memungkinkan model menghapus satu tugas terminal dan sesi turunannya selama percakapan. Fitur ini menolak tugas yang sedang berjalan dan tidak menggantikan pengakhiran sesi induk di sisi host.

Nota

Pelepasan sesi agen latar belakang pada sisi host saat ini belum tersedia dalam Go.

Tambahkan waktu tunggu otomatis secara manual

Bungkus elemen induk yang disusun secara manual dengan LoopAgent. BackgroundTaskCompletionLoopEvaluator berlanjut hanya saat tugas tetap dalam status Running :

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

Evaluator berhenti pada tugas yang selesai, gagal, dan hilang.

Tambahkan AgentLoopMiddleware ke elemen induk biasa dan pasangkan predikat background-task dengan helper next-message-nya:

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

Predikat hanya berlanjut selama status tugas yang tersimpan masih menunjukkan bahwa tugas sedang berjalan.

Integrasi perulangan tugas latar belakang otomatis saat ini tidak tersedia di Go.

Gunakan agen latar belakang dengan Harness Agent

Gunakan konfigurasi ini jika Anda juga menginginkan pipeline default Harness Agent untuk perencanaan, memori, persetujuan, dan observabilitas.

Atur HarnessAgentOptions.BackgroundAgents. Tambahkan evaluator penyelesaian saat proses induk harus tetap berjalan hingga pekerjaan yang didelegasikan tidak lagi berjalan:

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

Gunakan HarnessAgentOptions.BackgroundAgentsProviderOptions untuk menyesuaikan instruksi penyedia dan pemformatan daftar agen. Menghilangkan LoopEvaluators membuat delegasi latar belakang tetap tersedia tanpa pemanggilan ulang otomatis.

Pasokan background_agents ke create_harness_agent. Padukan dengan loop berbatas saat proses induk perlu menunggu secara otomatis:

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

Gunakan background_agents_instructions untuk mengganti instruksi penyedia. background_agents_wait_timeout_seconds mengonfigurasi tunggu terikat yang sama seperti wait_timeout_seconds pada BackgroundAgentsProvider. Harness Python mengaktifkan middleware persetujuan otomatis untuk alat secara default, jadi sertakan session pada setiap eksekusi.

Nota

Delegasi latar belakang Harness Agent saat ini tidak tersedia di Go.

Pertimbangan keamanan

Hanya daftarkan agen anak yang Anda percayai. Induk dapat mengirimi mereka teks yang berasal dari konteks privat atau tidak tepercaya, dan hasilnya ditambahkan kembali ke konteks induk. Anak yang disusupi dapat menyelundupkan input yang didelegasikan atau mengembalikan konten injeksi prompt tidak langsung.

Langkah berikutnya

Rencanakan pekerjaan dan lacak tugas

Mempelajari secara lebih mendalam

  • Last updated on