Цель этой заметки - показать один из вариантов того, как прикрутить LLM к существующему ASP.NET API с минимальными трудозатратами (на базе Semantic Kernel).

Итак задача - имея в производстве классический ASP.NET API сервис на стеке Microsoft (разделённые (типа микро) сервисы, инфраструктура на Azure) добавить к нему еще один сервис для AI агента. Агент, как и прочие сервисы будет вызываться из клиента, в контексте авторизированного пользователя.

Постановка вопроса и общий принцип

Проект, с которым я работаю, можно отнести к категории «умный дом», где пользователь через сайт может создать инфраструктуру, указать, где и что стоит, связаться с реальными устройствами, настраивать их, и так далее Идея состоит в том, чтобы на сайт прикрутить «ИИ чат», дав пользователю альтернативный способ управления. «Добавь такой‑то контроллер на второй этаж», например. В общем всё то, что можно сделать через сайт, плюс новые возможности, там не предусмотренные, например: «Сравни конфигурации устройств по таким‑то параметрам». Для этого очевидно нужна какая‑то LLM с возможностью вызывать необходимый API. Получается примерно такая схема:

LLM вызывается через Open AI (Azure open AI)
Существующие API документируются и списком отправляются вместе с запросом
LLM исходя из контекста запроса, может вызывать функции из этого списка

Еще нужно держать где-то контекст чата. Добавляем хранилище и имеем почти стандартную диаграмму MCP сервера:

тут эта диаграмма в разметке mermaid

mermaid
sequenceDiagram
    participant FE as Frontend
    participant API as AiAgent API<br/>(MCP Client)
    participant MCP as MCP Servers
    participant AOAI as Azure OpenAI
    participant APIs as Microservices
    participant DB as Database
    
    FE->>API: POST /chats {message}
    API->>DB: Load history
    API->>MCP: Discover all tools
    MCP-->>API: All available tools
    API->>AOAI: Chat + all tools
    AOAI-->>API: tool_calls
    API->>MCP: Execute tool
    MCP->>APIs: API call
    APIs-->>MCP: Result
    MCP-->>API: Tool result
    API->>AOAI: Continue with result
    AOAI-->>API: Final response
    API->>DB: Save conversation
    API-->>FE: Response

Прототип заработал, но получился громоздким и негибким, особенно в плане оркестрации. Лучшей альтернативой оказался Semantic Kernel, "официальный SDK" для ИИ интеграции. Он и оркестрацию на себя берёт и описание API может брать просто из ссылки на swagger.json ! То есть мой ИИ агент будет всегда иметь актуальную информацию и всё, что мне нужно реализовать — это тонкую прослойку для формирования этого самого kernel. Выглядит ненамного проще, но на деле получилось чисто и аккуратно.

диаграмма в разметке mermaid

mermaid
sequenceDiagram
    participant FE as Frontend
    participant API as AiAgent API
    participant KF as Semantic Kernel
    participant AOAI2 as Azure OpenAI<br/>(Auto Function Calls)
    participant APIs as Microservices
    participant DB as Database

    FE->>API: POST /chats {message}
    API->>DB: Load history
    API->>KF: Chat + Swagger.json files
    KF->>AOAI2: Chat + function list
    AOAI2-->>KF: Required functions
    KF->>APIs: Function calls
    APIs-->>KF: Results
    KF->>AOAI2: Function Results
    AOAI2-->>API: Final response
    API->>DB: Save conversation
    API-->>FE: Response

Теперь немного кода

Сперва выбираем LLM модель. Что-то небольшое, но не слишком старое, чтоб была поддержка структурированного вывода. Я взял gpt-4.1-mini. В портале Azure создаем Microsoft Foundry | Azure OpenAI ресурс и публикуем выбранную модель. Из деплоймента нужен ключ, адрес и имя.

Добавляем новый ASP.NET API проект, и в числе прочего добавляем необходимые материалы в pipeline в Program.cs

// там лежат OpenAi Endpoint, ApiKey, DeploymentId и SystemPrompt
builder.Services.AddOptions<AiAgentOptions>().Bind(builder.Configuration.GetSection("AiAgent"));

// обычный EF core db context, для истории чата
builder.Services.AddScoped<IChatSessionRepository, ChatSessionRepository>(); 

// в IKernelFactory один метод CreateForApisAsync(IEnumerable<string> apiNames, Guid sessionId), 
// выдающий легковесный kernel
builder.Services.AddScoped<IKernelFactory, KernelFactory>(); 

// вспомогательный агент, IApiClassifier содержит один метод ClassifyAsync(string userMessage),
// для фильтрации функций API
builder.Services.AddScoped<IApiClassifier, ApiClassifier>(); 

// дирижер этого балагана, содержит один метод ExecuteTurnAsync(Guid sessionId, string userMessage) 
builder.Services.AddScoped<IChatOrchestrator, ChatOrchestrator>();

Чтобы агент мог поддерживать беседу, нужно передавать весь чат с каждым запросом. Для этого на обоих концах держим SessionId, создаваемый в начале беседы. Когда приходит новое сообщение, по SessionId загружаем историю чата и закидываем в соответствующие коллекции в хронологическом порядке.

