Membuat Agen

Penting

Mulai Januari 2026, proyek AI Shell tidak lagi dipelihara secara aktif. Proyek ini harus dianggap diarsipkan dari sudut pandang teknik.

Agen adalah pustaka kode yang berinteraksi dengan AI Shell untuk berbicara dengan model bahasa besar tertentu atau penyedia bantuan lainnya. Pengguna mengobrol dengan agen menggunakan bahasa alami untuk mendapatkan output atau bantuan yang diinginkan. Agen diimplementasikan sebagai kelas C# yang mengimplementasikan antarmuka ILLMAgent dari paket AIShell.Abstraction.

Untuk detail tentang lapisan AIShell.Abstraction dan AIShell.Kernel, lihat arsitektur AI Shell dokumentasi.

Artikel ini adalah panduan langkah demi langkah untuk membuat agen untuk model bahasa Ollama . Tujuan dari artikel ini adalah untuk memberikan contoh sederhana tentang cara membuat agen. Ada implementasi agen Ollama yang lebih kuat di AIShell.Ollama.Agent folder repositori.

Prasyarat

  • .NET 8 SDK atau yang lebih baru
  • PowerShell 7.4.6 atau yang lebih baru

Langkah-langkah untuk membuat agen

Untuk contoh ini, kita membuat agen untuk berkomunikasi dengan model phi3 bahasa menggunakan Ollama. Ollama adalah alat CLI untuk mengelola dan menggunakan LLM/SLM buatan lokal.

Langkah 1: Buat proyek baru

Langkah pertama adalah membuat proyek classlib baru.

  1. Membuat folder baru bernama OllamaAgent

  2. Jalankan perintah berikut untuk membuat proyek baru:

    dotnet new classlib

Langkah 2: Tambahkan paket yang diperlukan

Dalam proyek yang baru dibuat, Anda perlu menginstal paket AIShell.Abstraction dari galeri NuGet. Instal paket NuGet menggunakan perintah berikut:

dotnet add package AIShell.Abstraction --version 1.0.0-preview.2

Perintah ini menambahkan paket ke file .csproj Anda. File .csproj Anda harus berisi XML berikut:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <SuppressNETCoreSdkPreviewMessage>true</SuppressNETCoreSdkPreviewMessage>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="AIShell.Abstraction" Version="1.0.0-preview.2" />
  </ItemGroup>
</Project>

Penting

Pastikan Anda berada di versi terbaru dari galeri NuGet.

Langkah 3: Menerapkan kelas agen

Untuk menerapkan antarmuka ILLMAgent, ubah file Class1.cs.

  1. Ganti nama file menjadi OllamaAgent.cs
  2. Ganti nama kelas menjadi OllamaAgent
  3. Tambahkan namespace layanan .NET yang digunakan oleh kode dalam implementasi
using System.Diagnostics;
using System.Text;
using System.Text.Json;
using AIShell.Abstraction;

namespace AIShell.Ollama.Agent;

public sealed class OllamaAgent : ILLMAgent
{

}

Langkah 4: Tambahkan anggota dan metode kelas yang diperlukan

Selanjutnya, terapkan variabel dan metode yang diperlukan dari kelas agen. Komentar memberikan deskripsi anggota kelas OllamaAgent. _chatService Anggota adalah instans kelas OllamaChatService, yang Anda terapkan di langkah selanjutnya.

public sealed class OllamaAgent : ILLMAgent
{
    /// <summary>
    /// The name of the agent
    /// </summary>
    public string Name => "ollama";

    /// <summary>
    /// The description of the agent to be shown at start up
    /// </summary>
    public string Description => "This is an AI assistant that uses the Ollama CLI tool. Be sure to follow all prerequisites in https://aka.ms/ollama/readme";

    /// <summary>
    /// This is the company added to `/like` and `/dislike` verbiage for who the telemetry helps.
    /// </summary>
    public string Company => "Microsoft";

    /// <summary>
    /// These are samples that are shown at start up for good questions to ask the agent
    /// </summary>
    public List<string> SampleQueries => [
        "How do I list files in a given directory?"
    ];

    /// <summary>
    /// These are any optional legal/additional information links you want to provide at start up
    /// </summary>
    public Dictionary<string, string> LegalLinks { private set; get; }

    /// <summary>
    /// This is the chat service to call the API from
    /// </summary>
    private OllamaChatService _chatService;

    /// <summary>
    /// A string builder to render the text at the end
    /// </summary>
    private StringBuilder _text;

    /// <summary>
    /// Dispose method to clean up the unmanaged resource of the chatService
    /// </summary>
    public void Dispose()
    {
        _chatService?.Dispose();
    }

    /// <summary>
    /// Initializing function for the class when the shell registers an agent
    /// </summary>
    /// <param name="config">Agent configuration for any configuration file and other settings</param>
    public void Initialize(AgentConfig config)
    {
        _text = new StringBuilder();
        _chatService = new OllamaChatService();

        LegalLinks = new(StringComparer.OrdinalIgnoreCase)
        {
            ["Ollama Docs"] = "https://github.com/ollama/ollama",
            ["Prerequisites"] = "https://aka.ms/ollama/readme"
        };

    }

