Çalışma Zamanı Bağlamı

Çalışma zamanı bağlamı, ara yazılıma geçerli yürütme ortamı ve istek hakkındaki bilgilere erişim sağlar. Bu, oturum başına yapılandırma, kullanıcıya özgü davranış ve çalışma zamanı koşullarına göre dinamik ara yazılım davranışı gibi desenleri etkinleştirir.

C# dilinde çalışma zamanı bağlamı üç ana yüzeyden akar:

  • AgentRunOptions.AdditionalProperties ara yazılımların ve araçların okuyabileceği çalıştırma başına anahtar-değer meta verileri için.
  • FunctionInvocationContext işlevi çağırma ara yazılımı içinde araç çağrısı bağımsız değişkenlerini incelemek ve değiştirmek için.
  • AgentSession.StateBag bir konuşma içindeki çalıştırmalar arasında kalıcı olan paylaşılan durum için.

Uygun en dar yüzeyi kullanın. Çalıştırma başına meta veriler öğesine AdditionalPropertiesaittir, kalıcı konuşma durumu oturumun StateBagöğesine aittir ve araç bağımsız değişken işlemesi işlev çağırma ara yazılımına aittir.

Tip

Ara yazılım kapsamının çalışma zamanı bağlamı erişimini nasıl etkilediği hakkında bilgi için Aracı ve Çalıştırma Kapsamı sayfasına bakın.

Doğru çalışma zamanı yüzeyini seçin

Kullanım örneği API yüzeyi Erişilen yer:
Çalıştırmalar arasında konuşma durumunu veya verileri paylaşma AgentSession.StateBag session.StateBag ara yazılımı çalıştırmada, AIAgent.CurrentRunContext?.Session araçlarda
Ara yazılıma veya araçlara çalıştırma başına meta verileri geçirme AgentRunOptions.AdditionalProperties options.AdditionalProperties ara yazılımı çalıştırmada, AIAgent.CurrentRunContext?.RunOptions araçlarda
Ara yazılımda araç çağrısı bağımsız değişkenlerini inceleme veya değiştirme FunctionInvocationContext İşlev çağırma ara yazılımı geri çağırma

Çalıştırma başına değerleri şu şekilde geçirme: AgentRunOptions

Çalıştırma başına anahtar-değer verileri eklemek için açık AgentRunOptions seçeneğini kullanınAdditionalProperties. İşlev çağırma ara yazılımı bu değerleri araç bağımsız değişkenlerine iletebilir.

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Threading;
using System.Threading.Tasks;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

[Description("Send an email to the specified address.")]
static string SendEmail(
    [Description("Recipient email address.")] string address,
    [Description("User ID of the sender.")] string userId,
    [Description("Tenant name.")] string tenant = "default")
{
    return $"Queued email for {address} from {userId} ({tenant})";
}

// Function invocation middleware that injects per-run values into tool arguments
async ValueTask<object?> InjectRunContext(
    AIAgent agent,
    FunctionInvocationContext context,
    Func<FunctionInvocationContext, CancellationToken, ValueTask<object?>> next,
    CancellationToken cancellationToken)
{
    var runOptions = AIAgent.CurrentRunContext?.RunOptions;
    if (runOptions?.AdditionalProperties is { } props)
    {
        if (props.TryGetValue("user_id", out var userId))
        {
            context.Arguments["userId"] = userId;
        }

        if (props.TryGetValue("tenant", out var tenant))
        {
            context.Arguments["tenant"] = tenant;
        }
    }

    return await next(context, cancellationToken);
}

AIAgent baseAgent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
        .AsAIAgent(
            model: "gpt-4o-mini",
            instructions: "Send email updates.",
            tools: [AIFunctionFactory.Create(SendEmail)]);

var agent = baseAgent
    .AsBuilder()
        .Use(InjectRunContext)
    .Build();

var response = await agent.RunAsync(
    "Email the launch update to finance@example.com",
    options: new AgentRunOptions
    {
        AdditionalProperties = new AdditionalPropertiesDictionary
        {
            ["user_id"] = "user-123",
            ["tenant"] = "contoso",
        }
    });

Console.WriteLine(response);

Uyarı

