Table of Contents

Class AgentDefinition

Namespace
LMKit.Agents
Assembly
LM-Kit.NET.dll

A portable, serializable agent: a reusable bundle of behavior (prompt, skill, tools, memory, model, limits) that any host can run. The same definition runs in-process through WithDefinition(AgentDefinition, Func<string, ITool>, Func<string, AgentSkill>, AgentMemory, Func<IReadOnlyList<string>, IKnowledgeRetriever>) and on an LM-Kit server, where requests select it by name.

public sealed class AgentDefinition
Inheritance
AgentDefinition
Inherited Members

Examples

var definition = new AgentDefinition
{
    Name = "support",
    Description = "Answers questions about orders and refunds.",
    System = "You are the support assistant of Contoso.",
    Tools = new List<string> { "calc_arithmetic" },
    MaxToolCalls = 4,
};

File.WriteAllText("support.agent.json", definition.ToJson());

var agent = Agent.CreateBuilder(model)
    .WithDefinition(AgentDefinition.FromJson(File.ReadAllText("support.agent.json")))
    .Build();

Remarks

A definition holds no live object, secret or delegate: only names and settings, so it can be stored, exported and moved between hosts as JSON (ToJson(), FromJson(string)). The host binds the names to its own tools, skills and memory.

The definition supplies defaults; anything a request states explicitly wins (ApplyTo(AgentInvocation)), so a definition saves callers from restating the same setup, and narrows nothing: permissions belong to the host's policies.

Fields

AgentMemoryScope

Memory scope value: one memory shared by every end user of the same tenant. A host never shares it across tenants.

CallerMemoryScope

Memory scope value: each caller (each end user the host names, else each tenant) keeps its own memory. The default.

CurrentSchemaVersion

The schema version this release writes and the newest it reads.

HandoffContract

The contract an agent that may hand over (Handoff) carries in its system prompt: when a person must take over, it says so through the hand-off tool instead of improvising.

ToolContinuityContract

The sentence every tool-bearing definition adds to its system text, so each agent treats tool results already in the conversation alike without having to say it itself.

UserQuestionsContract

The contract an agent that may ask the user (UserQuestions) carries in its system prompt: a missing detail is asked for, never guessed.

Properties

DefaultMemoryId

Gets the memory id a request that names none remembers under: agent- and the agent's name, as a safe identifier.

Description

Gets or sets one line shown in pickers: what this agent is for.

Greeting

Gets or sets a fixed first assistant message a fresh conversation opens with. Presentation only.

Handoff

Gets or sets whether the agent may hand a conversation over to a person, and where the host delivers it; null for no hand-off. In a run that stops for people, the hand-off ends the run HandedOff.

HasOutputSchema

Gets whether OutputSchema holds a schema (a JSON object).

Knowledge

Gets or sets the knowledge sources the agent grounds its answers in, and how; null for none. Resolved by the host under the caller's own rights.

MaxToolCalls

Gets or sets the most tool calls one turn may spend before the model must answer; 0 leaves the host's default.

Memory

Gets or sets whether the agent remembers facts across conversations. A request that names no memory id gets the agent's memory (DefaultMemoryId), scoped by MemoryScope.

MemoryScope

Gets or sets who shares the agent's memory: CallerMemoryScope (empty means the same) or AgentMemoryScope.

MemoryStore

Gets or sets the memory store (policy bundle) the agent's memory lives under; empty for the host's default.

Model

Gets or sets the catalog id of the model the agent answers with; empty leaves the choice to the request or the host.

Name

Gets or sets the unique name the definition is selected by.

OutputSchema

Gets or sets the JSON Schema every answer of the agent conforms to (a JSON object), or null for free text. The host enforces it while decoding, so a nonconforming answer cannot be produced: the shape an integration reads, such as a reply with a status, or a list of proposed actions. A request that states its own response format keeps it.

ProposalReport

Gets or sets where the answer reports the changes the agent proposed, or null for none. With SimulateTools on, the answer's actions and status are then set from the changes the run recorded, so they always say what it did (ProposalReport).

Reasoning

Gets or sets the thinking level: none, low, medium, high, or empty for the model's default.

RequireApproval

Gets or sets which of the agent's tool calls need a person's approval before they run, in the textual rule form of RequireApprovalFor(IEnumerable<string>): a tool name or pattern, category:<name> or risk:<level>. A call that needs approval pauses a run that defers approvals; elsewhere it is refused unless a handler approves it. Approval rules only ever tighten: a request cannot remove them. Null or empty adds none.

Revision

Gets or sets the published revision this definition is, as a host that keeps revisions numbers them (1, 2, ...); 0 for a definition that was never published. A revision is immutable: a change is a new revision, never an edit of an old one. Not part of the agent's behavior, so HasSameConfiguration(AgentDefinition) ignores it.

SchemaVersion

Gets or sets the schema version of this definition. Written as CurrentSchemaVersion.

SimulateTools

Gets or sets whether the agent's tools that write are simulated for every caller: a tool that only reads runs, a tool that writes, sends or cannot be undone returns a simulated result and never executes (Guard(ITool)). The agent then proposes actions without taking them. A request cannot turn it off.

Skill

Gets or sets the skill pinned for every request, unless the request pins its own.

System

Gets or sets the system prompt the agent brings; a request's own system text follows it.

Tools

Gets or sets the names of the tools the agent brings, unless the request names its own. Null brings none.

UserQuestions

Gets or sets whether the agent may ask the user a question it cannot go on without: in a run, the question stops the run AwaitingInput until it is answered.

Methods

ApplyTo(AgentInvocation)

Fills invocation with this definition's defaults wherever the request stayed silent: the ONE resolution every host runs, so a definition behaves alike in-process and on a server.

Clone()

A copy of this definition (its tool list included): the one way to carry a definition forward with a field changed, so a field added later can never be dropped by a copy that forgot it.

FromJson(string)

Reads a definition from its JSON form. Missing fields take their defaults; a definition written by a newer release (a higher schema version) is refused rather than misread.

HasSameConfiguration(AgentDefinition)

Whether other configures the same agent as this definition: every field equal in their canonical JSON form, the Revision aside. A host uses it to tell a real change (a new revision) from a save that changed nothing.

IsSharedMemoryScope(string)

True when scope asks for one memory shared by every end user of a tenant.

SafeIdentifier(string)

The identifier form of value that memory ids and store names use: letters, digits, dash and underscore only, at most 64 characters. Null when nothing safe remains.

ToJson()

The canonical JSON form of this definition (snake_case properties, indented), the same shape an LM-Kit server stores and exports.

ValidateOutputSchema()

Why OutputSchema cannot constrain an answer, or null when it can (or when the definition has none).

ValidateRequireApproval()

Why RequireApproval cannot be applied, or null when it can (or when the definition has no approval rules).

Share