    /// <summary>
    /// Get commands that an agent can register to the shell when being loaded
    /// </summary>
    public IEnumerable<CommandBase> GetCommands() => null;

    /// <summary>
    /// Gets the path to the setting file of the agent.
    /// </summary>
    public string SettingFile { private set; get; } = null;

    /// <summary>
    /// Refresh the current chat by starting a new chat session.
    /// An agent can reset chat states in this method.
    /// </summary>
    public void RefreshChat() {}

    /// <summary>
    /// Gets a value indicating whether the agent accepts a specific user action feedback.
    /// </summary>
    /// <param name="action">The user action.</param>
    public bool CanAcceptFeedback(UserAction action) => false;

    /// <summary>
    /// A user action was taken against the last response from this agent.
    /// </summary>
    /// <param name="action">Type of the action.</param>
    /// <param name="actionPayload"></param>
    public void OnUserAction(UserActionPayload actionPayload) {}

    /// <summary>
    /// Main chat function that takes
    /// </summary>
    /// <param name="input">The user input from the chat experience</param>
    /// <param name="shell">The shell that provides host functionality</param>
    /// <returns>Task Boolean that indicates whether the query was served by the agent.</returns>
    public async Task<bool> Chat(string input, IShell shell)
    {

    }
}

Untuk implementasi awal, agen akan mengembalikan "Hello World!", membuktikan bahwa Anda membuat antarmuka yang benar. Anda juga perlu menambahkan try-catch blok untuk menangkap dan menangani pengecualian apa pun saat pengguna mencoba membatalkan operasi.

Tambahkan kode berikut ke metode Chat Anda.

public async Task<bool> Chat(string input, IShell shell)
{
    // Get the shell host
    IHost host = shell.Host;

    // get the cancellation token
    CancellationToken token = shell.CancellationToken;

    try
    {
       host.RenderFullResponse("Hello World!");
    }
    catch (OperationCanceledException e)
    {
        _text.AppendLine(e.ToString());

        host.RenderFullResponse(_text.ToString());

        return false;
    }

    return true;
}

Langkah 5: Tambahkan pemeriksaan Ollama

Selanjutnya, Anda perlu memastikan bahwa Ollama berjalan.

public async Task<bool> Chat(string input, IShell shell)
{
    // Get the shell host
    IHost host = shell.Host;

    // get the cancellation token
    CancellationToken token = shell.CancellationToken;

    if (Process.GetProcessesByName("ollama").Length is 0)
    {
        host.RenderFullResponse("Please be sure that Ollama is installed and the server is running. Ensure that you have met all the prerequisites in the README for this agent.");
        return false;
    }

    // Calls to the API will go here

    return true;
}

Langkah 6: Membuat struktur data untuk bertukar data dengan Layanan Obrolan

Sebelum dapat menggunakan API Ollama, Anda perlu membuat kelas yang mengirim input ke dan menerima respons dari API Ollama. Contoh Ollama berikut menunjukkan format input dan respons dari agen.

Contoh ini memanggil API Ollama dengan streaming dinonaktifkan. Ollama menghasilkan satu respons tetap. Di masa mendatang, Anda dapat menambahkan kemampuan streaming sehingga respons dapat dirender secara real time, karena agen menerimanya.

Untuk menentukan struktur data, buat file baru di folder yang sama bernama OllamaSchema.cs. Salin kode berikut ke file.

namespace AIShell.Ollama.Agent;

// Query class for the data to send to the endpoint
internal class Query
{
    public string prompt { get; set; }
    public string model { get; set; }

    public bool stream { get; set; }
}

// Response data schema
internal class ResponseData
{
    public string model { get; set; }
    public string created_at { get; set; }
    public string response { get; set; }
    public bool done { get; set; }
    public string done_reason { get; set; }
    public int[] context { get; set; }
    public double total_duration { get; set; }
    public long load_duration { get; set; }
    public int prompt_eval_count { get; set; }
    public int prompt_eval_duration { get; set; }
    public int eval_count { get; set; }
    public long eval_duration { get; set; }
}

internal class OllamaResponse
{
    public int Status { get; set; }
    public string Error { get; set; }
    public string Api_version { get; set; }
    public ResponseData Data { get; set; }
}

Sekarang Anda memiliki potongan-potongan yang diperlukan untuk membangun layanan obrolan yang menggunakan API Ollama. Kelas layanan obrolan terpisah tidak diperlukan, tetapi berguna untuk mengabstraksi panggilan ke API.

Buat file baru yang disebut OllamaChatService.cs di folder yang sama dengan agen. Salin contoh kode ke dalam file.

Petunjuk / Saran

Contoh ini menggunakan titik akhir dan model bahasa yang dikodekan secara permanen untuk API Ollama. Di masa mendatang, Anda dapat menentukan parameter yang dapat dikonfigurasi dalam file konfigurasi agen.

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

using AIShell.Abstraction;