DefaultAzureCredential geliştirme için uygundur ancak üretimde dikkatli bir şekilde dikkate alınması gerekir. Üretimde gecikme sorunları, istenmeyen kimlik bilgisi yoklama ve geri dönüş mekanizmalarından kaynaklanan olası güvenlik risklerini önlemek için belirli bir kimlik bilgisi (ör ManagedIdentityCredential. ) kullanmayı göz önünde bulundurun.

Ara yazılım, ortam AIAgent.CurrentRunContext aracılığıyla çalıştırma başına değerleri AgentRunOptions.AdditionalProperties okur ve araç yürütülmeden önce bunları aracın FunctionInvocationContext.Arguments içine ekler.

İşlev çağırma ara yazılımı bağlamı alır

İşlev çağırma ara yazılımı, araç bağımsız değişkenlerini incelemek veya değiştirmek, sonuçları kesmek veya araç yürütmeyi tamamen atlamak için kullanır FunctionInvocationContext .

using System;
using System.Threading;
using System.Threading.Tasks;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

async ValueTask<object?> EnrichToolContext(
    AIAgent agent,
    FunctionInvocationContext context,
    Func<FunctionInvocationContext, CancellationToken, ValueTask<object?>> next,
    CancellationToken cancellationToken)
{
    if (!context.Arguments.ContainsKey("tenant"))
    {
        context.Arguments["tenant"] = "contoso";
    }

    if (!context.Arguments.ContainsKey("requestSource"))
    {
        context.Arguments["requestSource"] = "middleware";
    }

    return await next(context, cancellationToken);
}

AIAgent baseAgent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
        .AsAIAgent(
            model: "gpt-4o-mini",
            instructions: "Send email updates.",
            tools: [AIFunctionFactory.Create(SendEmail)]);

var agent = baseAgent
    .AsBuilder()
        .Use(EnrichToolContext)
    .Build();

Ara yazılım işlev çağırma bağlamını alır ve işlem hattına devam etmek için çağırır next . context.Arguments çağrısından nextönce sesi kapatın; araç güncelleştirilmiş değerleri görür.

Paylaşılan çalışma zamanı durumu için kullanma AgentSession.StateBag

using System;
using System.ComponentModel;
using System.Threading;
using System.Threading.Tasks;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

[Description("Store the specified topic in session state.")]
static string RememberTopic(
    [Description("Topic to remember.")] string topic)
{
    var session = AIAgent.CurrentRunContext?.Session;
    if (session is null)
    {
        return "No session available.";
    }

    session.StateBag.SetValue("topic", topic);
    return $"Stored '{topic}' in session state.";
}

AIAgent agent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
        .AsAIAgent(
            model: "gpt-4o-mini",
            instructions: "Remember important topics.",
            tools: [AIFunctionFactory.Create(RememberTopic)]);

var session = await agent.CreateSessionAsync();
await agent.RunAsync("Remember that the budget review is on Friday.", session: session);
Console.WriteLine(session.StateBag.GetValue<string>("topic"));

oturumu ile session: açıkça geçirin ve aracılığıyla AIAgent.CurrentRunContext?.Sessionaraçlardan erişin. , StateBag aynı oturumdaki çalıştırmalar arasında kalıcı olan tür açısından güvenli, iş parçacığı güvenli depolama alanı sağlar.

Ara yazılım ve araçlar arasında oturum durumunu paylaşma

Ara yazılımı çalıştır, oturumun StateBagöğesini okuyup yazabilir ve tüm değişiklikler aynı istekte yürütülen işlev çağırma ara yazılımı ve araçları tarafından görülebilir.

using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

// Run middleware that stamps the session with request metadata
async Task<AgentResponse> StampRequestMetadata(
    IEnumerable<ChatMessage> messages,
    AgentSession? session,
    AgentRunOptions? options,
    AIAgent innerAgent,
    CancellationToken cancellationToken)
{
    if (session is not null && options?.AdditionalProperties is { } props)
    {
        if (props.TryGetValue("request_id", out var requestId))
        {
            session.StateBag.SetValue("requestId", requestId?.ToString());
        }
    }

    return await innerAgent.RunAsync(messages, session, options, cancellationToken);
}

AIAgent baseAgent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
        .AsAIAgent(
            model: "gpt-4o-mini",
            instructions: "You are a helpful assistant.");

