Membangun dengan agen, percakapan, dan respons

Microsoft Foundry Agent Service menggunakan tiga komponen runtime inti—agents, konversi, dan responses—untuk mendukung interaksi multi-giliran yang stateful. Agen menggunakan model dari katalog model Foundry, bersama dengan instruksi dan alat. Jejak percakapan dipertahankan dari satu giliran ke giliran berikutnya. Respons adalah output yang dihasilkan agen saat memproses input.

Pilih komponen berdasarkan perilaku dan sebutkan kebutuhan aplikasi Anda:

Komponen Relationship Gunakan saat
Agen Menyediakan model, instruksi, dan alat yang dapat digunakan kembali untuk respons. Beberapa permintaan memerlukan perilaku atau konfigurasi alat yang sama.
Percakapan Menyediakan item input dan output yang dipertahankan untuk respons. Kemudian giliran membutuhkan riwayat sisi server.
Jawaban Menjalankan model atau agen terhadap input dan menghasilkan item output. Setiap interaksi membutuhkan satu unit eksekusi, dengan atau tanpa agen atau percakapan.

Mulailah dengan respons untuk satu interaksi. Tambahkan agen untuk perilaku yang dapat digunakan kembali, percakapan untuk riwayat yang tersimpan, atau keduanya. Untuk detail implementasi, langsung buka membuat agen, menghasilkan respons, atau menggunakan percakapan dan item percakapan.

Komponen bekerja sama dalam siklus hidup yang dapat diprediksi. Misalnya, pertimbangkan asisten dukungan yang menjawab pertanyaan tindak lanjut:

  1. Aplikasi memilih agen yang menentukan instruksi dan alat dukungan.
  2. Ini membuat percakapan dan menambahkan pertanyaan pertama pelanggan sebagai item input.
  3. Sebuah respons menjalankan agen pada percakapan dan menambahkan item output.
  4. Respons berikutnya menggunakan percakapan yang sama, sehingga agen dapat menjawab pertanyaan tindak lanjut dalam konteks.

Tanpa percakapan, aplikasi dapat meneruskan konteks dengan merujuk respons tersimpan sebelumnya atau dengan mengirim ulang item sebelumnya. Mode streaming dan latar belakang mengubah cara aplikasi menerima respons, bukan hubungan antara agen, percakapan, dan respons.

Diagram berikut mengilustrasikan bagaimana komponen-komponen ini berinteraksi dalam perulangan agen biasa.

Diagram yang memperlihatkan agen dan percakapan yang memberikan input ke respons, yang memanggil alat dan mengembalikan output untuk giliran berikutnya.

Anda memberikan input pengguna (dan riwayat percakapan opsional), layanan menghasilkan respons (termasuk panggilan alat saat dikonfigurasi), dan item yang dihasilkan dapat digunakan kembali sebagai konteks untuk giliran berikutnya.

Jika Anda menggunakan agen pengkodian seperti GitHub Copilot untuk merancang cara agen, percakapan, dan respons bekerja sama, keterampilan foundry Microsoft dapat membantu menerapkan komponen ini ke alur kerja aplikasi Anda.

Prasyarat

Untuk menjalankan sampel dalam artikel ini, Anda memerlukan:

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

Membuat agen

Agen adalah definisi orkestrasi yang bertahan yang menggabungkan model AI, instruksi, kode, alat, parameter, dan kontrol keamanan atau tata kelola opsional.

Simpan agen sebagai aset yang diberi nama dan memiliki versi di Microsoft Foundry. Selama pembuatan respons, definisi agen bekerja dengan riwayat interaksi (percakapan atau respons sebelumnya) untuk memproses dan merespons input pengguna.

Contoh berikut membuat agen perintah dengan nama, model, dan instruksi. Gunakan klien proyek untuk pembuatan dan penerapan versi agen.

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

Catatan

Agen sekarang diidentifikasi menggunakan nama agen dan versi agen. Mereka tidak memiliki GUID yang dipanggil AgentID lagi.

Untuk jenis agen tambahan (dihosting), lihat Siklus hidup pengembangan agen.

Membuat agen dengan alat

Alat memperluas apa yang dapat dilakukan agen selain menghasilkan teks. Saat Anda melampirkan alat ke agen, agen dapat memanggil layanan eksternal, menjalankan kode, file pencarian, dan mengakses sumber data selama pembuatan respons—menggunakan alat seperti pencarian web atau panggilan fungsi.

