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.

Sonuçta elde edilen nesne normal bir Agent Framework aracısı olarak kalır: .NET'te AIAgent'den türetilen bir HarnessAgent, Python'da create_harness_agent tarafından döndürülen bir Agent veya Go'da *agent.Agent ile yapılandırılmış, sağlayıcı destekli bir harness.AgentConfig. 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. Go sağlayıcı oluşturucuları, araç çağırma döngüsünü yönetir. İş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 .NET ve Python belirteç sınırları veya özel strateji sağlandığında etkinleştirilir. Go, açık sağlayıcı bileşimi gerektirir. 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 ve Go'da 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ı .NET ve Python'da adlandırılmış alt aracılara isteğe bağlı paralel delege etme. Paketlenmiş Go arka plan aracısı sağlayıcısı yok. 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.

Tip

Bir Python harness uygulaması oluşturmaya yardımcı olan coding-agent kılavuzu için agent-framework-builder-python öğesini yükleyin. Bu harici coding-agent becerisi, matriste listelenen çalışma zamanı Aracı Becerileri özelliğinden ayrıdı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.

Bir aracının birden çok dosya erişim sağlayıcısı olduğunda tool_name_prefix kullanın. Ön ek, workspace_file_access_read gibi adlar üretir ve araç adı çakışmalarını önler. Ön ekli sağlayıcılar için, her kuralın sağlayıcının oluşturduğu adlarla eşleşmesi amacıyla sağlayıcıya özgü onay kuralı fabrikalarını kullanın:

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() hem okuma hem de yazma araçları için eşdeğer kuralı oluşturur. Depolama sınırına ve araç girişlerine güvenilmediği sürece yazma onayını etkin tutun.

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.

Go agent/harness paketi, normal bir sağlayıcı destekli aracı için ara yazılımı, bağlam sağlayıcılarını ve geçmiş varsayılanlarını bir araya getirmektedir. harness.AgentConfig(harness.Config{}, agent.Config{...}) çağırın, hatasını işleyin ve döndürülen yapılandırmayı sağlayıcı oluşturucusuna geçirin. Ayrı bir aracı türü veya araç yürütme döngüsü sunmaz.

Bir harness ajanı oluşturun

Bileşik örnek, Foundry destekli bir koşum aracısını yapılandırıyor:

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.",
        },
    )

Bileşimi özelleştirin

Yardımcı aşağıdaki varsayılanları etkinleştirir:

Bileşen Varsayılan Go harnessı
Planning Plan modundan başlayarak oturum destekli yapılacaklar araçları ve plan/yürütme modları
Dosya hafızası agent-file-memory altındaki, oturum başına yalıtılmış çalışma klasörüne sahip kalıcı dosyalar
Yetenekler Bellek alt ağacı hariç, çalışma dizininden dosya destekli bulma
Web araması çağıran önceden sağlamadıysa barındırılan web araması bildirimi
Approval Onay gerektiren araçlar için sürekli onay ve otomatik onay ara yazılımı
History Hizmet başına çağrı kalıcılığı ile bellek içi geçmiş
İleti enjeksiyonu Ajan başına agent.MessageInjector
İz sürme Aracı, araç ve desteklenen model çağrısı araçsallaştırması

Bileşenleri devre dışı bırakmak veya yapılandırmalarını geçersiz kılmak için kullanın harness.Config . Seçili hizmet veya dağıtım bunu desteklemediğinde barındırılan web arama özelliğini devre dışı bırakın. Dosya destekli skill betikleri açıkça yapılandırılmış bir betik çalıştırıcısı gerektirir.

Yardımcı, çağıranın araçlarını, ara yazılımı, bağlam sağlayıcılarını ve açıkça yapılandırılan bir geçmiş sağlayıcısını korur. Foundry model deployment'ta, yerel geçmiş konuşmanın sahibi olduğunda DisableStoreOutput: true kullanın.

Sıkıştırma, döngü ve kabuk araçları Go yardımcısı tarafından eklenmez. Gerektiğinde bunları açıkça yapılandırın. Diğer SDK'larda açıklanan paketlenmiş arka plan aracısı yetkilendirme sağlayıcısı Go'da kullanılamaz.

Kurulum için Go koşum aracısı oluşturma ve varsayılanlar ve geçersiz kılmalar için Go koşum yapılandırma kılavuzuna bakın.

Ö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.

Go reposu, onay işlemeye sahip bileşik bir test düzeneği örneği ve ayrı bir etkileşimli sohbet CLI demosu içerir. Sohbet CLI'sı düz bir agent kullanır; C# veya Python Harness konsoluna eşdeğer değildir.

Sonraki Adımlar

İş planlama ve yapılacakları izleme

Daha derine git

  • Son güncelleştirme: