Aracılar, konuşmalar ve yanıtlarla inşa et

Microsoft Foundry Agent Service, durum bilgisi olan, çok yönlü etkileşimleri desteklemek için üç çekirdek çalışma zamanı bileşeni kullanır: agents, conversations ve responses. Aracı, Dökümhane modeli kataloğundaki bir modeli, yönergeler ve araçlarla birlikte kullanır. Konuşmalar sırayla geçmişi kalıcı hale alır. Yanıt, aracı girişi işlerken ürettiği çıkıştır.

Uygulamanıza gereken davranışa ve duruma göre bileşenleri seçin:

Bileşen Ilişki Şu durumlarda kullanın:
Aracı Yanıta yeniden kullanılabilir model, yönergeler ve araçlar sağlar. Birden çok istek aynı davranışa veya araç yapılandırmasına ihtiyaç duyar.
Konuşma Yanıtlara kalıcı giriş ve çıkış öğeleri sağlar. Daha sonra sunucu tarafı geçmişi gerekir.
Yanıt Girişe karşı bir model veya aracı çalıştırır ve çıkış öğeleri üretir. Her etkileşimin bir aracı veya konuşma ile veya konuşma olmadan bir yürütme birimi olması gerekir.

Tek bir etkileşim için bir yanıtla başlayın. Yeniden kullanılabilir davranış için bir aracı, kalıcı geçmiş için bir konuşma veya her ikisini birden ekleyin. Uygulama ayrıntıları için doğrudan aracı oluşturmaya, yanıt oluşturmaya veya konuşmalar ve konuşma öğeleriyle çalışmaya gidin.

Bileşenler tahmin edilebilir bir yaşam döngüsünde birlikte çalışır. Örneğin, bir takip sorusuna yanıt veren bir destek yardımcısı düşünün:

  1. Uygulama, destek yönergelerini ve araçlarını tanımlayan bir aracı seçer.
  2. Bir konuşma oluşturur ve müşterinin ilk sorusunu giriş öğesi olarak ekler.
  3. Yanıt, aracıyı konuşmaya karşı çalıştırır ve çıkış öğelerini ekler.
  4. Sonraki yanıt aynı konuşmayı kullanır, böylece aracı bir takip sorusuna bağlam içinde yanıt verebilir.

Konuşma olmadan uygulama, bağlamı daha önce depolanan bir yanıta başvurarak veya önceki öğeleri yeniden göndererek ileri taşıyabilir. Akış ve arka plan modu, aracılar, konuşmalar ve yanıtlar arasındaki ilişkiyi değil uygulamanın yanıt alma şeklini değiştirir.

Aşağıdaki diyagramda bu bileşenlerin tipik bir aracı döngüsünde nasıl etkileşimde olduğu gösterilmektedir.

Bir yanıta giriş sağlayan, araçları çağıran ve sonraki dönüş için çıkış döndüren bir aracıyı ve konuşmayı gösteren diyagram.

Kullanıcı girişi (ve isteğe bağlı olarak konuşma geçmişi) sağlarsınız, hizmet bir yanıt oluşturur (yapılandırıldığında araç çağrıları dahil) ve sonuçta elde edilen öğeler bir sonraki dönüş için bağlam olarak yeniden kullanılabilir.

Önkoşullar

Bu makaledeki örnekleri çalıştırmak için şunlar gerekir:

pip install "azure-ai-projects>=2.0.0"
pip install azure-identity

Bir ajan oluştur

Aracı, yapay zeka modellerini, yönergeleri, kodu, araçları, parametreleri ve isteğe bağlı güvenlik veya idare denetimlerini birleştiren kalıcı bir düzenleme tanımıdır.

Yazılım ajanlarını Microsoft Foundry'de adlandırılmış, sürümlenmiş varlıklar olarak depolayın. Yanıt oluşturma sırasında aracı tanımı, kullanıcı girişini işlemek ve yanıtlamak için etkileşim geçmişiyle (konuşma veya önceki yanıt) çalışır.

Aşağıdaki örnek ad, model ve yönergeler içeren bir istem aracısı oluşturur. Aracın oluşturulması ve sürümlendirilmesi için proje istemcisini kullanın.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create project client to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

# Create a prompt agent
agent = project.agents.create_version(
    agent_name="my-agent",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="You are a helpful assistant.",
    ),
)
print(f"Agent: {agent.name}, Version: {agent.version}")

Not

Aracılar artık aracı adı ve aracı sürümü kullanılarak tanımlanır. Artık adlı AgentID bir GUID'leri yok.

