Ajan altyapıları

Bir harness ajanı oluşturma

Sarmalayıcı, HarnessAgent ad alanında (Microsoft.Agents.AI paketi) Microsoft.Agents.AI.Harness sınıfı olarak sunulur. Bunu oluşturmanın en basit yolu, IChatClient uzantı yöntemini kullanarak herhangi bir AsHarnessAgent öğesinden oluşturmaktır:

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

Aracıyı doğrudan da oluşturabilirsiniz:

AIAgent agent = new HarnessAgent(chatClient);

Yönergeler ve araçlar sağlamak için bir HarnessAgentOptions sağlayın. Harness düzeyi yönergeler (HarnessAgentOptions.HarnessInstructions) genel çalışma yönergelerini açıklarken, göreve özgü yönergeler ChatOptions.Instructions üzerinde yer alır. HarnessAgent, varsayılan harness düzeyi yönergelerle (HarnessAgent.DefaultInstructions) birlikte gelir, ancak bunları HarnessAgentOptions.HarnessInstructions aracılığıyla kendi yönergelerinizle geçersiz kılabilirsiniz.

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

Sıkıştırmayı etkinleştirme

Sıkıştırma, uzun araç çağrısı döngülerinin bağlam penceresini aşmasını önler. Çıkarım hizmetinde depolanan sohbet geçmişi kullanılmadığında, oturumda depolanan sohbet geçmişinin de sıkıştırılması için varsayılan InMemoryChatHistoryProvider öğesine aynı sıkıştırma sağlayıcısı da atanır. Varsayılan belirteç bütçesini dikkate alan stratejiyi etkinleştirmek için hem maksimum bağlam penceresi boyutunu hem de maksimum çıktı boyutunu sağlayın:

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

Kendi stratejinizi kullanmak için HarnessAgentOptions.CompactionStrategy olarak ayarlayın; sıkıştırmayı devre dışı bırakmak için DisableCompaction = true olarak ayarlayın.

Özellikleri özelleştirme ve devre dışı bırakma

Her varsayılan özelliğin üzerinde HarnessAgentOptionskarşılık gelen bir devre dışı bırakma bayrağı vardır, böylece istediğiniz işlem hattını tutabilir ve kalanları bırakabilirsiniz:

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

Diğer bayraklar , DisableFileAccess, DisableAgentSkillsProviderve DisableToolAutoApprovalbayraklarıdırDisableOpenTelemetry. Ayrıca, AIContextProviders aracılığıyla kendi bağlam sağlayıcılarınızı ekleyebilir ve AgentSkillsSource aracılığıyla beceri sağlayıcısını özel konumlara yönlendirebilirsiniz.

Bitirene kadar döngü oluşturma

Varsayılan olarak test düzeneği, çağrı başına bir kez çalışır. Değerlendiriciler bunun bittiğine karar verene kadar aracıyı otomatik olarak yeniden çağırmak için bir veya daha fazla LoopEvaluator örnek sağlayın (örneğin, bir tamamlama işaretçisi göründüğünde, bir koşul karşılandığında veya yapay zeka hakimi onaylayana kadar):

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

Döngü, en dıştaki Agent dekoratörü olarak uygulanır; bu nedenle her yineleme, araç tarafından bağımsız olarak onaylanan ve izlenen, eksiksiz bir agent çalıştırması niteliğindedir.

Shell ve arka plan ajanları

Ajanın kabuk komutlarını çalıştırmasına izin vermek için bir ShellExecutor sağlayın. Bu, onay gerektiren bir kabuk yürütme aracı ile işletim sistemi, kabuk ve çalışma dizini bilgilerini bağlama enjekte eden bir sağlayıcı ekler:

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,
});

Paralel yetki devrini etkinleştirmek için bir arka plan aracıları kümesi sağlayın. Ajan, alt görevleri eşzamanlı olarak yürütülmek üzere devredebilir:

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

Bir harness ajanı oluşturma

Koşum, bir sohbet istemcisinden tam olarak yapılandırılmış bir create_harness_agent oluşturan Agent fabrika işlevi olarak sunulur. En basit form yalnızca bir istemci gerektirir:

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)

