Mengembangkan agen dengan LangGraph dan Microsoft Foundry Agent Service (klasik)

Hanya berlaku untuk:Portal Foundry (klasik). Artikel ini tidak tersedia untuk portal Foundry baru. Pelajari selengkapnya tentang portal baru.

Catatan

Tautan dalam artikel ini mungkin membuka konten dalam dokumentasi Microsoft Foundry baru alih-alih dokumentasi Foundry (klasik) yang Anda lihat sekarang.

langchain-azure-ai Gunakan paket untuk menghubungkan aplikasi LangGraph dan LangChain ke Foundry Agent Service. Artikel ini membahas skenario praktis, mulai dari agen prompt dasar hingga alur kerja yang didukung alat.

Prasyarat

Langganan Azure. Buat satu secara gratis.
Proyek Foundry di Foundry classic.
Model obrolan yang telah diterapkan (misalnya, gpt-4.1) di proyek Anda.
Python 3.10 atau yang lebih baru.
Azure CLI masuk (az login) sehingga DefaultAzureCredential dapat mengautentikasi.

Mengonfigurasi lingkungan Anda

Instal paket yang digunakan dalam artikel ini:

pip install langchain-azure-ai[tools,v1] azure-ai-agents azure-identity pandas

Penting

Instal [v1] untuk menyertakan dukungan untuk Foundry classic.

Pasang tambahan [tools] untuk menggunakan alat seperti Kecerdasan Dokumen atau konektor Azure Logic Apps.

Atur variabel lingkungan yang digunakan dalam sampel:

export AZURE_AI_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
export MODEL_DEPLOYMENT_NAME="gpt-4.1"

Membuat pabrik agen

Buat sebuah AgentServiceFactory dengan menggunakan integrasi v1. Agen yang dibuat melalui pabrik ini dikelola di Foundry Classic.

import os

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.agents.v1 import AgentServiceFactory