Diğer aracı türleri (barındırılan) için bkz. Aracı geliştirme yaşam döngüsü.

Araçlarla bir ajan oluşturma

Araçlar, bir aracının metin oluşturmanın ötesinde yapabileceklerini genişletir. Aracıya araç eklediğinizde aracı, web araması veya işlev çağrısı gibi araçları kullanarak dış hizmetleri çağırabilir, kod çalıştırabilir, dosyaları arayabilir ve yanıt oluşturma sırasında veri kaynaklarına erişebilir.

Aracı oluştururken bir veya daha fazla araç ekleyebilirsiniz. Yanıt oluşturma sırasında temsilci, yönergelerine ve kullanıcı girişine göre bir aracın çağrılıp çağrılmayacağına karar verir. Aşağıdaki örnek, web arama aracının eklendiği bir aracı oluşturur.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, WebSearchTool

PROJECT_ENDPOINT = "your_project_endpoint"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

# Create an agent with a web search tool
agent = project.agents.create_version(
    agent_name="my-tool-agent",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="You are a helpful assistant that can search the web.",
        tools=[WebSearchTool()],
    ),
)
print(f"Agent: {agent.name}, Version: {agent.version}")

Kullanılabilir araçların tam listesi için araçlara genel bakış bölümüne bakın. En iyi yöntemler için bkz. Araçları kullanmaya yönelik en iyi yöntemler.

Yanıt oluşturma

Yanıt oluşturma aracısını çağırır. Aracı, modelleri ve araçları çağırarak görevleri gerçekleştirmek için yapılandırmasını ve sağlanan herhangi bir geçmişi (konuşma veya önceki yanıt) kullanır. Yanıt oluşturma işleminin bir parçası olarak aracı konuşmaya öğe ekler.

Ayrıca bir aracı tanımlamadan da yanıt oluşturabilirsiniz. Bu durumda, tüm yapılandırmaları doğrudan istekte sağlar ve bunları yalnızca bu yanıt için kullanırsınız. Bu yaklaşım, en az araç içeren basit senaryolar için kullanışlıdır.

Ayrıca, konuşmayı ilk yanıt kimliğinde veya ikinci yanıt kimliğinde dallandırabilirsiniz.

Bir ajanla yanıt oluştur.

Aşağıdaki örnek, aracı başvurusu kullanarak bir yanıt oluşturur ve ardından bağlam olarak önceki yanıtı kullanarak bir izleme sorusu gönderir.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Generate a response using the agent
response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the largest city in France?",
)
print(response.output_text)

# Ask a follow-up question using the previous response
follow_up = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    previous_response_id=response.id,
    input="What is the population of that city?",
)
print(follow_up.output_text)

Bir ajan yanıt oluşturma sırasında araçları kullandığında, yanıt çıktısı son iletinin yanı sıra araç çağrı öğelerini de içerir. Yineleme yaparak response.output üzerinde her öğeyi inceleyebilir ve metin yanıtını yazdırmadan önce web aramaları, işlev çağrıları veya dosya aramaları gibi araç çağrılarını görüntüleyebilirsiniz.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What happened in the news today?",
)

# Print each output item, including tool calls
for item in response.output:
    if item.type == "web_search_call":
        print(f"[Tool] Web search: status={item.status}")
    elif item.type == "function_call":
        print(f"[Tool] Function call: {item.name}({item.arguments})")
    elif item.type == "file_search_call":
        print(f"[Tool] File search: status={item.status}")
    elif item.type == "message":
        print(f"[Assistant] {item.content[0].text}")

Depolamadan yanıt oluşturma

Varsayılan olarak, hizmet yanıt geçmişini sunucu tarafında depolar, böylece çok adımlı etkileşim için başvurabilirsiniz previous_response_id. store öğesini false olarak ayarlarsanız hizmet yanıtı kaydetmez. Önceki çıkış öğelerini bir sonraki isteğe giriş olarak geçirerek konuşma bağlamını kendiniz iletmeniz gerekir.

Konuşma durumu üzerinde tam denetime ihtiyacınız olduğunda, depolanan verileri en aza indirmek istediğinizde veya sıfır veri saklama ortamında çalışırken bu yaklaşım kullanışlıdır.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Generate a response without storing
response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the largest city in France?",
    store=False,
)
print(response.output_text)

# Carry forward context client-side by passing previous output as input
follow_up = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input=[
        {"role": "user", "content": "What is the largest city in France?"},
        {"role": "assistant", "content": response.output_text},
        {"role": "user", "content": "What is the population of that city?"},
    ],
    store=False,
)
print(follow_up.output_text)

