Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Agen harness, kadang-kadang disebut harness AI, adalah perancah runtime yang mengubah model bahasa menjadi agen yang dapat melakukan pekerjaan. Ini menggerakkan model dan pemanggilan alat, mengelola status dan konteks percakapan, menerapkan kebijakan persetujuan, dan dapat menjaga agar agen terus melangkah maju dalam tugas multilangkah.
Agent Framework menyediakan Harness yang berpendapat dan disertakan baterai untuk penelitian, pengkodan, analisis data, dan pekerjaan jangka panjang lainnya. Anda menyediakan klien obrolan dan hanya menyesuaikan kemampuan yang dibutuhkan aplikasi Anda.
Architecture
Harness merangkai komponen penyusun kerangka kerja agen yang sudah ada, alih-alih mendefinisikan runtime agen yang terpisah:
- Klien chat — menghubungkan agen dengan model.
- Alur obrolan — menambahkan pemanggilan fungsi, injeksi pesan, persistensi riwayat per panggilan layanan, dan pemadatan opsional.
- Penyedia agen dan konteks — tambahkan instruksi, alat, memori, status todo, mode operasi, dan kemampuan opsional yang tercakup sesi.
- Middleware dan dekorator — tambahkan penanganan persetujuan, observabilitas, dan perulangan terbatas opsional.
- UX Aplikasi — mengalirkan respons, menampilkan kemajuan, dan mengumpulkan input seperti persetujuan alat.
Objek yang dihasilkan tetap menjadi agen Agent Framework normal: HarnessAgent yang berasal dari AIAgent dalam .NET, atau yang Agent dikembalikan oleh create_harness_agent dalam Python. Sesinya menggunakan sesi dan abstraksi penyedia konteks yang sama dengan agen lain.
Memanfaatkan matriks kemampuan
| Capability | Perilaku alat uji | Panduan kanonis |
|---|---|---|
| Pemanggilan fungsi | Diaktifkan dengan batas iterasi per permintaan yang dapat dikonfigurasi. | Alat fungsi |
| Persistensi riwayat per panggilan layanan | Menyimpan riwayat setelah setiap panggilan model dalam proses pemanggilan alat. | Sesi |
| Pemadatan | Diaktifkan saat batas token atau strategi kustom disediakan. | Pemadatan |
| Pelacakan tugas | Diaktifkan secara default. | Perencanaan dan daftar tugas |
| Mode agen | Mode rencana dan eksekusi diaktifkan secara default. | Perencanaan dan daftar tugas |
| Memori file dan akses file | Memori file sesi diaktifkan secara bawaan; akses file yang dibagikan bersifat opsional. | Penyedia konteks |
| Persetujuan alat | Persetujuan permanen dan aturan persetujuan otomatis aktif secara default. | Persetujuan alat |
| OpenTelemetry | Observabilitas agen diaktifkan secara bawaan. | Keterlihatan |
| Pencarian web | Ditambahkan secara default di mana klien obrolan yang dipilih mendukungnya. | Pencarian web |
| Keterampilan Agen | Diaktifkan secara bawaan di .NET; diaktifkan secara opsional melalui penyedia atau jalur di Python. | Keterampilan Agen |
| Agen latar belakang | Delegasi paralel opsional untuk agen anak bernama. | Agen latar belakang |
| Eksekusi shell | Terdiri dari paket shell; pabrik Python dapat menyambungkannya secara otomatis. | Peralatan shell |
| Perulangan | Pemanggilan ulang dengan batasan berdasarkan evaluator atau predikat, bersifat opsional. | Perulangan agen |
Pendelegasian agen latar belakang terpisah dari respons latar belakang yang dikelola oleh penyedia. Agen latar belakang menjalankan agen anak untuk tugas yang didelegasikan; respons latar belakang memeriksa status secara berkala atau melanjutkan satu permintaan ke penyedia dengan menggunakan token kelanjutan.
Buat agen harness
Paket Microsoft.Agents.AI.Harness mengekspos HarnessAgent dalam ruang nama Microsoft.Agents.AI. Buat satu dari IChatClient apa pun dengan AsHarnessAgent, atau buat HarnessAgent langsung:
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
AIAgent agent = chatClient.AsHarnessAgent();
AgentResponse response = await agent.RunAsync("Plan a weekend trip to Seattle.");
Console.WriteLine(response.Text);
Gunakan HarnessAgentOptions untuk mengatur panduan operasi tingkat harness, instruksi khusus agen, dan opsi fitur:
AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
Name = "research-agent",
HarnessInstructions = "Use tools deliberately and report verified results.",
ChatOptions = new ChatOptions
{
Instructions = "You are a research assistant focused on academic sources.",
},
MaxContextWindowTokens = 128_000,
MaxOutputTokens = 16_384,
});
HarnessAgent.DefaultInstructions menyediakan panduan harness bawaan.
HarnessInstructions muncul sebelum ChatOptions.Instructions.
Menyesuaikan komposisi
Kemampuan default memiliki opsi yang ditargetkan, termasuk DisableTodoProvider, , DisableAgentModeProvider, DisableFileMemoryDisableAgentSkillsProvider, DisableWebSearch, DisableToolAutoApproval, DisableOpenTelemetry, dan DisableCompaction.
Tambahkan penyedia konteks kustom dengan AIContextProviders. Aktifkan akses file dengan FileAccessStore, delegasi latar belakang dengan BackgroundAgents, dan pengulangan dengan LoopEvaluators.
Buat agen harness
create_harness_agent factory mengembalikan Agent yang telah dikonfigurasi sepenuhnya:
from agent_framework import create_harness_agent
from agent_framework.openai import OpenAIChatClient
agent = create_harness_agent(
client=OpenAIChatClient(model="gpt-4o"),
)
session = agent.create_session()
response = await agent.run("Plan a weekend trip to Seattle.", session=session)
print(response.text)
Atur instruksi tingkat harness dan khusus agen secara terpisah:
agent = create_harness_agent(
client=client,
name="research-agent",
harness_instructions="Use tools deliberately and report verified results.",
agent_instructions="You are a research assistant focused on academic sources.",
max_context_window_tokens=128_000,
max_output_tokens=16_384,
)
DEFAULT_HARNESS_INSTRUCTIONS menyediakan panduan harness bawaan.
harness_instructions muncul sebelum agent_instructions.
Menyesuaikan komposisi
Nonaktifkan default dengan opsi seperti disable_todo, , disable_mode, disable_file_memory, disable_web_searchdisable_tool_auto_approval, dan disable_compaction.
Ganti penyedia bawaan dengan todo_provider atau mode_provider, dan tambahkan penyedia dengan context_providers. Kemampuan bersifat opsional melalui skills_provider atau skills_paths; akses file, agen latar belakang, alat shell, dan perulangan juga bersifat opsional.
Akses file menggunakan penyimpanan yang disediakan sebagai satu ruang kerja bersama secara default. Untuk mengisolasi file dengan ID sesi aktif, aktifkan akses file dengan cakupan sesi:
from agent_framework import FileSystemAgentFileStore, create_harness_agent
file_store = FileSystemAgentFileStore("agent-files")
agent = create_harness_agent(
client=client,
file_access_store=file_store,
file_access_session_scoped=True,
)
Untuk membagikan secara sengaja di beberapa sesi yang dipilih, buat FileAccessProvider(store=file_store, scope="tenant-1") secara langsung dan tambahkan melalui context_providers. Scope adalah kunci opak yang dipetakan ke folder yang dikelola oleh penyedia, bukan jalur. Akses tercakup gagal ditutup alih-alih menggunakan akar penyimpanan bersama saat ID sesi aktif maupun cakupan eksplisit tidak tersedia.
Saat akses file diaktifkan, gunakan file_access_grep untuk menemukan nomor baris berbasis 1, file_access_read_lines untuk memeriksa rentang inklusif, dan file_access_replace_lines untuk mengedit seluruh baris.
file_access_read_lines mengawali setiap baris dengan angka dan tabnya; hilangkan awalan tersebut saat meneruskan teks baris sebagai expected_line. Teks yang diharapkan mencegah nomor baris yang kedaluwarsa atau tidak cocok agar tidak mengedit baris yang salah.
file_access_grep menggunakan ekspresi reguler yang tidak peka huruf besar/kecil, menerima pola hingga 256 karakter, dan menerapkan batas waktu 10 detik untuk seluruh pencarian. Pola dan penelusuran yang tidak valid atau terlalu panjang serta melebihi batas akan menghasilkan error. Batasi direktori atau pola sebelum coba lagi.
Penting
file_access_grep mengembalikan teks baris yang sesuai beserta karakter akhir barisnya. Implementasi kustom AgentFileStore.search() harus mengembalikan nomor baris berbasis 1 yang membahas baris yang sama seperti AgentFileStore.split_lines() pada teks yang dikembalikan oleh read().
Nota
create_harness_agent dirilis. Proses latar belakang, akses file, dan perulangan tetap bersifat eksperimental, dan perkakas shell berasal dari paket pra-rilis agent-framework-tools.
Nota
Paket Harness Go saat ini tidak tersedia. Susun secara langsung agen Go, penyedia konteks, pemadatan, dan paket middleware yang sesuai. Lihat repositori Agent Framework Go untuk dukungan saat ini.
Contoh UX terminal
Harness tidak meresepkan antarmuka aplikasi. Repositori ini mencakup contoh aplikasi terminal yang menayangkan output secara streaming, menampilkan daftar tugas dan mode saat ini, menampilkan prompt persetujuan alat, serta menyediakan perintah seperti /todos, /mode, dan /exit.
Penting
Proyek konsol ini adalah sampel, bukan komponen kerangka kerja yang dikirim. Gunakan sebagai contoh yang dapat dijalankan atau sebagai titik awal untuk pengalaman terminal Anda sendiri.
Titik masuk sampel .NET adalah HarnessConsole.RunAgentAsync:
using Harness.Shared.Console;
await HarnessConsole.RunAgentAsync(
agent,
userPrompt: "Ask me anything to get started.");
Sesuaikan sampel dengan pengamat, pemformat alat, penangan perintah, dan HarnessConsoleOptions. Lihat contoh .NET Harness.
Sampel Python menggunakan paket berbasis console Tekstual di samping sampel Harness:
from console import run_agent_async
await run_agent_async(agent)
Sesuaikan sampel dengan pengamat, pemformat, perintah, dan komponen UI. Lihat contoh Python Harness.
Repositori ini saat ini tidak menyertakan sampel terminal Go Harness dalam bentuk paket.