Aracı Koşum

Ajan çerçevesi, bazen YZ çerçevesi olarak da adlandırılır ve bir dil modelini iş gerçekleştirebilen bir ajana dönüştüren çalışma zamanı altyapısıdır. Model ve araç çağrılarını yönlendirir, konuşma durumunu ve bağlamını yönetir, onay ilkeleri uygular ve aracının çok adımlı bir görev aracılığıyla ilerlemesini sağlayabilir.

Agent Framework, araştırma, kodlama, veri analizi ve diğer uzun süren işler için, belirli tercihleri olan ve ihtiyaç duyulan bileşenleri yerleşik olarak sunan bir altyapı sağlar. Bir sohbet istemcisi sağlar ve yalnızca uygulamanızın ihtiyaç duyduğu özellikleri özelleştirebilirsiniz.

Architecture

Harness, ayrı bir aracı çalışma zamanı tanımlamak yerine mevcut Agent Framework yapı taşları oluşturur:

  1. Sohbet istemcisi — aracıyı bir modele bağlar.
  2. Sohbet işlem hattı — işlev çağırma, ileti ekleme, hizmet başına çağrı geçmişi kalıcılığı ve isteğe bağlı sıkıştırma ekler.
  3. Ajan ve bağlam sağlayıcıları — oturum kapsamındaki yönergeler, araçlar, bellek, yapılacaklar durumu, işletim modları ve isteğe bağlı özellikler ekleyin.
  4. Ara yazılım ve dekoratörler — onay işleme desteği, gözlemlenebilirlik ve isteğe bağlı sınırlı döngüleme ekleyin.
  5. Uygulama UX — yanıtları akışa alır, ilerleme durumunu görüntüler ve araç onayları gibi girişleri toplar.

Ortaya çıkan nesne, normal bir Agent Framework aracısı olarak kalır: .NET'te AIAgent'den türeyen bir HarnessAgent veya Python'da create_harness_agent tarafından döndürülen bir Agent. Oturumlarında diğer aracılarla aynı oturum ve bağlam sağlayıcısı soyutlamaları kullanılır.

Yetenek matrisinden yararlanma

Capability Kullanım davranışı Resmî kılavuz
İşlev çağırma yapılandırılabilir istek başına yineleme sınırıyla etkinleştirilir. İşlev araçları
Hizmet başına çağrı geçmişi kalıcılığı Araç çağrılı bir çalıştırmada her model çağrısından sonra geçmişi kalıcı olarak saklar. Oturumlar
Sıkıştırma Belirteç sınırları veya özel bir strateji belirtildiğinde etkinleştirilir. Sıkıştırma
Yapılacaklar izleme Varsayılan olarak etkindir. Planlama ve yapılacaklar
Ajan modları Plan ve yürütme modları varsayılan olarak etkindir. Planlama ve yapılacaklar
Dosya belleği ve dosya erişimi Oturum dosyası belleği varsayılan olarak etkindir; paylaşılan dosya erişimi kabul edilir. Bağlam sağlayıcıları
Araç onayı Sürekli onaylar ve otomatik onay kuralları varsayılan olarak etkindir. Araç onayı
OpenTelemetry Aracı gözlemlenebilirliği varsayılan olarak etkindir. Gözlemlenebilirlik
Web araması Seçili sohbet istemcisinin desteklediği varsayılan olarak eklenir. Web araması
Ajan Yetenekleri .NET'te varsayılan olarak etkindir; Python'da bir sağlayıcı veya yollar aracılığıyla isteğe bağlı olarak etkinleştirilir. Aracı Becerileri
Arka plan aracıları Adlandırılmış alt aracılara isteğe bağlı paralel yetki devri. Arka plan aracıları
Kabuk yürütme Shell paketinden oluşur; Python factory’si bunu otomatik olarak bağlayabilir. Komut satırı araçları
Döngü Değerlendiriciler veya önkoşullar tarafından yönlendirilen isteğe bağlı sınırlanmış yeniden çağırma. Ajan döngüsü

Arka plan aracısı temsilcisi, sağlayıcı tarafından yönetilen arka plan yanıtlarından ayrıdır. Arka plan aracıları, kendilerine devredilen görevlerde alt aracıları çalıştırır; arka plan yanıtları, bir devam belirteci kullanarak tek bir sağlayıcı isteğini yoklar ya da sürdürür.

Bir harness ajanı oluşturun

Microsoft.Agents.AI.Harness paketi, Microsoft.Agents.AI ad alanında HarnessAgent kullanımına sunar. Herhangi bir IChatClient öğesinden AsHarnessAgent ile bir tane oluşturun veya HarnessAgent öğesini doğrudan oluşturun:

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

HarnessAgentOptions kullanarak koşum düzeyinde çalıştırma yönergelerini, aracıya özgü yönergeleri ve özellik seçeneklerini ayarlayın:

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 varsayılan harness yönergelerini sağlar. HarnessInstructions önce ChatOptions.Instructionsgörünür.

Bileşimi özelleştirin

Varsayılan özellikler, DisableTodoProvider, DisableAgentModeProvider, DisableFileMemory, DisableAgentSkillsProvider, DisableWebSearch, DisableToolAutoApproval, DisableOpenTelemetry ve DisableCompaction dahil olmak üzere hedefe yönelik seçeneklere sahiptir.