Anda dapat melampirkan satu atau beberapa alat saat membuat agen. Selama pembuatan respons, agen memutuskan apakah akan memanggil alat berdasarkan input pengguna dan instruksinya. Contoh berikut membuat agen dengan alat pencarian web terlampir.

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

Untuk daftar lengkap alat yang tersedia dan cara menambahkannya ke Kotak Alat, lihat Gambaran umum Kotak Alat. Untuk praktik terbaik, lihat Praktik terbaik untuk menggunakan alat.

Hasilkan respons

Pembuatan respons mengaktifkan agen. Agen menggunakan konfigurasinya dan riwayat yang disediakan (percakapan atau respons sebelumnya) untuk melakukan tugas dengan memanggil model dan alat. Sebagai bagian dari pembuatan respons, agen menambahkan item ke percakapan.

Anda juga dapat menghasilkan respons tanpa menentukan agen. Dalam hal ini, Anda menyediakan semua konfigurasi langsung dalam permintaan dan menggunakannya hanya untuk respons tersebut. Pendekatan ini berguna untuk skenario sederhana dengan alat minimal.

Selain itu, Anda dapat menggandakan percakapan pada ID respons pertama atau ID respons kedua.

Membuat respons dengan agen

Contoh berikut menghasilkan respons menggunakan referensi agen, lalu mengirim pertanyaan tindak lanjut menggunakan respons sebelumnya sebagai konteks.

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)

Saat agen menggunakan alat selama pembuatan respons, output respons berisi item panggilan alat bersama pesan akhir. Anda dapat melakukan iterasi response.output untuk memeriksa setiap item dan menampilkan panggilan alat—seperti pencarian web, panggilan fungsi, atau pencarian file—sebelum mencetak respons teks.

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

Membuat respons tanpa menyimpan

Secara default, layanan menyimpan riwayat respons sisi server, sehingga Anda dapat referensi previous_response_id untuk konteks berganda. Jika Anda mengatur store ke false, layanan tidak mempertahankan respons. Anda harus meneruskan konteks percakapan sendiri dengan meneruskan item output sebelumnya sebagai input ke permintaan berikutnya.

Pendekatan ini berguna ketika Anda memerlukan kontrol penuh atas status percakapan, ingin meminimalkan data yang disimpan, atau bekerja di lingkungan retensi data nol.

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)

Percakapan dan elemen percakapan

Percakapan adalah objek yang bertahan lama dengan pengidentifikasi yang unik. Setelah pembuatan, Anda dapat menggunakannya kembali di seluruh sesi.

Percakapan menyimpan item, yang dapat mencakup pesan, panggilan alat, output alat, dan data lainnya.

Membuat percakapan

Contoh berikut membuat percakapan dengan pesan pengguna awal. Gunakan klien OpenAI (diperoleh dari klien proyek) untuk percakapan dan respons.

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

Kapan harus menggunakan percakapan

Gunakan percakapan saat Anda ingin:

  • Kelangsungan multi-giliran: Pertahankan riwayat yang stabil di seluruh belokan tanpa membangun kembali konteks sendiri.
  • Kelangsungan lintas sesi: Gunakan kembali percakapan yang sama untuk pengguna yang kembali nanti.
  • Penelusuran bug yang lebih mudah: Telaah kejadian yang terjadi sepanjang waktu (misalnya, panggilan alat dan hasil keluaran).

Saat percakapan digunakan untuk menghasilkan respons (dengan atau tanpa agen), percakapan lengkap disediakan sebagai input ke model. Respons yang dihasilkan kemudian ditambahkan ke percakapan yang sama.

Catatan

Jika percakapan melebihi ukuran konteks model yang didukung, model akan secara otomatis memotong konteks input. Percakapan itu sendiri tidak terpotong, tetapi hanya bagian terpilih dari percakapan yang digunakan untuk menghasilkan respons.

Jika Anda tidak membuat percakapan, Anda masih dapat membangun alur multi-giliran dengan menggunakan output dari respons sebelumnya sebagai titik awal untuk permintaan berikutnya. Pendekatan ini memberi Anda lebih banyak fleksibilitas daripada pola berbasis utas yang lebih lama, di mana status digabungkan erat ke objek utas. Untuk panduan migrasi, lihat Beralih ke SDK Agen.

