LightAgent 0.10.1

LightAgent Integration Guide

This document explains how to integrate LightAgent, register tools, connect to an LLM service, process events, handle streaming responses, and work with the AgentV1 event-driven execution model.

---

AgentV1 Execution Model (Important)

Current AgentV1 uses a fully event-driven execution pipeline.

A user request may trigger multiple rounds of:

LLM Response
      │
      ├── Text Events
      ├── Reasoning Events
      └── Tool Plan Json
                    │
                    ▼
              Tool Execution
                    │
                    ▼
               Tool Result
                    │
                    ▼
              Next LLM Round

Tool execution begins immediately after a tool-plan JSON response is received.

AgentV1 no longer waits for the entire LLM response to finish before starting tool execution.

A request is considered finished only after:

AgentConversationCompletedEvent

is received.

---

Single Active Session Limitation

AgentV1 currently allows only one active user request at a time.

The following sequence is valid:

User Request
      │
      ▼
Conversation Running
      │
      ▼
AgentConversationCompletedEvent
      │
      ▼
Next User Request

The following sequence is invalid:

User Request A
      │
      ▼
Still Running
      │
      ▼
User Request B

If a new request is submitted while another session is still active, AgentV1 rejects the request and emits:

AgentErrorEvent

Applications should wait for:

AgentConversationCompletedEvent

before sending another:

AgentUserRequestCommand

or explicitly cancel the current session using:

agent.CancelCurrent();

---

Authoring Tools

LightAgent supports tools implemented as 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 returned values

Example:

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

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

---

Creating AgentV1

Current AgentV1 constructor:

var agent =
    new AgentV1(
        parent: null,
        isSubAgent: false,
        normalToolClasses,
        sysExtToolClasses,
        typeof(LlmClientV2),
        questionsAllowAnswered,
        parentWorkflows,
        subagentWorkflows,
        systemKnowledge,
        sandboxPath,
        tempFolder);

Parameter description:

Parameter	Description
parent	Parent agent when creating a sub-agent
isSubAgent	Indicates whether this instance is a sub-agent
normalToolClasses	Regular tool classes
sysExtToolClasses	System extension tool classes
llmConnectorType	LLM connector type
questionsAllowAnswered	Allowed question guidance
parentWorkflows	Parent agent workflows
subagentWorkflows	Sub-agent workflows
systemKnowledge	System knowledge
sandboxPath	Sandbox directory
tempFolder	Temporary directory

---

System Extension Tools

AgentV1 supports extension tool adapters through:

ISysToolsExtAdapter

When AgentV1 is created as the root agent:

extClass.SetAgentV1(this);

will be called automatically.

This allows extension tools to:

• Create sub-agents
• Emit logs
• Access agent services
• Coordinate workflows

---

Built-in Tools

AgentV1 automatically registers internal built-in tools.

No manual registration is required.

Examples include:

• Dashboard generation
• File generation
• Workflow helpers
• Other system functions

---

UI Thread Invocation

Some tools must execute on the UI thread.

Examples:

• WinForms controls
• WPF controls
• Clipboard access
• COM components
• Embedded browsers

AgentV1 provides:

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

When configured, tool execution is routed through this callback.

WinForms Example

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

    return action();
};

WPF Example

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

Without OnInvoke, tools execute on worker threads.

---

Connecting to the LLM

After creating the agent:

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

---

Waiting For Connection Result

while (await agent.Events.WaitToReadAsync())
{
    while (agent.Events.TryRead(out var evt))
    {
        if (evt is AgentConnectResultEvent conn)
        {
            if (conn.Success)
            {
                Console.WriteLine("Connected");
            }

            break;
        }
    }
}

---

Connection Parameters

Parameter	Description
Endpoint	LLM service endpoint
ApiKey	Authentication key
Model	Model name
ContextWindowSize	Conversation context size

---

Sending User Requests

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

Example with reasoning:

await agent.SendAsync(
    new AgentUserRequestCommand
    {
        UserOriginalInputText =
            "Design an enterprise architecture",

        ReasoningEffort =
            ReasoningEffort.high
    });

---

Cancelling Current Request

agent.CancelCurrent();

Cancellation affects:

• Active LLM request
• Tool execution
• Current planning pipeline
• Current session

