Kerangka kerja agen

Membuat agen harness

Harness tersedia sebagai kelas HarnessAgent di namespace Microsoft.Agents.AI (paket Microsoft.Agents.AI.Harness). Cara paling sederhana untuk membuatnya adalah dari IChatClient mana pun menggunakan metode ekstensi AsHarnessAgent:

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

// chatClient is any IChatClient implementation (Foundry, Azure OpenAI, OpenAI, Anthropic, ...).
AIAgent agent = chatClient.AsHarnessAgent();

AgentResponse response = await agent.RunAsync("Plan a weekend trip to Seattle.");
Console.WriteLine(response.Text);

Anda juga dapat membangun agen secara langsung:

AIAgent agent = new HarnessAgent(chatClient);

Sediakan HarnessAgentOptions untuk menyediakan instruksi dan alat. Instruksi pada tingkat harness (HarnessAgentOptions.HarnessInstructions) menjelaskan pedoman pengoperasian umum, sedangkan instruksi khusus tugas ditempatkan pada ChatOptions.Instructions. HarnessAgent dilengkapi dengan instruksi default pada tingkat harness (HarnessAgent.DefaultInstructions), tetapi Anda dapat menggantinya dengan instruksi Anda sendiri melalui HarnessAgentOptions.HarnessInstructions.

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    Name = "research-agent",
    ChatOptions = new ChatOptions
    {
        Instructions = "You are a research assistant focused on academic sources.",
        Tools = [AIFunctionFactory.Create(GetStockPrice)],
    },
});

Mengaktifkan pemadatan

Kompaksi mencegah loop pemanggilan alat yang panjang melebihi kapasitas jendela konteks. Jika tidak menggunakan riwayat obrolan yang disimpan oleh layanan inferensi, default InMemoryChatHistoryProvider juga diberi penyedia pemadatan yang sama sehingga riwayat obrolan yang disimpan dalam sesi juga dipadatkan. Berikan keduanya, yaitu ukuran jendela konteks maksimum dan ukuran output maksimum, untuk mengaktifkan strategi default yang mempertimbangkan anggaran token:

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    MaxContextWindowTokens = 128_000,
    MaxOutputTokens = 16_384,
});

Untuk menggunakan strategi Anda sendiri, atur HarnessAgentOptions.CompactionStrategy; untuk menonaktifkan pemadatan, atur DisableCompaction = true.

Menyesuaikan dan menonaktifkan fitur

Setiap kemampuan default memiliki bendera nonaktifkan yang sesuai pada HarnessAgentOptions, sehingga Anda dapat menyimpan alur yang Anda inginkan dan menghilangkan sisanya:

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    HarnessInstructions = "Custom operating guidelines here.",
    DisableTodoProvider = true,      // No todo list
    DisableAgentModeProvider = true, // No plan/execute modes
    DisableWebSearch = true,         // No hosted web search tool
    DisableFileMemory = true,        // No file-based session memory
});

Bendera lain termasuk DisableFileAccess, DisableAgentSkillsProvider, DisableToolAutoApproval, dan DisableOpenTelemetry. Anda juga dapat menambahkan penyedia konteks Anda sendiri melalui AIContextProviders dan mengarahkan penyedia keterampilan di lokasi kustom melalui AgentSkillsSource.

Mengulang sampai selesai

Secara bawaan, harness akan berjalan satu kali setiap kali dipanggil. Berikan satu atau beberapa LoopEvaluator instance untuk memanggil ulang agen secara otomatis hingga evaluator memutuskan bahwa prosesnya telah selesai (misalnya, ketika penanda penyelesaian muncul, predikat terpenuhi, atau penilai AI menyetujuinya):

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    LoopEvaluators = [new CompletionMarkerLoopEvaluator("DONE")],
});

Perulangan diterapkan sebagai dekorator agen paling luar, sehingga setiap iterasi merupakan eksekusi agen yang lengkap, yang secara independen disetujui oleh alat dan dilacak.

Shell dan agen latar belakang

Untuk membiarkan agen menjalankan perintah shell, lewati ShellExecutor. Ini menambahkan alat eksekusi shell yang memerlukan persetujuan dan penyedia yang menyisipkan informasi OS, shell, dan direktori kerja ke dalam konteks:

using Microsoft.Agents.AI.Tools.Shell;

// A shell confined to a working directory. Commands require approval by default;
// the deny-list is a UX pre-filter, not a security boundary.
await using var shell = new LocalShellExecutor(new LocalShellExecutorOptions
{
    WorkingDirectory = workingDir,
    ConfineWorkingDirectory = true,
    Policy = new ShellPolicy(denyList: [@"\brm\s+-rf\b", @"\bsudo\b"]),
});

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    ShellExecutor = shell,
});

Untuk mengaktifkan delegasi paralel, lewati sekumpulan agen latar belakang. Agen dapat mendelegasikan subtugas untuk dieksekusi secara bersamaan:

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    BackgroundAgents = [webSearchAgent, codeAgent],
});

Membuat agen harness

Harness tersedia sebagai fungsi pabrik create_harness_agent, yang menyusun Agent yang dikonfigurasi sepenuhnya dari klien obrolan. Formulir paling sederhana hanya memerlukan klien:

from agent_framework import create_harness_agent
from agent_framework.openai import OpenAIChatClient

agent = create_harness_agent(
    OpenAIChatClient(model="gpt-4o"),
)

