LightAgent 0.9.26

LightAgent Integration Guide

This document explains how to integrate LightAgent, register tools, connect to an LLM service, process events, and safely execute UI-related tools.

Authoring Tools

LightAgent currently supports tools implemented as native runtime objects.

To expose a method as a tool:

• Apply ToolAttribute
• Provide a non-empty description
• Apply ToolParameterAttribute to every parameter
• Return type can be any serializable object
• LightAgent automatically serializes the return value to text

Example:

public class FileToolAdapter
{
    [Tool(
        Description = "Create a file")]
    public ToolReturnValue CreateFile(
        [ToolParameter(
            Description = "File path")]
        string path,

        [ToolParameter(
            Description = "File content")]
        string text)
    {
        ...
    }
}

Create an Agent Instance

Register Tool Objects

LightAgent requires actual tool instances.

var fileTool =
    new FileToolAdapter();

var agent =
    new AgentV1(
        null,
        appAdapter,
        new object[]
        {
            fileTool
        },
        typeof(LlmClientV2));

Multiple tools can be registered:

var fileTool =
    new FileToolAdapter();

var mailTool =
    new MailToolAdapter();

var agent =
    new AgentV1(
        null,
        appAdapter,
        new object[]
        {
            fileTool,
            mailTool
        },
        typeof(LlmClientV2));

Important: LightAgent executes tools directly on the registered instances. Tool types alone are not sufficient.

UI Thread Invocation

Some tools must execute on the UI thread.

Examples:

• WinForms controls
• WPF controls
• Clipboard operations
• COM components
• Embedded browser controls

LightAgent provides the OnInvoke callback:

public Func<Func<object>, object> OnInvoke;

When configured, all tool execution will be routed through it.

WinForms Example

agent.OnInvoke = action =>
{
    if (InvokeRequired)
    {
        return Invoke(action);
    }

    return action();
};

WPF Example

agent.OnInvoke = action =>
{
    return Dispatcher.Invoke(action);
};

When OnInvoke is not assigned, LightAgent executes tools on a worker thread.

Connect to the LLM

After creating the agent, connect it to an LLM service.

await agent.SendAsync(
    new AgentConnectCommand
    {
        Endpoint = endpoint,
        ApiKey = apiKey,
        Model = modelName,
        ContextWindowSize = 50000
    });

Verify Connection Result

Wait for a connection event from the event stream.

var evt =
    await agent.Events.ReadAsync();

if (evt is AgentConnectResultEvent conn &&
    conn.Success)
{
    // Connected successfully
}

Connection Parameters

Sending User Requests

Send a request after a successful connection.

await agent.SendAsync(
    new AgentUserRequestCommand
    {
        UserOriginalInputText =
            "Summarize this document"
    });

Cancelling Current Request

LightAgent supports cancellation of the current session.

agent.CancelCurrent();

This cancels:

• LLM requests
• Tool execution pipeline
• Aggregation operations
• Current conversation session

Processing Agent Events

Applications should continuously consume events from the agent.

A common pattern is to start a dedicated background worker.

private void ProcessEvents()
{
    _ = Task.Run(async () =>
    {
        var reader = _agent.Events;

        while (await reader.WaitToReadAsync())
        {
            while (reader.TryRead(out var evt))
            {
                switch (evt)
                {
                    case AgentOutputTextEvent text:
                        Console.Write(text.Text);
                        break;

                    case AgentReasoningEvent reasoning:
                        Console.Write(reasoning.Text);
                        break;

                    case AgentLogEvent log:
                        Console.WriteLine(log.LogId);
                        break;

                    case AgentConversationCompletedEvent completed:
                        Console.WriteLine("Conversation completed");
                        break;

                    case AgentErrorEvent error:
                        Console.WriteLine(error.Message);
                        break;
                }
            }
        }
    });
}

Common Agent Events

AgentOutputTextEvent

Represents streamed text generated by the model.

if (evt is AgentOutputTextEvent text)
{
    Console.Write(text.Text);
}

Typical usage:

• Chat window updates
• Streaming assistant responses
• Building final response text

AgentReasoningEvent

Represents reasoning content produced by the model.

if (evt is AgentReasoningEvent reasoning)
{
    Console.Write(reasoning.Text);
}

Typical usage:

• Display reasoning process
• Debug agent planning
• Visualize internal workflow

AgentLogEvent

Represents diagnostic or execution status information.

if (evt is AgentLogEvent log)
{
    Console.WriteLine(log.LogId);
}

Typical usage:

• Diagnostics
• Telemetry
• Execution progress

AgentErrorEvent

Represents unexpected failures.

if (evt is AgentErrorEvent error)
{
    Console.WriteLine(error.Message);
}

Typical usage:

• Exception logging
• User notifications
• Failure handling

AgentConversationCompletedEvent

Represents completion of the current request.

if (evt is AgentConversationCompletedEvent completed)
{
    Console.WriteLine(completed.IsSuccess);
}

Typical usage:

• Enable UI input
• Hide loading indicators
• Persist conversation history

Properties:

Dashboard Generation

LightAgent can generate interactive dashboards using Apache ECharts.

https://echarts.apache.org/examples/en/index.html

Generated dashboard data is exposed through the built-in SystemFeatures service.

Retrieve the dashboard HTML template:

var html =
    SystemFeatures.GetInstance()
        .GetState("DASHBOARD_HTML");

Retrieve the latest ECharts option object:

var optionJson =
    SystemFeatures.GetInstance()
        .GetState("DASHBOARD_CONTENT");

A minimal WebView2 integration:

await webView.EnsureCoreWebView2Async();

var html =
    SystemFeatures.GetInstance()
        .GetState("DASHBOARD_HTML");

webView.NavigateToString(html);

Once navigation completes, render the latest dashboard:

webView.NavigationCompleted += async (_, __) =>
{
    var optionJson =
        SystemFeatures.GetInstance()
            .GetState("DASHBOARD_CONTENT");

    await webView.CoreWebView2.ExecuteScriptAsync(
        $"renderDashboard({optionJson});");
};

Optionally refresh periodically:

var timer =
    new System.Windows.Forms.Timer();

timer.Interval = 5000;

timer.Tick += async (_, __) =>
{
    var optionJson =
        SystemFeatures.GetInstance()
            .GetState("DASHBOARD_CONTENT");

    await webView.CoreWebView2.ExecuteScriptAsync(
        $"renderDashboard({optionJson});");
};

timer.Start();

The dashboard page exposes:

renderDashboard(option)

where option is a standard Apache ECharts option object generated by LightAgent.

Typical dashboard requests:

• Sales reports
• Project status dashboards
• Trend analysis
• Financial summaries
• Engineering metrics
• Pie, bar, line and scatter charts

Recommended Workflow

Create Agent
      │
      ▼
Register Tool Instances
      │
      ▼
Connect to LLM
      │
      ▼
Start Event Loop
      │
      ▼
Send User Request
      │
      ▼
Receive Events
      │
      ├── AgentOutputTextEvent
      ├── AgentReasoningEvent
      ├── AgentLogEvent
      ├── AgentErrorEvent
      └── AgentConversationCompletedEvent
      │
      ▼
Update UI / Business Logic

Integration Checklist

1. Create tool instances.
2. Register tool instances with AgentV1.
3. Configure OnInvoke if UI thread access is required.
4. Connect using AgentConnectCommand.
5. Start processing Events.
6. Send AgentUserRequestCommand.
7. Handle streamed output and reasoning.
8. Monitor logs and errors.
9. Wait for AgentConversationCompletedEvent.
10. Optionally cancel active requests using CancelCurrent().