Разработка агентов с помощью LangGraph и агентской службы Microsoft Foundry (классическая модель)

Применяется только к:Портал Foundry (классический). Эта статья недоступна для нового портала Foundry. Дополнительные сведения о новом портале.

langchain-azure-ai Используйте пакет для подключения приложений LangGraph и LangChain к службе агента Foundry. В этой статье рассматриваются практические сценарии, от базовых агентов подсказок до рабочих процессов, использующих инструменты.

Необходимые условия

• Подписка Azure. Создайте его бесплатно.
• Проект Foundry в классической версии Foundry.
• Развернутая модель чата (например, gpt-4.1) в проекте.
• Python 3.10 или более поздней версии.
• Azure CLI вошел в систему (az login), чтобы DefaultAzureCredential могла пройти проверку подлинности.

Настройка среды

Установите пакеты, используемые в этой статье:

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

Установите дополнительные компоненты [tools], чтобы использовать такие средства, как аналитика документов или соединители Azure Logic Apps.

Задайте переменные среды, используемые в примерах:

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

Создание фабрики агентов

Создайте AgentServiceFactory с помощью интеграции v1. Агенты, созданные с помощью этой фабрики, управляются в классической модели Foundry.

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(),
)

Что делает этот фрагмент кода: Подключает версию 1 AgentServiceFactory к проекту, чтобы последующие агенты LangGraph могли создаваться и управляться в классической версии Foundry.

Создание базового агента запроса

Начните с минимального агента запроса, чтобы быстро проверить настройку.

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.

Вызов агента:

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!

Что делает этот фрагмент кода: Создает агент на основе запроса версии 1 в службе агента Foundry (классическая модель), вызывает его и выводит полную последовательность сообщений из состояния LangGraph.

Вы можете визуализировать, как агент был создан и использован в графе LangGraph, распечатав его представление схемы. Узел foundryAgent выполняется в службе агента Foundry. Обратите внимание, как имя и версия агента отображаются на графе.

from IPython import display

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

factory.delete_agent(agent)

Что делает этот фрагмент кода: Отрисовывает граф для отображения одного узла службы агента, а затем удаляет временный образец агента.

Настройка дополнительных параметров

Поведение модели и метаданные можно настроить, передав в 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...

Распространенные варианты: temperature, top_p, response_format, tools, tool_resources, и metadata.

Что делает этот фрагмент кода: Создает второй агент с параметрами создания не по умолчанию и проверяет поведение с помощью примера запроса.

Добавьте инструменты в вашего агента

Вы можете добавить инструменты в ваш агент для выполнения действий. Метод create_prompt_agent реализует цикл агента для вас.

Следует различать два типа инструментов:

• Локальные инструменты: это инструменты, которые выполняются в одной среде с кодом агента. Они могут быть вызываемыми функциями или любой функцией, доступной для экосистемы LangChain/LangGraph.
• Встроенные инструменты: это инструменты, которые могут выполняться исключительно в службе Foundry Agent; на стороне сервера. Серверные средства можно применять только к агентам Foundry.

Добавление локальных инструментов в ваш агент системы добавляет узел инструментов в ваш граф для их выполнения. Встроенные инструменты не добавляют узел инструмента и выполняются в процессе выполнения запроса.

В следующем разделе объясняется, как использовать оба:

Добавить локальные инструменты

Определите локальные функции Python и передайте их в 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,
)

Активировать агента, оснащенного инструментом:

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.

Что делает этот фрагмент кода: присоединяет три локальных инструмента Python к агенту запроса версии 1 и демонстрирует многоэтапные обращения к инструментам, организованные через цикл агента.

Используйте другие средства из экосистемы LangGraph/LangChain, например Azure Интеллектуальный анализ документов в рамках инструментов Foundry из того же потока агента. Хотя эти средства подключены к ресурсу Foundry, они не являются эксклюзивными для службы агентов и, следовательно, действуют как локальное средство.

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())],
)