session = agent.create_session()
response = await agent.run("Plan a weekend trip to Seattle.", session=session)
print(response.text)

Instruksi pada level harness menjelaskan panduan pengoperasian umum, sementara instruksi khusus tugas dicantumkan di dalam agent_instructions. Harness disertai instruksi default pada tingkat harness (DEFAULT_HARNESS_INSTRUCTIONS), yang dapat Anda ganti melalui harness_instructions. Anda juga dapat memberikan tool tambahan:

agent = create_harness_agent(
    client=client,
    name="research-agent",
    agent_instructions="You are a research assistant focused on academic sources.",
    tools=get_stock_price,
)

Mengaktifkan pemadatan

Kompaksi mencegah loop pemanggilan alat yang panjang melebihi kapasitas jendela konteks. Berikan ukuran maksimum jendela konteks model dan ukuran output maksimum untuk mengaktifkan strategi bawaan yang mempertimbangkan anggaran token:

agent = create_harness_agent(
    client=client,
    max_context_window_tokens=128_000,
    max_output_tokens=16_384,
)

Ketika parameter token atau strategi kustom tidak disediakan, pemadatan secara otomatis dinonaktifkan. Untuk menggunakan strategi Anda sendiri, berikan before_compaction_strategy dan/atau after_compaction_strategy; untuk menonaktifkan pemadatan secara eksplisit, atur disable_compaction=True.

Menyesuaikan dan menonaktifkan fitur

Setiap kemampuan default memiliki argumen kata kunci yang disable_* sesuai, sehingga Anda dapat menyimpan bagian yang Anda inginkan dan menghilangkan sisanya:

agent = create_harness_agent(
    client=client,
    harness_instructions="Custom operating guidelines here.",
    disable_todo=True,         # No todo list
    disable_mode=True,         # No plan/execute modes
    disable_web_search=True,   # No hosted web search tool
    disable_file_memory=True,  # No file-based session memory
)

Bendera lain termasuk disable_file_access, disable_tool_auto_approval, dan disable_compaction. Anda dapat mengarahkan penemuan keterampilan di lokasi kustom dengan skills_paths dan menambahkan penyedia Anda sendiri dengan context_providers.

Mengulang sampai selesai

Secara bawaan, harness akan berjalan satu kali setiap kali dipanggil. Teruskan predikat loop_should_continue untuk memanggil ulang agen secara otomatis hingga predikat menentukan bahwa prosesnya telah selesai. Gunakan loop_next_message untuk mengontrol perintah untuk setiap iterasi tindak lanjut dan loop_max_iterations untuk membatasi jumlah pass:

from agent_framework import create_harness_agent, todos_remaining

agent = create_harness_agent(
    client=client,
    loop_should_continue=todos_remaining(),
    loop_max_iterations=10,
)

Predikat dipanggil dengan argumen kata kunci (iteration, last_result, session, agent, dan seterusnya); todos_remaining menjalankan ulang agen selama daftar tugasnya masih memiliki item yang belum selesai. Untuk menulis sendiri, terima argumen kata kunci tersebut — misalnya, lambda *, last_result, **kwargs: "DONE" not in last_result.text.

Shell dan agen latar belakang

Agar agen dapat menjalankan perintah shell, berikan shell_executor (misalnya, LocalShellTool dari agent-framework-tools). Ini menambahkan alat eksekusi shell yang memerlukan persetujuan serta penyedia yang memeriksa OS dan lingkungan shell. Pemanggil bertanggung jawab atas siklus hidup eksekutor:

from agent_framework_tools.shell import LocalShellTool, ShellPolicy

# A shell confined to a working directory. Commands require approval by default;
# the deny-list is a UX pre-filter, not a security boundary.
async with LocalShellTool(
    workdir="./working",
    confine_workdir=True,
    policy=ShellPolicy(denylist=[r"\brm\s+-rf\b", r"\bsudo\b"]),
) as shell:
    agent = create_harness_agent(
        client=client,
        shell_executor=shell,
    )

Untuk mengaktifkan delegasi paralel, berikan serangkaian agen latar belakang. Agen dapat mendelegasikan subtugas untuk dieksekusi secara bersamaan:

agent = create_harness_agent(
    client=client,
    background_agents=[web_search_agent, code_agent],
)

Konsol sampel .NET adalah proyek Harness.Shared.Console. Titik masuknya adalah HarnessConsole.RunAgentAsync, yang menerima agen Anda, prompt placeholder, dan HarnessConsoleOptions opsional (pengamat, penangan perintah slash, warna mode):

using Harness.Shared.Console;

await HarnessConsole.RunAgentAsync(agent, userPrompt: "Ask me anything to get started.");

Sesuaikan terminal ini dengan pemantau, pemformat alat, dan penangan perintah Anda sendiri — atau fork sebagai dasar untuk pengalaman menggunakan terminal versi Anda sendiri. Lihat contoh harness .NET.

Konsol contoh Python adalah paket console di samping contoh harness. Titik masuknya adalah run_agent_async, yang menjalankan aplikasi berbasis Tekstual:

from console import run_agent_async

await run_agent_async(agent)

Strukturnya disusun berdasarkan observer, komponen UI, dan perintah slash, yang semuanya dapat diperluas melalui kelas dasar ConsoleObserver, ToolCallFormatter, dan CommandHandler (bergantung pada textual dan rich). Jalankan as-is, atau salin sebagai basis untuk pengalaman terminal Anda sendiri. Lihat contoh harness Python.