Konuşmalar ve konuşma öğeleri

Konuşmalar, benzersiz tanımlayıcılara sahip dayanıklı nesnelerdir. Oluşturma işleminden sonra bunları oturumlar arasında yeniden kullanabilirsiniz.

Konuşmalar, iletileri, araç çağrılarını, araç çıkışlarını ve diğer verileri içerebilen öğeleri depolar.

Konuşma oluşturma

Aşağıdaki örnek, ilk kullanıcı iletisiyle bir konuşma oluşturur. Konuşmalar ve yanıtlar için OpenAI istemcisini (proje istemcisinden alınan) kullanın.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Create a conversation with an initial user message
conversation = openai.conversations.create(
    items=[
        {
            "type": "message",
            "role": "user",
            "content": "What is the largest city in France?",
        }
    ],
)
print(f"Conversation ID: {conversation.id}")

Konuşma ne zaman kullanılmalı?

İstediğiniz zaman konuşma kullanın:

  • Çok dönüşlü süreklilik: Bağlamı kendiniz yeniden oluşturmadan sabit bir geçmişi muhafaza edin.
  • Oturumlar arası süreklilik: Daha sonra geri dönen bir kullanıcı için aynı konuşmayı yeniden kullanma.
  • Daha kolay hata ayıklama: Zaman içinde ne olduğunu inceleyin (örneğin, araç çağrıları ve çıkışlar).

Bir konuşma yanıt oluşturmak için kullanıldığında, aracı olsun ya da olmasın, tam konuşma modele giriş olarak sağlanır. Oluşturulan yanıt daha sonra aynı konuşmaya eklenir.

Not

Konuşma modelin desteklenen bağlam boyutunu aşarsa, model giriş bağlamını otomatik olarak kesecektir. Konuşmanın kendisi kesilmez, ancak yanıtı oluşturmak için yalnızca bir alt kümesi kullanılır.

Konuşma oluşturmazsanız, önceki bir yanıttan alınan çıkışı sonraki isteğin başlangıç noktası olarak kullanarak çok dönüşlü akışlar oluşturmaya devam edebilirsiniz. Bu yaklaşım, durumun iş parçacığı nesneleriyle sıkı bir şekilde birleştirildiği eski iş parçacığı tabanlı desenden daha fazla esneklik sağlar. Geçiş kılavuzu için bkz. Aracılar SDK'sına geçiş.

Konuşma öğesi türleri

Konuşmalar yalnızca sohbet iletileri yerine öğeleri depolar. Öğeler yanıt oluşturulurken ne olduğunu yakalar, böylece sonraki adım bu bağlamı yeniden kullanabilir.

Yaygın öğe türleri şunlardır:

  • İleti öğeleri: Kullanıcı veya yardımcı iletileri.
  • Araç çağrı öğeleri: Yazılım ajanının denemiş olduğu araç çağrılarının kayıtları.
  • Araç çıkış öğeleri: Araçlar tarafından döndürülen çıkışlar (örneğin, alma sonuçları).
  • Çıkış öğeleri: Kullanıcıya geri görüntülediğiniz yanıt içeriği.

Konuşmaya öğe ekleme

Bir konuşma oluşturduktan sonra, sonraki kullanıcı iletilerini veya diğer öğeleri eklemek için kullanın conversations.items.create() .

# Add a follow-up message to an existing conversation
openai.conversations.items.create(
    conversation_id=conversation.id,
    items=[
        {
            "type": "message",
            "role": "user",
            "content": "What about Germany?",
        }
    ],
)

Bir temsilciyle konuşmayı kullanın

Birden çok dönüşte geçmişi korumak için bir konuşmayı aracı başvurusuyla birleştirin. Aracı sohbet içerisindeki tüm öğeleri işler ve çıkışını otomatik olarak ekler.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Create a conversation for multi-turn chat
conversation = openai.conversations.create()

# First turn
response = openai.responses.create(
    conversation=conversation.id,
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the largest city in France?",
)
print(response.output_text)

# Follow-up turn in the same conversation
follow_up = openai.responses.create(
    conversation=conversation.id,
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the population of that city?",
)
print(follow_up.output_text)

Konuşmaların ve yanıtların kodda birlikte nasıl çalıştığını gösteren örnekler için bkz . Foundry Agent Service'te bellek oluşturma ve kullanma.

Akış ve arka plan yanıtları