Çerçeve düzeyindeki yönergeler genel işletim yönergelerini açıklar; göreve özgü yönergeler ise agent_instructions içinde yer alır. Harness, varsayılan harness düzeyindeki yönergelerle (DEFAULT_HARNESS_INSTRUCTIONS) birlikte gelir; bunları harness_instructions aracılığıyla geçersiz kılabilirsiniz. Ayrıca ek araçlar da iletebilirsiniz:

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

Sıkıştırmayı etkinleştirme

Sıkıştırma, uzun araç çağrısı döngülerinin bağlam penceresini aşmasını önler. Varsayılan belirteç bütçesini tanıyan stratejileri etkinleştirmek için hem modelin bağlam penceresi boyutunun üst sınırını hem de maksimum çıkış boyutunu sağlayın:

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

Belirteç parametresi veya özel strateji sağlanmazsa sıkıştırma otomatik olarak devre dışı bırakılır. Kendi stratejilerinizi kullanmak için before_compaction_strategy ve/veya after_compaction_strategy iletin; sıkıştırmayı açıkça kapatmak için disable_compaction=True olarak ayarlayın.

Özellikleri özelleştirme ve devre dışı bırakma

Her varsayılan özelliğin karşılık gelen disable_* bir anahtar sözcük bağımsız değişkeni vardır, böylece istediğiniz bölümleri tutabilir ve kalan bölümleri bırakabilirsiniz:

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
)

Diğer bayraklar arasında disable_file_access, disable_tool_auto_approval ve disable_compaction bulunur. skills_paths ile beceri bulmayı özel konumlara yönlendirebilir ve context_providers ile kendi sağlayıcılarınızı ekleyebilirsiniz.

Bitirene kadar döngü oluşturma

Varsayılan olarak test düzeneği, çağrı başına bir kez çalışır. Ajanı, yüklem işlemin tamamlandığına karar verene kadar otomatik olarak yeniden çağırmak için bir loop_should_continue yüklem geçirin. Her bir sonraki yineleme için istemi denetlemek üzere loop_next_message ve geçiş sayısını sınırlamak üzere loop_max_iterations kullanın:

from agent_framework import create_harness_agent, todos_remaining

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

Koşul anahtar sözcük bağımsız değişkenleriyle (iteration, last_result, session, agentvb.) çağrılır; todos_remaining yapılacaklar listesinde hala açık öğeler varken aracıyı yeniden çalıştırır. Kendinizinkini yazmak için bu anahtar sözcük argümanlarını kabul edin; örneğin, lambda *, last_result, **kwargs: "DONE" not in last_result.text.

Shell ve arka plan ajanları

Ajanın kabuk komutlarını çalıştırmasına izin vermek için bir shell_executor iletin (örneğin, LocalShellTool içinden agent-framework-tools). Bu, onay gerektiren bir kabuk çalıştırma aracına ek olarak işletim sistemi ve kabuk ortamını inceleyen bir sağlayıcı ekler. Çağıran, yürütücünün yaşam döngüsünden sorumludur:

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

Paralel yetki devrini etkinleştirmek için bir arka plan aracıları dizisi iletin. Ajan, alt görevleri eşzamanlı olarak yürütülmek üzere devredebilir:

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

.NET örnek konsol uygulaması, Harness.Shared.Console projesidir. Giriş noktası, aracınızı, yer tutucu bir istemi ve isteğe bağlı HarnessConsole.RunAgentAsync’i (gözlemciler, eğik çizgi komut işleyicileri, mod renkleri) girdi olarak alan HarnessConsoleOptions’dır:

using Harness.Shared.Console;

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

Onu kendi izleyicileriniz, araç biçimleyicileriniz ve komut işleyicilerinizle özelleştirin — ya da kendi terminal deneyiminiz için temel alıp çatallayın. Bkz. .NET test düzeneği örneklerini.

Python örnek konsolu, test harness örneklerinin yanında bulunan console paketidir. Giriş noktası run_agent_async olup Textual tabanlı bir uygulama çalıştırır:

from console import run_agent_async

await run_agent_async(agent)

Gözlemciler, UI bileşenleri ve slash komutları temelinde yapılandırılmıştır; bunların tümü ConsoleObserver, ToolCallFormatter ve CommandHandler temel sınıfları aracılığıyla genişletilebilir (textual ve rich'e bağlıdır). Onu olduğu gibi çalıştırın veya kendi terminal deneyiminiz için bir temel olarak kopyalayın. Bkz. Python harness örneklerini.