Interface: AgentDefinition

Properties

agents?

optional agents: Record<string, AgentDefinition>;

Sub-agents, exposed as agent-<key> tools on this agent.

auth?

optional auth: "on-behalf-of-user";

Run this agent on behalf of the signed-in user: the model call, plugin tools, hand-rolled tools, and sub-agents all use the user's credentials. Overrides agents({ auth }) for this agent. Omit for the default, where the model and hand-rolled tools run as the app service principal and plugin tools run as the user.

baseSystemPrompt?

optional baseSystemPrompt: BaseSystemPromptOption;

Override the plugin's baseSystemPrompt for this agent only.

default?

optional default: boolean;

Marks this agent as the default one chosen when a client doesn't name an agent. Mirrors markdown frontmatter default: true. When several agents set it, a code (discovered) agent wins over a markdown one, then the lowest id; an explicit agents({ defaultAgent }) always overrides it. Defaults to false.

ephemeral?

optional ephemeral: boolean;

When true, the thread used for a chat request against this agent is deleted from ThreadStore after the stream completes (success or failure). Use for stateless one-shot agents — e.g. autocomplete, where each request is independent and retaining history would both poison future calls and accumulate unbounded state in the default InMemoryThreadStore. Defaults to false.

generationParams?

optional generationParams: GenerationParams;

Optional generation parameters (temperature, top_p, stop, frequency_penalty, presence_penalty) forwarded to the OpenAI-compatible serving request body. Only set keys are sent. Applied only when AppKit builds the adapter itself (string or omitted model); when you pass a pre-built AgentAdapter, configure generation params on it directly.

instructions

instructions: string;

System prompt body. For markdown-loaded agents this is the file body.

maxSteps?

optional maxSteps: number;

maxTokens?

optional maxTokens: number;

model?

optional model: 
  | string
  | AgentAdapter
| Promise<AgentAdapter>;

Model adapter (or endpoint-name string sugar for DatabricksAdapter.fromServingEndpoint({ endpointName })). Optional — falls back to the plugin's defaultModel.

name?

optional name: string;

Stable identifier for the agent. Optional and informational — when the definition is registered via agents: { foo: def } (code) or lives at server/agents/<id>/agent.md (markdown), the registry key always wins and name is ignored. The agent will be reachable as foo (or <id>) regardless of what this field contains.

Set name when:

• Running standalone via runAgent({ agent: def }), where there is no enclosing key. The runtime uses it for the agent's slot in error messages and OTel spans.
• Building a definition that may be passed to either form and you want a consistent fallback label.

Setting name to a value that differs from the registry key is harmless but confusing — prefer keeping them aligned or omitting name entirely.

skills?

optional skills: string[];

Names of global skills (shared skills/ pool or catalog volume) to make visible to this agent. Per-agent skills under <id>/skills/ are always visible and need not be listed. Ignored when the plugin's autoInheritSkills makes every global skill visible.

tools?

optional tools: 
  | AgentTools
  | AgentToolsFn;

Per-agent tool record. Key is the LLM-visible tool-call name.

Accepts either a plain record (for agents that only use inline tools) or a function (plugins) => Record<string, AgentTool> that receives the typed Plugins map and returns a tool record (for agents that pull tools from registered plugins).

The function is invoked once at agent setup; the result is cached. Don't put per-request logic in there.