Uzun süre çalışan işlemler için, streaming kullanarak sonuçları artımlı olarak döndürebilir veya tamamen asenkron background modunu kullanarak çalıştırabilirsiniz. Bu gibi durumlarda, genellikle bitene kadar yanıtı izler ve ardından son çıkış öğelerini tüketirsiniz.

Yanıt akışı

Yayın akışı, oluşturulduklarında kısmi sonuçları aktarır. Bu yaklaşım, kullanıcılara çıkışı gerçek zamanlı olarak göstermek için kullanışlıdır.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Stream a response using the agent
stream = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="Explain how agents work in one paragraph.",
    stream=True,
)
for event in stream:
    if hasattr(event, "delta") and event.delta:
        print(event.delta, end="", flush=True)

Yanıt modları ve çıkışları kullanma hakkında ayrıntılı bilgi için bkz. Yanıtlar API'si.

Aracıyı arka plan modunda çalıştırma

Arka plan modu aracıyı zaman uyumsuz olarak çalıştırır. Bu, karmaşık akıl yürütme veya görüntü oluşturma gibi uzun süre çalışan görevler için kullanışlıdır. background'ı true olarak ayarlayın ve yanıt durumunu tamamlanana kadar yoklayın.

from time import sleep
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Start a background response using the agent
response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="Write a detailed analysis of renewable energy trends.",
    background=True,
)

# Poll until the response completes
while response.status in ("queued", "in_progress"):
    sleep(2)
    response = openai.responses.retrieve(response.id)

print(response.output_text)

Ajan'a bellek ekleme (önizleme)

Bellek aracılara, yanıtları kişiselleştirmeleri ve zaman içindeki kullanıcı tercihlerini geri çekmeleri için oturumlar arasında bilgi tutma olanağı sağlar. Bellek olmadan her konuşma sıfırdan başlar.

Döküm Aracı Hizmeti, bellek depoları aracılığıyla yapılandırdığınız bir yönetilen bellek çözümü (önizleme) sağlar. Bellek deposu, aracının hangi tür bilgileri tutması gerektiğini tanımlar. Aracınıza bir bellek deposu ekleyin ve aracı, yanıt oluşturma sırasında ek bağlam olarak depolanan bellekleri kullanır.

Aşağıdaki örnek bir bellek deposu oluşturur ve bunu bir aracıya ekler.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    MemoryStoreDefaultDefinition,
    MemoryStoreDefaultOptions,
)

PROJECT_ENDPOINT = "your_project_endpoint"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

# Create a memory store
options = MemoryStoreDefaultOptions(
    chat_summary_enabled=True,
    user_profile_enabled=True,
)
definition = MemoryStoreDefaultDefinition(
    chat_model="gpt-5.2",
    embedding_model="text-embedding-3-small",
    options=options,
)
memory_store = project.beta.memory_stores.create(
    name="my_memory_store",
    definition=definition,
    description="Memory store for my agent",
)
print(f"Memory store: {memory_store.name}")

Kavramsal ayrıntılar için bkz . Döküm Aracı Hizmeti'nde Bellek. Tam uygulama kılavuzu için bkz. Bellek oluşturma ve kullanma.

Güvenlik ve veri işleme

Konuşmalar ve yanıtlar kullanıcı tarafından sağlanan içeriği ve araç çıkışlarını kalıcı hale geldiği için çalışma zamanı verilerini uygulama verileri gibi değerlendirin:

  • Gizli bilgileri istemlerde veya sohbet geçmişinde depolamaktan kaçının. Bunun yerine bağlantıları ve yönetilen gizli anahtar depolarını kullanın (örneğin, bir Key Vault bağlantısı kurma).
  • Araç erişimi için en az ayrıcalık kullanın. Bir araç dış sistemlere eriştiğinde, ajan bu araç aracılığıyla verileri okuyabilir veya gönderebilir.
  • Microsoft olmayan hizmetlere dikkat edin. Aracınız, Microsoft hizmetleri dışındaki servisler tarafından desteklenen araçları çağırırsa, bazı veriler bu hizmetlere akabilir. İlgili konular için bkz Döküm Araçları'ndaki Araçları Keşfetme.

Sınırlar ve kısıtlamalar

Sınırlar modele, bölgeye ve eklediğiniz araçlara (örneğin, akış kullanılabilirliği ve araç desteği) bağlı olabilir. Geçerli kullanılabilirlik ve yanıt kısıtlamaları için bkz. Yanıtlar API'si.

İlgili içerik

  • Last updated on