After cancellation AgentV1 still emits:

AgentConversationCompletedEvent

with:

completed.IsCancelled == true

Applications should use this event for UI cleanup.

---

Processing Agent Events

Applications should continuously consume agent events.

Example:

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(
                            $"Completed:{completed.IsSuccess}");
                        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);
}

Important:

AgentOutputTextEvent is true streaming output.

Text chunks are emitted immediately as they are received from the underlying LLM stream.

Applications should append incoming text rather than replace existing content.

Typical usage:

• Chat streaming UI
• Live response rendering
• Building transcripts

---

AgentReasoningEvent

Represents reasoning content produced by the model.

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

Typical usage:

• Reasoning visualization
• Workflow inspection
• Debugging

---

AgentLogEvent

Represents execution progress information.

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

Typical usage:

• Progress tracking
• Tool execution status
• Diagnostics
• Telemetry

Properties:

Property	Description
LogId	Log identifier
Args	Parameters
Lang	UI language
IsSubAgent	Indicates log originated from sub-agent

---

AgentErrorEvent

Represents an unexpected failure.

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

Typical usage:

• Error logging
• User notification
• Recovery handling

---

AgentConversationCompletedEvent

Represents final completion of the current request.

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

Important:

This is the only event that indicates a request has fully completed.

Do not use:

• AgentOutputTextEvent
• AgentLogEvent
• AgentReasoningEvent

to determine completion.

Properties:

Property	Description
IsSuccess	Successful completion
IsCancelled	Request cancelled
Message	Error or completion message
ResponseText	Aggregated final response

Typical usage:

• Enable user input
• Hide loading indicators
• Persist history
• Start next request

---

Event-Driven Tool Execution

AgentV1 executes tools immediately after receiving a valid tool-plan JSON.

Conceptually:

User Request
      │
      ▼
LLM Streaming
      │
      ├── Text
      ├── Reasoning
      └── Tool Json
                  │
                  ▼
             Tool Execute
                  │
                  ▼
              Tool Result
                  │
                  ▼
              Next LLM

The agent waits until:

Current LLM Response Finished
AND
All Tool Executions Finished

before continuing with the next LLM round.

This avoids conversation-history race conditions and ensures deterministic conversation ordering.

---

Sub-Agent Support

AgentV1 supports internal sub-agents.

Create sub-agent:

var subAgent =
    await agent.CreateSubAgentAsync();

Sub-agents:

• Inherit parent conversation history
• Have their own sessions
• Can run independent workflows
• Can invoke tools
• Can return results to parent agents

Sub-agent logs are forwarded as:

AgentLogEvent

with:

log.IsSubAgent == true

UI implementations may display these logs differently.

---

Dashboard Generation

LightAgent can generate dashboards using Apache ECharts.

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

Retrieve dashboard page:

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

Retrieve current dashboard data:

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

Minimal WebView2 integration:

await webView.EnsureCoreWebView2Async();

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

webView.NavigateToString(html);

Render dashboard:

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

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

Refresh periodically:

var timer =
    new Timer();

timer.Interval = 5000;

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

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

timer.Start();

Available JavaScript API:

renderDashboard(option)

---

Recommended Workflow

Create Agent
      │
      ▼
Connect To LLM
      │
      ▼
Start Event Loop
      │
      ▼
Send User Request
      │
      ▼
Receive Events
      │
      ├── AgentOutputTextEvent
      ├── AgentReasoningEvent
      ├── AgentLogEvent
      ├── AgentErrorEvent
      └── AgentConversationCompletedEvent
      │
      ▼
Update UI
      │
      ▼
Wait For AgentConversationCompletedEvent
      │
      ▼
Send Next Request

---

Integration Checklist

1. Create AgentV1.
2. Configure tool adapters.
3. Configure OnInvoke when UI thread access is required.
4. Connect using AgentConnectCommand.
5. Wait for AgentConnectResultEvent.
6. Start consuming Events continuously.
7. Send AgentUserRequestCommand.
8. Append AgentOutputTextEvent to UI.
9. Display AgentReasoningEvent if desired.
10. Display AgentLogEvent progress.
11. Handle AgentErrorEvent.
12. Wait for AgentConversationCompletedEvent.
13. Send the next request only after completion.
14. Optionally cancel using CancelCurrent().