var agent = baseAgent
    .AsBuilder()
        .Use(runFunc: StampRequestMetadata, runStreamingFunc: null)
    .Build();

var session = await agent.CreateSessionAsync();
await agent.RunAsync(
    "Hello!",
    session: session,
    options: new AgentRunOptions
    {
        AdditionalProperties = new AdditionalPropertiesDictionary
        {
            ["request_id"] = "req-abc-123",
        }
    });

Console.WriteLine(session.StateBag.GetValue<string>("requestId"));

Ara yazılımı çalıştır, oturumu doğrudan parametre olarak alır. Tür güvenli erişim için ve GetValue kullanınStateBag.SetValue. Çalıştırma ara yazılımı aşamasında depolanan tüm değerler aracılığıyla AIAgent.CurrentRunContext?.Sessionaraçlar ve işlev çağırma ara yazılımı tarafından kullanılabilir.

Python çalışma zamanı bağlamı üç genel yüzeye ayrılır:

  • session= konuşma durumu ve geçmişi için.
  • function_invocation_kwargs= yalnızca araçların veya işlev ara yazılımının görmesi gereken değerler için.
  • client_kwargs= sohbet istemciye özgü veriler veya istemci ara yazılım yapılandırması için.

Verilere uyan en küçük yüzeyi kullanın. Bu, araç girişlerini açık tutar ve araç yürütmeye yalnızca istemci meta verilerinin sızmasını önler.

Tip

veya'a function_invocation_kwargsrastgele genel **kwargs geçirmenin eski deseninin yerine olarak agent.run() davranınget_response().

Doğru çalışma zamanı demetini seçin

Kullanım örneği API yüzeyi Erişilen yer:
Konuşma durumunu, hizmet oturumu kimliklerini veya geçmişi paylaşma session= ctx.session, AgentContext.session
Çalışma zamanı değerlerini yalnızca araçlar veya işlev ara yazılımı gereksinimini geçirme function_invocation_kwargs= FunctionInvocationContext.kwargs
İstemciye özgü çalışma zamanı değerlerini veya istemci ara yazılım yapılandırmasını geçirme client_kwargs= özel get_response(..., client_kwargs=...) uygulamalar

Yalnızca araç çalışma zamanı değerlerini geçirme

from typing import Annotated

from agent_framework import FunctionInvocationContext, tool
from agent_framework.openai import OpenAIChatClient


@tool(approval_mode="never_require")
def send_email(
    address: Annotated[str, "Recipient email address."],
    ctx: FunctionInvocationContext,
) -> str:
    user_id = ctx.kwargs["user_id"]
    tenant = ctx.kwargs.get("tenant", "default")
    return f"Queued email for {address} from {user_id} ({tenant})"


agent = OpenAIChatClient().as_agent(
    name="Notifier",
    instructions="Send email updates.",
    tools=[send_email],
)

response = await agent.run(
    "Email the launch update to finance@example.com",
    function_invocation_kwargs={
        "user_id": "user-123",
        "tenant": "contoso",
    },
)

print(response.text)

Çağırılabilir araç üzerinde battaniye ctx.kwargs bildirmek yerine aracın içinde kullanın**kwargs. Eski **kwargs araçlar uyumluluk için çalışmaya devam eder, ancak GA'dan önce kaldırılır.

olarak FunctionInvocationContext ek açıklama eklenmiş herhangi bir parametre, adından bağımsız olarak eklenen çalışma zamanı bağlam parametresi olarak kabul edilir ve modele gösterilen JSON şemasında gösterilmez. Açık bir şema/giriş modeli sağlarsanız, adlı ctx düz eklenmemiş bir parametre de eklenen bağlam parametresi olarak kabul edilir.

Değer, çağırma verileri yerine uzun ömürlü araç durumu veya bağımlılıksa, bunu aracılığıyla function_invocation_kwargsgeçirmek yerine bir araç sınıfı örneğinde tutun. Bu düzen için bkz. Birden çok işlev aracıyla sınıf oluşturma.

İşlev ara yazılımı aynı bağlamı alır

İşlev ara yazılımı, araçların aldığı nesnenin aynısını FunctionInvocationContext kullanır. Bu, ara yazılımların , , context.argumentscontext.kwargsve context.session'yi inceleyebileceği context.resultanlamına gelir.