Попросите агента проанализировать счет по 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**.

Что делает этот фрагмент кода: Запрашивает агент извлечь данные из примера образа счета. Агент вызывает AzureAIDocumentIntelligenceTool для анализа документа и возвращает результат. Ожидаемый результат: "Общая сумма в счете составляет $ 144,00".

Добавление встроенных средств

Встроенные средства в Службе агентов Foundry выполняются на стороне сервера, а не в узле инструментов, как местные инструменты. В этом шаблоне версии 1 создайте встроенные инструменты из azure.ai.agents.models, обернув их AgentServiceBaseTool для create_prompt_agent.

Пример. Использование средства интерпретатора кода

Создайте агент интерпретатора кода для анализа данных и вызовите его с помощью вымышленного data.csv файла данных.

Перед выполнением этого примера создайте локальный data.csv файл в текущем рабочем каталоге.

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

Файлы необходимо передать в проект, чтобы агенты использовали их. Вы можете либо загрузить файл и настроить его для работы с инструментом, либо позволить AgentServiceFactory сделать это за вас.

Загрузка и настройка файлов для инструментов

Необходимо передать этот файл, чтобы он был доступен инструменту интерпретатора кода. Используйте SDK Foundry для их загрузки.

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

Что делает этот фрагмент кода: Отправляет CSV-файл в виде файла агента, чтобы встроенные средства могли получить к нему доступ в среде выполнения службы.

Затем настройте средство:

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

Code interpreter tool configured.

Что делает этот фрагмент кода: Привязывает отправленный файл к экземпляру средства интерпретатора кода, чтобы агент смог выполнить анализ этого файла.

Методу create_prompt_agent требуется, чтобы средства службы агента были упакованы в 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)],
)

Давайте посмотрим на практике:

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...'}
]

Что делает этот фрагмент кода: Оборачивает CodeInterpreterTool с помощью AgentServiceBaseTool, выполняет анализ в службе Агент и отрисовывает возвращенное изображение PNG из содержимого base64.

Отправка встроенного содержимого файла

При передаче содержимого файла в качестве входных данных, а средство интерпретатора кода подключено к агенту, файлы передаются автоматически.

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

Что делает этот фрагмент кода: Отправляет CSV-файл в составе полезной нагрузки сообщения, чтобы интерпретатор кода мог обработать его без отдельного шага загрузки.

Выполнение асинхронных операций

Вы можете асинхронно вызывать агентов версии 1 с помощью 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': [...], ...}

Что делает этот фрагмент кода: Демонстрирует асинхронные вызовы с ainvoke и обеспечивает очистку с factory.delete_agent в блоке finally.

Очистка агентов

Удалите агенты, созданные во время сеанса.

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

Устранение неполадок

Используйте этот контрольный список для диагностики распространенных проблем с настройкой и средой выполнения.

Включение ведения журнала

import logging

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

Для более широкой диагностики:

import logging

logging.basicConfig(level=logging.DEBUG)

Проверка конфигурации

• Убедитесь, что AZURE_AI_PROJECT_ENDPOINT указывает на правильную конечную точку классического проекта Foundry.
• Подтвердите, что MODEL_DEPLOYMENT_NAME соответствует существующему развертыванию модели.
• Проверьте контекст аутентификации с помощью az account show.
• Сначала начните с минимального примера агента запроса.

Проверка ресурсов и разрешений

• Убедитесь, что ваша учетная запись может получить доступ к развертыванию проекта и модели.
• Убедитесь, что зависимые ресурсы, такие как загруженные файлы и ресурсы инструментов, существуют.
• Убедитесь, что ресурсы находятся в ожидаемой подписке и регионе.

Дальнейшие действия

• Разработка приложений с помощью LlamaIndex
• Визуализация трассировок и управление ими в Foundry
• Использование моделей Foundry
• Справочник. API вывода модели