namespace AIShell.Ollama.Agent;

internal class OllamaChatService : IDisposable
{
    /// <summary>
    /// Ollama endpoint to call to generate a response
    /// </summary>
    internal const string Endpoint = "http://localhost:11434/api/generate";

    /// <summary>
    /// Http client
    /// </summary>
    private readonly HttpClient _client;

    /// <summary>
    /// Initialization method to initialize the http client
    /// </summary>

    internal OllamaChatService()
    {
        _client = new HttpClient();
    }

    /// <summary>
    /// Dispose of the http client
    /// </summary>
    public void Dispose()
    {
        _client.Dispose();
    }

    /// <summary>
    /// Preparing chat with data to be sent
    /// </summary>
    /// <param name="input">The user input from the chat experience</param>
    /// <returns>The HTTP request message</returns>
    private HttpRequestMessage PrepareForChat(string input)
    {
        // Main data to send to the endpoint
        var requestData = new Query
        {
            model = "phi3",
            prompt = input,
            stream = false
        };

        var json = JsonSerializer.Serialize(requestData);

        var data = new StringContent(json, Encoding.UTF8, "application/json");
        var request = new HttpRequestMessage(HttpMethod.Post, Endpoint) { Content = data };

        return request;
    }

    /// <summary>
    /// Getting the chat response async
    /// </summary>
    /// <param name="context">Interface for the status context used when displaying a spinner.</param>
    /// <param name="input">The user input from the chat experience</param>
    /// <param name="cancellationToken">The cancellation token to exit out of request</param>
    /// <returns>Response data from the API call</returns>
    internal async Task<ResponseData> GetChatResponseAsync(IStatusContext context, string input, CancellationToken cancellationToken)
    {
        try
        {
            HttpRequestMessage request = PrepareForChat(input);
            HttpResponseMessage response = await _client.SendAsync(request, cancellationToken);
            response.EnsureSuccessStatusCode();

            context?.Status("Receiving Payload ...");
            Console.Write(response.Content);
            var content = await response.Content.ReadAsStreamAsync(cancellationToken);
            return JsonSerializer.Deserialize<ResponseData>(content);
        }
        catch (OperationCanceledException)
        {
            // Operation was cancelled by user.
        }

        return null;
    }
}

Langkah 7: Hubungi layanan obrolan

Selanjutnya, Anda perlu memanggil layanan obrolan di kelas agen utama. Ubah metode Chat() untuk memanggil layanan obrolan dan merender respons kepada pengguna. Contoh berikut menunjukkan metode Chat() yang telah selesai.

public async Task<bool> Chat(string input, IShell shell)
{
    // Get the shell host
    IHost host = shell.Host;

    // get the cancellation token
    CancellationToken token = shell.CancellationToken;

    if (Process.GetProcessesByName("ollama").Length is 0)
    {
        host.RenderFullResponse("Please be sure that Ollama is installed and the server is running. Ensure that you have met all the prerequisites in the README for this agent.");
        return false;
    }

    ResponseData ollamaResponse = await host.RunWithSpinnerAsync(
        status: "Thinking ...",
        func: async context => await _chatService.GetChatResponseAsync(context, input, token)
    ).ConfigureAwait(false);

    if (ollamaResponse is not null)
    {
        // render the content
        host.RenderFullResponse(ollamaResponse.response);
    }

    return true;
}

Kode agen selesai.

Langkah 8: Membangun dan menguji agen

Selanjutnya, Anda perlu membangun dan menguji bahwa kode berfungsi seperti yang diharapkan. Jalankan perintah berikut:

dotnet build

Perintah ini membangun semua paket yang diperlukan di folder \bin\Debug\net8.0 proyek.

Agar aish memuat agen, Anda perlu menyalin file .dll ke folder di folder Agents. Nama folder harus sama dengan nama agen.

Anda dapat menginstal agen di salah satu dari dua lokasi:

  • Di folder Agents di bawah lokasi tempat Anda menginstal aish.exe. [pasang skrip][08] untuk AI Shell diinstal di %LOCALAPPDATA%\Programs\AIShell. Buat folder %LOCALAPPDATA%\Programs\AIShell\Agents\OllamaAgent.
  • Sebagai alternatif, Anda menginstal agen di %USERPROFILE%\.aish\Agents. Buat folder %USERPROFILE%\.aish\Agents\OllamaAgent.

Salin file .dll ke folder agen yang Anda buat. Anda akan melihat agen ketika Anda mulai aish.

AI Shell
v1.0.0-preview.2

Please select an agent to use:

    azure
   >ollama
    openai-gpt

Bagaimana cara berbagi agen saya sendiri?

Tidak ada cara untuk membagikan agen Anda di repositori terpusat. Kami sarankan untuk menempa repositori ini untuk pengembangan agen Anda sendiri. Anda dapat membagikan tautan fork Anda di bagian tab Diskusi dari repositori ini. Untuk menggunakan agen, letakkan file agen dll di agents folder direktori aish.exedasar . AI Shell secara otomatis memuat agen dari folder tersebut.

  • Last updated on