ile AIContextProvidersözel bağlam sağlayıcıları ekleyin. FileAccessStore ile dosya erişimine, BackgroundAgents ile arka plan devrine ve LoopEvaluators ile döngüye alma özelliğine izin verin.

Bir harness ajanı oluşturun

create_harness_agent fabrikası, tam olarak yapılandırılmış bir Agent döndürür:

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)

Harness düzeyindeki ve ajana özgü yönergeleri ayrı ayrı ayarlayın:

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 varsayılan harness yönergelerini sağlar. harness_instructions önce agent_instructionsgörünür.

Bileşimi özelleştirin

disable_todo, disable_mode, disable_file_memory, disable_web_search, disable_tool_auto_approval ve disable_compaction gibi seçeneklerle varsayılanları devre dışı bırakın.

Yerleşik sağlayıcıları todo_provider veya mode_provider ile değiştirin ve context_providers ile sağlayıcı ekleyin. Beceriler skills_provider veya skills_paths üzerinden isteğe bağlı olarak etkinleştirilir; dosya erişimi, arka plan ajanları, komut kabuğu araçları ve döngü oluşturma da isteğe bağlıdır.

Dosya erişimi, sağlanan depoyu varsayılan olarak tek bir paylaşılan çalışma alanı olarak kullanır. Dosyaları etkin oturum kimliğine göre yalıtmak için oturum kapsamlı dosya erişimini etkinleştirin:

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

Belirli oturumlar arasında bilerek paylaşım için FileAccessProvider(store=file_store, scope="tenant-1") öğesini doğrudan oluşturun ve context_providers aracılığıyla ekleyin. Kapsam, bir yol değil, sağlayıcı tarafından yönetilen bir klasöre karşılık gelen opak bir anahtardır. Etkin bir oturum kimliği ya da açıkça belirtilmiş bir kapsam bulunmadığında, kapsamlandırılmış erişim paylaşılan veri deposunun kökünü kullanmak yerine kapalı duruma düşer.

Dosya erişimi etkinleştirildiğinde, 1 tabanlı satır numaralarını bulmak, file_access_read_lines kapsayıcı bir aralığı incelemek ve file_access_replace_lines satırların tamamını düzenlemek için kullanınfile_access_grep. file_access_read_lines her satırın önüne numarası ve bir sekme ekler; satır metnini olarak expected_linegeçirirken bu ön eki atlayın. Beklenen metin, güncelliğini yitirmiş veya uyuşmayan bir satır numarasının yanlış satırın düzenlenmesine yol açmasını engeller.

file_access_grep büyük/küçük harfe duyarsız normal ifadeler kullanır, 256 karaktere kadar desenleri kabul eder ve aramanın tamamına 10 saniyelik bir bütçe uygular. Geçersiz veya fazla uzun desenler ve bütçeyi aşan aramalar hata döndürür. Yeniden denemeden önce dizini veya düzeni daraltın.

Önemli

file_access_grep eşleşen satır metnini satır sonlandırıcısıyla döndürür. Özel bir AgentFileStore.search() uygulaması, AgentFileStore.split_lines() tarafından döndürülen metin üzerinde read() ile aynı satırlara karşılık gelen 1 tabanlı satır numaraları döndürmelidir.

Uyarı

create_harness_agent yayımlandı. Arka plan aracıları, dosya erişimi ve döngü oluşturma hâlâ deneysel, kabuk araçları ise agent-framework-tools yayın öncesi paketten geliyor.

Uyarı

Paketlenmiş bir Go Harness şu anda mevcut değil. İlgili Go aracısını, bağlam sağlayıcısını, sıkıştırmayı ve ara yazılım paketlerini doğrudan oluşturun. Geçerli destek için bkz. Agent Framework Go deposu .

Örnek terminal UX

Harness, bir uygulama arayüzünü zorunlu kılmaz. Depo, çıktı akışı sağlayan, yapılacaklar listesini ve geçerli modu görüntüleyen, araç onay istemlerini gösteren ve /todos, /mode ve /exit gibi komutlar sunan örnek terminal uygulamaları içerir.

Önemli

Bu konsol projeleri, gönderilen çerçeve bileşenleri değil örneklerdir. Bunları çalıştırılabilir örnekler olarak veya kendi terminal deneyiminiz için başlangıç noktası olarak kullanın.

.NET örnek giriş noktası:HarnessConsole.RunAgentAsync

using Harness.Shared.Console;

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

Gözlemciler, araç biçimlendiricileri, komut işleyicileri ve HarnessConsoleOptionsile örneği özelleştirin. .NET Harness örneklerine bakın.

Python örneği, Harness örneklerinin yanında Textual tabanlı console paketini kullanır:

from console import run_agent_async

await run_agent_async(agent)

Gözlemciler, biçimlendiriciler, komutlar ve kullanıcı arabirimi bileşenleriyle örneği özelleştirin. Bkz. Python Harness örnekleri.

Depo şu anda paketlenmiş Go Harness terminal örneği içermiyor.

Sonraki Adımlar

İş planlama ve yapılacakları izleme

Daha derine git

  • Last updated on