Agents package

Troolio.Agents models agent definitions and runs as event-sourced actors. It provides framework contracts and actors; it does not choose a model provider, tool runtime, credential store, or execution policy for the host.

Definition actor

IAgentActor accepts RegisterAgent, UpdateAgentDefinition, SetAgentEnabled, and run lifecycle registration commands. Its events include AgentRegistered, AgentDefinitionUpdated, AgentEnabledChanged, AgentRunStarted, and AgentRunCompleted. GetAgentDefinition and GetAgentMetrics query the projected actor state. The definition records the agent's identity and configuration; the host decides who may modify it.

Run actor

IRunActor accepts RunAgentDefinition, StartRun, ResumeRun, CancelRun, RecordAgentResponse, and RecordAgentFailure. The run event stream records start, resume, completion, failure, cancellation, and individual agent outcomes. GetRunState returns a RunSnapshot; GetRunStatus returns the current status. A run ID is the durable correlation key across external execution and actor updates.

Install with dotnet add package Troolio.Agents --version 10.0.8, then register the actor assembly in the Orleans host and configure a compatible store. Build an application service around these contracts for scheduling, tool permissions, model calls, and idempotent delivery. Keep credentials and sensitive prompts out of public event payloads unless your retention and erasure design permits them.

Example: Create an agent and a run

These are the typed messages accepted by the definition and run actors. The host chooses actor IDs, persistence, authorization, and the external model execution service.

public static RegisterAgent DefineAgent(Metadata headers) =>
    new(headers, "Summarizer", "Assistant", "Summarize the input", "model-id");

public static StartRun BeginRun(Metadata headers) =>
    new(headers, "summary-1", "Summarize this", [
        new RunAgentDefinition("agent-1", "Summarizer", "Assistant",
            "Summarize the input", "model-id")]);