factory = AgentServiceFactory(
    project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

Apa yang dilakukan cuplikan ini: Menyambungkan v1 AgentServiceFactory ke proyek Anda sehingga agen LangGraph berikutnya dapat dibuat dan dikelola di Foundry klasik.

Catatan

Agen yang dibuat dengan langchain_azure_ai.agents.v1.AgentServiceFactory terlihat di portal Foundry (klasik).

Membuat agen prompt dasar

Mulailah dengan agen prompt minimal untuk memvalidasi setelan Anda dengan cepat.

agent = factory.create_prompt_agent(
    name="my-echo-agent",
    model=os.environ["MODEL_DEPLOYMENT_NAME"],
    instructions=(
        "You are a helpful AI assistant that always replies back saying the "
        "opposite of what the user says."
    ),
    trace=True,
)

print(f"Agent with ID {factory.get_agents_id_from_graph(agent)} created.")

Agent with ID {'my-echo-agent:1'} created.

Panggil agen:

from langchain_core.messages import HumanMessage
from langchain_azure_ai.utils.agents import pretty_print

messages = [HumanMessage(content="I'm a genius and I love programming!")]
state = agent.invoke({"messages": messages})

pretty_print(state)

================================ Human Message =================================

I'm a genius and I love programming!
================================== Ai Message ==================================
Name: my-echo-agent

You are not a genius and you hate programming!

Apa yang dilakukan cuplikan ini: Membuat agen v1 berbasis prompt di Foundry Agent Service (klasik), memanggilnya, dan mencetak urutan pesan lengkap dari status LangGraph.

Anda dapat memvisualisasikan bagaimana agen dibuat dan digunakan dalam grafik LangGraph dengan mencetak representasi diagramnya. Simpul foundryAgent berjalan di Foundry Agent Service. Perhatikan bagaimana nama dan versi agen terlihat dalam grafik.

from IPython import display

display.Image(agent.get_graph().draw_mermaid_png())

factory.delete_agent(agent)

Apa yang dilakukan cuplikan ini: Merender grafik untuk menampilkan simpul Layanan Agen tunggal lalu menghapus agen sampel sementara.

Diagram graf agen untuk agen tanpa peralatan.

Mengonfigurasi pengaturan tingkat lanjut

Anda dapat mengonfigurasi perilaku model dan metadata dengan meneruskan argumen opsional ke create_prompt_agent.

custom_agent = factory.create_prompt_agent(
    name="custom-configured-agent",
    description="A creative writing assistant with poetic flair",
    model=os.environ["MODEL_DEPLOYMENT_NAME"],
    instructions="You are a creative writing assistant. Write in a poetic style.",
    temperature=0.8,
)

response = custom_agent.invoke(
    {"messages": [HumanMessage("Describe a sunset over the ocean.")]}
)

pretty_print(response)

================================ Human Message =================================

Describe a sunset over the ocean.
================================== Ai Message ==================================
Name: custom-configured-agent

...poetic response...

Opsi umum termasuk temperature, top_p, response_format, tools, tool_resources, dan metadata.

Apa yang dilakukan cuplikan ini: Membuat agen kedua dengan pengaturan generasi non-default dan memvalidasi perilaku menggunakan prompt sampel.

Tambahkan alat ke agen Anda

Anda dapat menambahkan alat ke agen Anda untuk melakukan tindakan. Metode create_prompt_agent ini mengimplementasikan perulangan agen untuk Anda.

Anda harus membedakan dua jenis alat:

Alat lokal: Itu adalah alat yang beroperasi di lokasi yang sama dengan tempat kode agen Anda dijalankan. Fungsi dapat dipanggil atau fungsi apa pun yang tersedia untuk ekosistem LangChain/LangGraph.
Alat bawaan: Itu adalah alat yang dapat berjalan secara eksklusif di Foundry Agent Service; sisi server. Alat sisi server hanya dapat diterapkan ke agen Foundry.

Dengan menambahkan alat lokal ke agen Anda, Anda akan menambahkan simpul alat ke grafik Anda untuk menjalankan alat tersebut. Alat bawaan tidak menambahkan simpul alat dan dijalankan dalam layanan saat Anda membuat permintaan.

Diagram graf agen untuk agen dengan alat.

Bagian berikut menjelaskan cara menggunakan keduanya:

Menambahkan alat lokal

Tentukan fungsi Python lokal dan serahkan ke tools.

def multiply(a: int, b: int) -> int:
    """Multiply two integers."""
    return a * b


def add(a: int, b: int) -> int:
    """Add two integers."""
    return a + b


def divide(a: int, b: int) -> float:
    """Divide one integer by another."""
    return a / b


tools = [add, multiply, divide]

math_agent = factory.create_prompt_agent(
    name="math-agent",
    model=os.environ["MODEL_DEPLOYMENT_NAME"],
    instructions=(
        "You are a helpful assistant tasked with performing arithmetic on "
        "a set of inputs."
    ),
    tools=tools,
)

Panggil agen yang dipersenjatai alat

messages = [
    HumanMessage(content="Add 3 and 4. Multiply the output by 2. Divide the output by 5")
]
state = math_agent.invoke({"messages": messages})
pretty_print(state)

================================ Human Message =================================

Add 3 and 4. Multiply the output by 2. Divide the output by 5
================================== Ai Message ==================================
Tool Calls:
    add (...)
    multiply (...)
    divide (...)
...
================================== Ai Message ==================================
Name: math-agent

The final result is 2.8.

Apa yang dilakukan potongan kode ini: Melampirkan tiga alat Python lokal ke agen prompt v1 dan menunjukkan pemanggilan alat berlangkah-langkah yang diorkestrasi melalui perulangan agen.

Gunakan alat lain dari ekosistem LangGraph/LangChain seperti Azure Kecerdasan Dokumen di Foundry Tools dari alur agen yang sama. Meskipun alat-alat tersebut terhubung ke sumber daya Foundry, alat tersebut tidak eksklusif untuk Layanan Agen dan karenanya bertindak seperti alat lokal.

from langchain_azure_ai.tools import AzureAIDocumentIntelligenceTool

document_parser_agent = factory.create_prompt_agent(
    name="document-agent",
    model=os.environ["MODEL_DEPLOYMENT_NAME"],
    instructions="You are a helpful assistant tasked with analyzing documents.",
    tools=[AzureAIDocumentIntelligenceTool(credential=DefaultAzureCredential())],
)

Tips

AzureAIDocumentIntelligenceTool dapat menggunakan proyek Foundry untuk terhubung ke layanan dan juga mendukung Microsoft Entra untuk autentikasi. Secara default, alat ini menggunakan AZURE_AI_PROJECT_ENDPOINT dengan DefaultAzureCredential, itulah sebabnya tidak diperlukan konfigurasi lebih lanjut. Anda dapat mengubahnya untuk menggunakan titik akhir dan kunci tertentu jika diperlukan.

Minta agen untuk menganalisis faktur dari URL:

messages = [
    HumanMessage(
        content=(
            "What's the total amount in the invoice at "
            "https://raw.githubusercontent.com/Azure/azure-sdk-for-python/main/"
            "sdk/formrecognizer/azure-ai-formrecognizer/tests/sample_forms/"
            "forms/Form_1.jpg"
        )
    )
]
response = document_parser_agent.invoke({"messages": messages})
pretty_print(response)

================================ Human Message =================================

What's the total amount in the invoice at ...
================================== Ai Message ==================================
Tool Calls:
    azure_ai_document_intelligence (...)
...
================================== Ai Message ==================================
Name: document-agent

The total amount in the invoice is **$144.00**.

Apa yang dilakukan cuplikan ini: Meminta agen untuk mengekstrak data dari gambar faktur sampel. Agen memanggil AzureAIDocumentIntelligenceTool untuk mengurai dokumen dan mengembalikan hasilnya. Output yang diharapkan: "Jumlah total dalam faktur adalah $144,00."

Menambahkan alat bawaan

Alat bawaan di Foundry Agent Service berjalan di sisi server alih-alih dalam simpul alat seperti alat lokal. Dalam pola v1 ini, buat alat bawaan dari azure.ai.agents.models dan bungkus dengan AgentServiceBaseTool untuk create_prompt_agent.

Contoh: gunakan alat penerjemah kode

Buat agen penerjemah kode untuk analisis data dan panggil dengan file data fiktif data.csv .

Sebelum menjalankan sampel ini, buat file lokal data.csv di direktori kerja Anda saat ini.

from pathlib import Path

import pandas as pd

data = {
    "month": ["Jan", "Feb", "Mar", "Apr", "May", "Jun"],
    "sales": [12000, 15000, 18000, 14000, 22000, 25000],
    "region": ["North", "South", "East", "West", "North", "South"],
}

df = pd.DataFrame(data)
csv_path = Path.cwd() / "data.csv"
df.to_csv(csv_path, index=False, encoding="utf-8-sig")

print(f"Created sample data file: {csv_path}")

Created sample data file: .../data.csv

File perlu diunggah ke proyek agar agen dapat menggunakannya. Anda dapat mengunggahnya dan mengonfigurasi file untuk alat atau membiarkan AgentServiceFactory menanganinya untuk Anda.

Mengunggah dan mengonfigurasi file untuk alat

Kita perlu mengunggah file ini sehingga tersedia untuk alat penerjemah kode. Gunakan Foundry SDK untuk mengunggahnya.

from azure.ai.agents import AgentsClient
from azure.ai.agents.models import CodeInterpreterTool, FilePurpose

client = AgentsClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

uploaded_file = client.files.upload_and_poll(
    file_path=str(csv_path),
    purpose=FilePurpose.AGENTS,
)
print(f"Uploaded file ID: {uploaded_file.id}")

Uploaded file ID: file_...

Apa yang dilakukan cuplikan ini: Mengunggah CSV sebagai file agen sehingga alat bawaan dapat mengaksesnya di runtime layanan.

Kemudian konfigurasikan alat:

code_interpreter = CodeInterpreterTool(file_ids=[uploaded_file.id])
print("Code interpreter tool configured.")

Code interpreter tool configured.

Apa yang dilakukan cuplikan ini: Mengikat file yang diunggah ke instans alat penerjemah kode sehingga agen dapat menjalankan analisis atas file tersebut.

Metode create_prompt_agent membutuhkan alat-alat Agent Service untuk dibungkus dalam AgentServiceBaseTool.

from langchain_azure_ai.agents.v1.prebuilt.tools import AgentServiceBaseTool


code_interpreter_agent = factory.create_prompt_agent(
    name="code-interpreter-agent",
    model=os.environ["MODEL_DEPLOYMENT_NAME"],
    instructions=(
        "You are a data analyst agent. Analyze the provided CSV data and "
        "create visualizations when helpful."
    ),
    tools=[AgentServiceBaseTool(tool=code_interpreter)],
)

Mari kita lihat dalam praktiknya:

messages = [
    HumanMessage(
        content=(
            "Create a pie chart with the previously uploaded file "
            f"(ID: {uploaded_file.id}) showing sales by region and show it "
            "to me as a PNG image."
        )
    )
]
state = code_interpreter_agent.invoke({"messages": messages})
pretty_print(state)

================================ Human Message =================================

Create a pie chart with the previously uploaded file ...
================================== Ai Message ==================================
Name: code-interpreter-agent

[
    {'type': 'text', 'text': 'Here is the pie chart ...'},
    {'type': 'image', 'mime_type': 'image/png', 'base64': 'iVBORw0...'}
]

Gambar yang dihasilkan oleh 'CodeInterpreterTool'.

Apa yang dilakukan cuplikan ini: Membungkus CodeInterpreterTool dengan AgentServiceBaseTool, menjalankan analisis di Agent Service, dan merender gambar PNG yang dikembalikan dari konten base64.

Kirim konten file langsung

Saat Anda meneruskan konten file sebagai input dan alat penerjemah kode dilampirkan ke agen, file diunggah secara otomatis.

import base64

code_interpreter_agent = factory.create_prompt_agent(
    name="code-interpreter-agent-inline-file",
    model=os.environ["MODEL_DEPLOYMENT_NAME"],
    instructions=(
        "You are a data analyst agent. Analyze the provided CSV data and "
        "create visualizations when helpful."
    ),
    tools=[AgentServiceBaseTool(tool=CodeInterpreterTool())],
)

with open("data.csv", "rb") as file_handle:
    csv_data = base64.b64encode(file_handle.read()).decode()

state = code_interpreter_agent.invoke(
    {
        "messages": [
            HumanMessage(
                content=[
                    {"type": "file", "mime_type": "text/csv", "base64": csv_data},
                    {
                        "type": "text",
                        "text": (
                            "Create a pie chart with the uploaded data showing "
                            "sales by region and show it as a PNG image."
                        ),
                    },
                ]
            )
        ]
    }
)

Apa yang dilakukan cuplikan ini: Mengirim file CSV sebaris dalam payload pesan sehingga penerjemah kode dapat memprosesnya tanpa langkah pengunggahan eksplisit terpisah.

Menjalankan operasi asinkron

Anda dapat memanggil agen v1 secara asinkron dengan ainvoke.

async def async_example() -> None:
    async_agent = factory.create_prompt_agent(
        name="async-demo-agent",
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        instructions="You are an async AI assistant.",
    )

    try:
        response = await async_agent.ainvoke(
            {
                "messages": [
                    HumanMessage("What are the benefits of asynchronous programming?")
                ]
            }
        )
        print(response)
    finally:
        factory.delete_agent(async_agent)


await async_example()

{'messages': [...], ...}

Apa yang dilakukan cuplikan ini: Menunjukkan pemanggilan asinkron dengan ainvoke dan memastikan pembersihan menggunakan factory.delete_agent dalam blok finally .

Agen pembersih

Hapus agen yang Anda buat selama sesi berlangsung.

factory.delete_agent(math_agent)
factory.delete_agent(document_parser_agent)
factory.delete_agent(custom_agent)
factory.delete_agent(code_interpreter_agent)

Pemecahan masalah

Gunakan daftar periksa ini untuk mendiagnosis masalah penyiapan dan runtime umum.

Aktifkan pengelogan

import logging

logging.getLogger("langchain_azure_ai").setLevel(logging.DEBUG)

Untuk diagnostik yang lebih luas:

import logging

logging.basicConfig(level=logging.DEBUG)

Memvalidasi konfigurasi Anda

Pastikan AZURE_AI_PROJECT_ENDPOINT mengarah ke titik akhir dari proyek klasik Foundry yang benar.
Pastikan MODEL_DEPLOYMENT_NAME cocok dengan penyebaran model yang ada.
Verifikasi konteks autentikasi dengan az account show.
Mulailah terlebih dahulu dengan contoh agen prompt minimal.

Memverifikasi sumber daya dan izin

Pastikan akun Anda dapat mengakses proyek dan implementasi model.
Pastikan sumber daya dependen, seperti file yang diunggah dan sumber daya alat, ada.
Verifikasilah sumber daya berada di subskripsi dan wilayah yang telah ditentukan.

Langkah berikutnya

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-05-01