from collections.abc import Awaitable, Callable

from agent_framework import FunctionInvocationContext
from agent_framework.openai import OpenAIChatClient


async def enrich_tool_runtime_context(
    context: FunctionInvocationContext,
    call_next: Callable[[], Awaitable[None]],
) -> None:
    context.kwargs.setdefault("tenant", "contoso")
    context.kwargs.setdefault("request_source", "middleware")
    await call_next()


agent = OpenAIChatClient().as_agent(
    name="Notifier",
    instructions="Send email updates.",
    tools=[send_email],
    middleware=[enrich_tool_runtime_context],
)

Ara yazılım sözleşmesi bağımsız değişken olmadan kullanır call_next() . context.kwargs Çağırmadan önce sesi kapatın ve seçili araç eklenen aracılığıyla FunctionInvocationContextbu değerleri görür.

Paylaşılan çalışma zamanı durumu için kullanma session=

from typing import Annotated

from agent_framework import FunctionInvocationContext, tool
from agent_framework.openai import OpenAIChatClient


@tool(approval_mode="never_require")
def remember_topic(
    topic: Annotated[str, "Topic to remember."],
    ctx: FunctionInvocationContext,
) -> str:
    if ctx.session is None:
        return "No session available."

    ctx.session.state["topic"] = topic
    return f"Stored {topic!r} in session state."


agent = OpenAIChatClient().as_agent(
    name="MemoryAgent",
    instructions="Remember important topics.",
    tools=[remember_topic],
)

session = agent.create_session()
await agent.run("Remember that the budget review is on Friday.", session=session)
print(session.state["topic"])

Oturumu ile session= açıkça geçirin ve uygulamasından ctx.sessionokuyun. Oturum erişiminin artık çalışma zamanı kwargs üzerinden geçmesi gerekmez.

Oturum durumunu temsilci aracılarıyla paylaşma

Aracı aracılığıyla as_tool()bir araç olarak kullanıma sunulduğunda, çalışma zamanı işlevi kwargs zaten üzerinden ctx.kwargsakıyor. Yalnızca alt aracının çağıranın propagate_session=Trueöğesini paylaşması gerektiğinde ekleyinAgentSession.

from agent_framework import FunctionInvocationContext, tool
from agent_framework.openai import OpenAIChatClient


@tool(description="Store findings for later steps.")
def store_findings(findings: str, ctx: FunctionInvocationContext) -> None:
    if ctx.session is not None:
        ctx.session.state["findings"] = findings


client = OpenAIChatClient()

research_agent = client.as_agent(
    name="ResearchAgent",
    instructions="Research the topic and store findings.",
    tools=[store_findings],
)

research_tool = research_agent.as_tool(
    name="research",
    description="Research a topic and store findings.",
    arg_name="query",
    propagate_session=True,
)

ile propagate_session=True, temsilci temsilcisi arayanla aynı ctx.session durumu görür. Alt aracıyı kendi oturumunda yalıtmak için bırakın False .

Özel sohbet istemcileri ve aracıları

Özel genel run() veya get_response() yöntemler uygularsanız, imzaya açık çalışma zamanı demetlerini ekleyin.

from collections.abc import Mapping, Sequence
from typing import Any

from agent_framework import ChatOptions, Message


async def get_response(
    self,
    messages: Sequence[Message],
    *,
    options: ChatOptions[Any] | None = None,
    function_invocation_kwargs: Mapping[str, Any] | None = None,
    client_kwargs: Mapping[str, Any] | None = None,
    **kwargs: Any,
):
    ...

Araç çağırma akışları ve function_invocation_kwargs istemciye özgü davranışlar için kullanınclient_kwargs. İstemciye özgü değerleri doğrudan genel **kwargs olarak geçirmek yalnızca bir uyumluluk yoludur ve kullanım dışı olarak kabul edilmelidir. Benzer şekilde, ile **kwargs yeni araçlar tanımlamak yalnızca geçiş uyumluluğudur; bunun yerine eklenen bağlam nesnesi aracılığıyla çalışma zamanı verilerini kullanır.

Sonraki Adımlar

Sağlayıcıları

  • Last updated on