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, Agent yang dikembalikan oleh create_harness_agent dalam Python, atau *agent.Agent yang didukung penyedia dan dikonfigurasi dengan harness.AgentConfig di Go. 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. Konstruktor penyedia Go mengendalikan loop pemanggilan alat. | 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 dalam .NET dan Python. Go memerlukan komposisi provider yang eksplisit. | 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 default di .NET dan Go; harus diaktifkan secara opsional melalui penyedia atau jalur di Python. | Keterampilan Agen |
| Agen latar belakang | Delegasi paralel opsional untuk agen anak bernama di .NET dan Python. Tidak ada penyedia agen latar belakang Go dalam paket. | 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.
Tip
Untuk panduan agen pengkodian yang membantu menyusun aplikasi harness Python, instal agent-framework-builder-python.
Skill coding-agent eksternal ini terpisah dari kapabilitas Agent Skills runtime yang tercantum dalam matriks.
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.
Gunakan tool_name_prefix saat satu agen memiliki beberapa penyedia akses file. Awalan menghasilkan nama seperti workspace_file_access_read dan mencegah tabrakan nama alat. Untuk penyedia dengan prefiks, gunakan factory aturan persetujuan khusus penyedia sehingga setiap aturan cocok dengan nama yang dihasilkan penyedia:
from agent_framework import FileAccessProvider, create_harness_agent
workspace = FileAccessProvider(
store=file_store,
tool_name_prefix="workspace",
)
agent = create_harness_agent(
client=client,
context_providers=[workspace],
auto_approval_rules=[workspace.get_read_only_tools_auto_approval_rule()],
)
get_all_tools_auto_approval_rule() membuat aturan yang setara untuk alat baca dan alat tulis. Biarkan persetujuan penulisan tetap diaktifkan kecuali batas penyimpanan dan input alat tepercaya.
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.
Paket Go agent/harness merakit middleware, penyedia konteks, dan default riwayat untuk agen normal yang didukung penyedia. Panggil harness.AgentConfig(harness.Config{}, agent.Config{...}), tangani kesalahannya, dan teruskan konfigurasi yang dikembalikan ke konstruktor penyedia. Ini tidak memperkenalkan jenis agen terpisah atau perulangan eksekusi alat.
Buat agen harness
Contoh komposit mengonfigurasi agen harness yang didukung Foundry:
import (
"context"
"fmt"
"os"
"path/filepath"
"github.com/microsoft/agent-framework-go/agent"
"github.com/microsoft/agent-framework-go/agent/harness"
"github.com/microsoft/agent-framework-go/examples/internal/demo"
"github.com/microsoft/agent-framework-go/message"
"github.com/microsoft/agent-framework-go/provider/foundryprovider"
)
workingDirectory, err := os.Getwd()
if err != nil {
return fmt.Errorf("get working directory: %w", err)
}
cfg, err := harness.AgentConfig(harness.Config{WorkingDirectory: workingDirectory}, agent.Config{
Name: "HarnessAssistant",
Middlewares: []agent.Middleware{logger},
})
if err != nil {
return err
}
a := foundryprovider.NewAgent(
demo.FoundryProjectEndpoint,
demo.FoundryTokenCredential(),
foundryprovider.ModelDeployment(demo.FoundryModel),
foundryprovider.AgentConfig{
Config: cfg,
DisableStoreOutput: true,
Instructions: "Help with software engineering tasks. Use memory and todos to track the current session's work.",
},
)
Menyesuaikan komposisi
helper menetapkan pengaturan default berikut:
| Komponen | Go harness default |
|---|---|
| Planning | Alat tugas berbasis sesi dan mode perencanaan/eksekusi, dimulai dalam mode perencanaan |
| Memori berkas | File persisten di bawah agent-file-memory, dengan folder kerja terisolasi per sesi |
| Keterampilan | Penemuan yang didukung file dari direktori kerja, tidak termasuk subtree memori |
| Pencarian web | Deklarasi pencarian web yang dihosting, kecuali pemanggil telah lebih dulu menyediakannya |
| Approval | Middleware persetujuan permanen dan persetujuan otomatis untuk alat yang memerlukan persetujuan |
| History | Riwayat dalam memori dengan persistensi untuk setiap panggilan layanan |
| Injeksi pesan | per agen agent.MessageInjector |
| Menelusuri | Agent, alat, dan instrumentasi panggilan model yang didukung |
Gunakan harness.Config untuk menonaktifkan komponen atau menimpa konfigurasinya. Nonaktifkan pencarian web yang dihosting saat layanan atau deployment yang dipilih tidak mendukungnya. Skrip keterampilan yang didukung file memerlukan script runner yang dikonfigurasi secara eksplisit.
Pembantu mempertahankan alat pemanggil, middleware, penyedia konteks, dan penyedia riwayat yang dikonfigurasi secara eksplisit. Dengan penyebaran model Foundry, gunakan DisableStoreOutput: true saat riwayat lokal mengendalikan percakapan.
Alat pemadatan, looping, dan shell tidak ditambahkan oleh pembantu Go. Konfigurasikan item tersebut secara eksplisit saat diperlukan. Penyedia delegasi background-agent bawaan yang dijelaskan di SDK lain tidak tersedia di Go.
Lihat Membuat agen Go harness untuk penyiapan dan panduan konfigurasi Go harness untuk default dan penimpaan.
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 Go mencakup sampel harness komposit dengan penanganan persetujuan dan demo CLI obrolan interaktif terpisah. CLI obrolan menggunakan agen sederhana; ini tidak setara dengan konsol C# atau Python Harness.