Fluent builder for an AgentDef, obtained from AgentManager.newAgentDefBuilder(). Each setter returns the builder so calls can be chained; build() then assembles and returns a new AgentDef without saving it. Used by apps that supply an agent definition programmatically through agentDefProviders, and by any code assembling a definition before handing it to saveAgentDef.

Group: Builders

---

Methods

attributes(Map<String,Serializable> attributes) · name(String name) · title(String title) · instructions(String instructions) · timers(List<AgentDefTimer> timers) · events(List<AgentDefEventHandler> events) · functions(List<String> functions) · groups(List<String> groups) · allowedOverrides(List<String> allowedOverrides) · build()

attributes(Map<String,Serializable> attributes)

Returns: AgentDefBuilder

Sets the arbitrary name/value pairs carried on the definition, for values an app wants to keep with the agent that none of the other properties covers. Replaces any attributes already set on this builder.

name(String name)

Returns: AgentDefBuilder

Sets the definition's portable identifier, which is how an agent, a saveAgentDef call or an agentDefProviders entry refers to it. For a definition parsed from XML this is the file name, including the .xml suffix. Required: build throws if it was never set.

title(String title)

Returns: AgentDefBuilder

Sets the display title shown to users choosing or managing this agent. Optional, and purely cosmetic - code always refers to the definition by its name.

instructions(String instructions)

Returns: AgentDefBuilder

Sets the instructions used as the agent's system prompt, ie what the agent is for and how it should behave. The text may be templated with kcode, which is evaluated when the agent runs.

timers(List<AgentDefTimer> timers)

Returns: AgentDefBuilder

Sets the schedules on which the agent runs unprompted, replacing any already set on this builder. A definition with no timers only ever runs in response to an event or a user.

events(List<AgentDefEventHandler> events)

Returns: AgentDefBuilder

Sets the event handlers that decide which events wake the agent and how those events are buffered before it runs, replacing any already set on this builder. An account may add to these, replace one by name, or disable one, without taking a copy of the definition - see AgentManager.saveAccountEventHandlers.

functions(List<String> functions)

Returns: AgentDefBuilder

Sets the names of the functions the agent is allowed to call, replacing any already set on this builder. This is the agent's whole tool surface: a function not named here cannot be called.

groups(List<String> groups)

Returns: AgentDefBuilder

Sets the names of the user groups whose members may have this agent, replacing any already set on this builder. Membership of any one of the named groups is enough.

allowedOverrides(List<String> allowedOverrides)

Returns: AgentDefBuilder

Sets which properties of the definition a tenant is allowed to change, replacing any already set on this builder. Each entry is written as property=mode1,mode2 where property names a property of AgentDef and each mode is one of add, edit or remove.

build()

Returns: AgentDef

Create the agent definition. Builds the definition and returns it; it is not saved. An app that supplies a definition through agentDefProviders wants exactly this: an instance, used directly, with nothing written to the tenant. Call saveAgentDef as a separate step if the definition is one a tenant authored and should persist.