Tipe elemen obrolan

Percakapan menyimpan item daripada hanya pesan obrolan. Item menangkap apa yang terjadi selama pembuatan respons sehingga giliran berikutnya dapat menggunakan kembali konteks tersebut.

Jenis item umum meliputi:

  • Item pesan: Pesan pengguna atau asisten.
  • Item panggilan alat: Catatan pemanggilan alat yang dicoba agen.
  • Item keluaran alat: Keluaran yang dikembalikan oleh alat (misalnya, hasil pengambilan).
  • Item output: Konten respons yang Anda tampilkan kembali ke pengguna.

Menambahkan item ke percakapan

Setelah Anda membuat percakapan, gunakan conversations.items.create() untuk menambahkan pesan pengguna berikutnya atau item lainnya.

# 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?",
        }
    ],
)

Menggunakan percakapan dengan agen

Gabungkan percakapan dengan referensi agen untuk mempertahankan riwayat di beberapa belokan. Agen memproses semua item dalam percakapan dan menambahkan outputnya secara otomatis.

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)

Untuk contoh yang memperlihatkan bagaimana percakapan dan respons bekerja sama dalam kode, lihat Membuat dan menggunakan memori di Foundry Agent Service.

Respons streaming dan latar belakang

Untuk operasi jangka panjang, Anda dapat mengembalikan hasil secara bertahap menggunakan streaming atau berjalan sepenuhnya secara asinkron menggunakan background mode. Dalam kasus ini, Anda biasanya memantau respons hingga selesai dan kemudian menggunakan item output akhir.

Melakukan streaming respons

Streaming mengembalikan hasil secara parsial seiring dengan proses pembuatannya. Pendekatan ini berguna untuk menampilkan output kepada pengguna secara real time.

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)

Untuk detail tentang mode respons dan cara menggunakan output, lihat API Respons.

Menjalankan agen dalam mode latar belakang

Mode latar belakang menjalankan agen secara asinkron, yang berguna untuk tugas jangka panjang seperti penalaran kompleks atau pembuatan gambar. Atur background ke true lalu periksa status respons sampai selesai.

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)

Melampirkan memori ke agen (pratinjau)

Memori memberi agen kemampuan untuk menyimpan informasi di seluruh sesi, sehingga mereka dapat mempersonalisasi respons dan memanggil kembali preferensi pengguna dari waktu ke waktu. Tanpa memori, setiap percakapan dimulai dari awal.

Foundry Agent Service menyediakan solusi memori terkelola versi pratinjau yang Anda konfigurasi melalui penyimpanan memori. Penyimpanan memori menentukan jenis informasi mana yang harus dipertahankan agen. Lampirkan penyimpanan memori ke agen Anda, dan agen menggunakan memori tersimpan sebagai konteks tambahan selama pembuatan respons.

Contoh berikut membuat penyimpanan memori dan mengaitkannya dengan agen.

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

Untuk detail konseptual, lihat Memori di Foundry Agent Service. Untuk panduan implementasi lengkap, lihat Membuat dan menggunakan memori.

Penanganan keamanan dan data

Karena percakapan dan respons dapat mempertahankan konten dan output alat yang disediakan pengguna, perlakukan data runtime seperti data aplikasi:

  • Hindari menyimpan rahasia dalam perintah atau riwayat percakapan. Gunakan koneksi dan penyimpanan rahasia terkelola sebagai gantinya (misalnya, Siapkan koneksi Key Vault).
  • Gunakan hak istimewa paling sedikit untuk akses alat. Ketika alat mengakses sistem eksternal, agen berpotensi membaca atau mengirim data melalui alat tersebut.
  • Hati-hati dengan layanan yang bukan dari Microsoft. Jika agen Anda memanggil alat yang didukung oleh non-layanan Microsoft, beberapa data mungkin mengalir ke layanan tersebut. Untuk pertimbangan terkait, lihat Ikhtisar Toolbox.

Batasan dan kendala

Batasan dapat bergantung pada model, wilayah, dan alat yang Anda lampirkan (misalnya, ketersediaan streaming dan dukungan alat). Untuk ketersediaan dan batasan saat ini untuk respons, lihat API Respons.

Konten terkait

  • Last updated on