internal class ChatOrchestrator : IChatOrchestrator
{ 
...

public async Task<string> ExecuteTurnAsync(Guid sessionId, string userMessage, CancellationToken cancellationToken)
{
 ...
  //самый обычный EF db context
  var conversationMessages = await m_Repository.GetLastMessagesAsync(sessionId, cancellationToken);
  
  //API так много, что всё не влазит и нужно ограничевать количество функций
  var apiNames = await m_ApiClassifier.ClassifyAsync(userMessage, cancellationToken); 
  
  //создаём легковесный kernel
  var kernel = await m_KernelFactory.CreateForApisAsync(apiNames, sessionId, cancellationToken);
  var chatHistory = new ChatHistory();
  
  // В системном сообщении объясняются задачи и ограничения ассистента, 
  // достаточно подробно и с примерами. 
  chatHistory.AddSystemMessage(m_Options.SystemPrompt);
  
  foreach (var msg in conversationMessages.OrderBy(m => m.CreatedUtc))
  {
      if (msg.Role.Equals("user"))
      {
          chatHistory.AddUserMessage(msg.Content);
      }
      else if (msg.Role.Equals("assistant"))
      {
          chatHistory.AddAssistantMessage(msg.Content);
      }
  }
  
  // Добовляем само сообщение
  chatHistory.AddUserMessage(userMessage);
  
  // Получаем ответ
  var responseRaw = await InvokeWithAutomaticToolLoopAsync(kernel, chatService, chatHistory, sessionId, cancellationToken);

В строке 12 выше вызывается m_ApiClassifier.ClassifyAsync . Это не не имеет прямого отношения в Semantic Kernel, просто если в API больше чем 128 функций, то их приходится как-то ограничить и фильтровать. Дело в том, что у Open AI стоит жёсткий лимит на количество "tools". Как вариант обойти ограничение, можно попросить LLM выбрать только необходимые инструменты, исходя из их описания. В этом случает на каждый пользовательский вопрос приходится два вызова ИИ ассистента. (первый - исходя из семантики вопроса выбрать необходимые функции).

В строке 15 m_KernelFactory.CreateForApisAsync создаёт kernel на основе ключа и адреса LLM ассистента.

public Task<Kernel> CreateForApisAsync(...)
{
  var builder = Kernel.CreateBuilder();
  
  builder.AddAzureOpenAIChatCompletion(
      deploymentName: m_Options.AzureOpenAiDeploymentId,
      endpoint: m_Options.AzureOpenAiEndpoint,
      apiKey: m_Options.AzureOpenAiApiKey);
  
  var kernel = builder.Build();
...

Там же загружаются необходимые инструменты с указанием callback для авторизации

...
  var executionParameters = new OpenApiFunctionExecutionParameters(httpClient)
  {
      // в authCallback прокидивыются нужные authentication headers, 
      // authCallback вызывается на каждую функцию
      AuthCallback = authCallback 
  };
  
  // для каждого сервиса, который, согласно ApiClassifier, может потребоваться
  // для ответа на вопрос, указываем swagger документ с описанием функций и DTO
  await kernel.ImportPluginFromOpenApiAsync(
      pluginName: api.Name, 
      uri: new Uri(api.SwaggerUrl),
      executionParameters: executionParameters,
      cancellationToken: cancellationToken);
...

Первый листинг завершается вызовом InvokeWithAutomaticToolLoopAsync, на строке 38 вот важные моменты оттуда:

private async Task<string> InvokeWithAutomaticToolLoopAsync(Kernel kernel ...
{
  //основные параметры для ИИ ассистента. 
  //Вызов API можно контролировать вручную с ToolCallBehavior = ToolCallBehavior.EnableKernelFunctions, 
  //с ToolCallBehavior.AutoInvokeKernelFunctions Semantic Kernel вызывает API сам.
  //Temperature чем ниже, тем меньше LLM фантазирует. 
  //ResponseFormat можно задать в JSON схеме (если выбранная LLM поддерживает)
  var executionSettings = new OpenAIPromptExecutionSettings
  {
      ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions,
      Temperature = 0.3,
      ResponseFormat = null,
      MaxTokens = 5000
  };
  
  //передаём полную историю чата, настройки и получаем ответ
  ChatMessageContent result = await chatService.GetChatMessageContentAsync(
      chatHistory,
      executionSettings: executionSettings,
      kernel: kernel,
      cancellationToken: cancellationToken);

Как вывод, можно сказать:

Если Open API документация прописана хорошо, то агент определяет, что и как вызвать, прямо таки с пугающей точностью. Правда, стоит отметить, что системное сообщение нужно прописывать весьма детально, начиная с описания системы, что она такое и зачем. Что пользователь может делать, что нет, как понимать DTO и другие нюансы.

Были, конечно, сугубо специфичные для нашей системы проблемы. И разумеется, чтоб внедрить этот чат в продукт, придется решить вопросы по безопасности и с большой вероятностью адаптировать API. Но в общем и целом, создать свой "co-pilot" оказалось намного проще, чем я думал. Удивило и то, как тонко и гибко можно настроить, контролировать и логировать вызываемые функции. Да, они вызываются автоматически, но при необходимости можно настроить http request перед вызовом API и контролировать контекст вызова через IFunctionInvocationFilter

ИИ чат для API или «Co-Pilot» своими руками