Skip to content
Kindgi

Agent

View as Markdown

@kindgi/specs/agent.schema.json, schema version 1.6.0.

An agent definition. Declarative composition of instructions + capabilities + tools + memory retrieval + guardrails + conversation policy. The same definition is durable across restarts and versioned like flows — provenance references agents by (id, version).

  • id (string, required): Agent identifier. Convention: '<pack>.<agent>' (e.g. 'acme.citation-verifier').
  • version (string, required): Semver identifying this iteration of the agent. Different versions are different agents for audit purposes.
  • name (string, required): Human-readable display name.
  • description (string): Prose describing what the agent does. Shown in catalog + provenance metadata.
  • instructions (string or PromptRef, required): System-prompt rendered at the top of every turn. LiquidJS template — {{ variable }} substitution, {% if %} / {% for %} control flow, {{ value | filter }} filters. Every referenced variable must be a declared PromptParameter or a framework auto-var (today, now, agent., conversation., settings). Rendered with strictVariables — unresolved refs are hard errors. Or a prompt block by range ({ prompt, version }): its template and parameters are used instead, at the version pinned when the agent version is published.
  • settings (array of BlockRef): Settings blocks the agent reads, by range: tools read them as ToolContext.settings['<id>'], templates as settings["<id>"]. Pinned when the agent version is published.
  • modelSettings (BlockRef): A model-settings block by range: its temperature and maxOutputTokens go into the turn's model calls. Pinned when the agent version is published.
  • parameters (array of PromptParameter): Typed parameters supplied at invoke time. UI reads this to build a configuration form; runtime validates required parameters are provided before the model call.
  • capabilities (array of object, required): Capability declarations consumed by the router at turn time. One entry per resource kind the agent needs (e.g. LLM inference, embedding, gpu-compute). The router matches each entry by its kind (Capability.kind, default llm-inference) and its requirements; the array shape lets new kinds arrive without a schema break.
  • tools (array of ToolRef, required): Tools the agent may invoke, as { id, version } references; an empty array makes the agent chat-only. At run start each reference resolves to the highest registered version that satisfies its range; an unresolvable reference fails the turn. Schema-version 1.1.0 replaced the bare-string tool ids of 1.0.0, which defineAgent already rejected.
  • retrieval (array of RetrievalIntent, required): Fact-retrieval intents run before every turn to ground the model's context. Each sees only what the run may (its project and org, the user it acts for, its conversation and that conversation's end user, and tenant-wide facts); retrieved facts reach the model as a labelled data block, never as instructions. Schema-version 1.4.0 adds the same-user scope and memory; 1.5.0 adds memory.remember; 1.6.0 adds source: conversations and same-segment.
  • memory (object): How the agent uses what it retrieves.
    • instructionTypes (array of string): Fact types that are instructions for this agent: a retrieved fact of one of these types that a person verified goes into the system message under 'Policies (verified)'. Default: none, every retrieved fact is data.
    • remember (object): Lets the agent remember: its turns offer the built-in tool kindgi_remember (built-in tools are kindgi_<verb>; an agent can't list one in tools). The model picks the type, the text (up to 2,000 characters), an optional slot key and when it stops being true; the scope comes from here and the run. Every remembered fact is unverified, attributed to the agent version and the call that wrote it, and expires after keepDays unless a person verifies it. A person approves it before any read sees it when the scope is wider than one person (same-project, tenant) or the text reads like an instruction.
      • types (array of string, required): The fact types it may write.
      • scope ("same-user" | "same-conversation" | "same-project" | "tenant", required): Where its facts go: the conversation's end user (else the user the run acts for), the conversation, the run's project, or the tenant. Each but tenant includes the run's project.
      • keepDays (integer): Days an unverified fact is kept. Default 30.
  • guardrails (array of string, required): Guardrail ids the agent is subject to. Resolved at turn start against the guardrails bound for the run (an unknown id fails the turn); evaluated on each turn's final response, before it is stored.
  • preferredProvider (string): Preferred model provider id. Soft hint: the router prefers this provider when it satisfies the agent's capabilities and tenant policy, and otherwise routes normally.
  • preferredModel (string): Preferred model name within the selected provider. Soft hint, combined with preferredProvider.
  • conversationPolicy (ConversationPolicy)
  • budget (TurnBudget)
  • tags (array of string): Free-form filter tags for the catalog. Not consumed by execution.
  • output (AgentOutputSpec)
  • toolErrors (ToolErrorsSpec)

Definitions

Section titled “Definitions”

PromptRef

Section titled “PromptRef”
  • prompt (string, required)
  • version (string, required): A semver range.

BlockRef

Section titled “BlockRef”
  • id (string, required)
  • version (string, required): A semver range.

ToolErrorsSpec

Section titled “ToolErrorsSpec”

What the turn does when a tool call fails (schema-version 1.3.0): the failure goes back to the model as the call's result, so it can correct the call, up to maxRetries times per turn, for the kinds in retryOn. Default: one retry, for invalid-arguments and unknown-tool. A tenant tool-errors policy can lower it.

  • maxRetries (integer): Failed calls sent back to the model per turn. Default 1.
  • retryOn (array of "invalid-arguments" | "unknown-tool" | "tool-error"): Which failures are sent back: arguments that don't fit the input schema, a tool the agent doesn't have, a tool that ran and failed. Default invalid-arguments, unknown-tool.

AgentOutputSpec

Section titled “AgentOutputSpec”

A typed result (schema-version 1.2.0): the final answer must be JSON matching schema. An invalid answer is sent back to the model with the problems listed, up to maxRepairs times; then the turn fails with output-schema-violation.

  • schema (object, required): JSON Schema (draft 2020-12) the final answer must match.
  • name (string): A name for the output, shown to the model and in errors. Default output.
  • maxRepairs (integer): How many times the model is asked to repair an invalid answer. Default 1.

ToolRef

Section titled “ToolRef”

A typed tool reference: a tool id plus a semver range. Bare-string ids are not accepted — every reference names both.

  • id (string, required): Tool id (e.g. 'acme.verify-citation'). Must not be blank.
  • version (string, required): npm-style semver range: '1.2.3' pins exactly, '^1.2.3' allows compatible updates, '~1.2.3' patch updates only, '>=1.0.0 <2.0.0' an explicit range. Must not be blank; the range grammar is checked when the reference resolves at run start.

PromptParameter

Section titled “PromptParameter”
  • name (string, required): Variable name referenced in the instructions template. Must NOT collide with reserved auto-var namespaces: today, now, agent, conversation.
  • description (string): UI-facing description of what the caller should supply.
  • type ("string" | "number" | "boolean" | "date", required)
  • required (boolean): Default true. Set false to allow the parameter to be omitted.
  • default (object): Value used when the caller omits this parameter. Must match the declared type.

RetrievalIntent

Section titled “RetrievalIntent”
  • source ("facts" | "conversations"): What it reads: facts (the default), or messages of this agent's earlier conversations, quoted in the turn's <memory> block as earlier conversation, never as turns. Schema-version 1.6.0.
  • types (array of string): The fact types it retrieves: required for facts, absent for conversations.
  • roles (array of "user" | "agent"): For conversations: whose messages it recalls. Default ["user"], the people's own words. Adding "agent" recalls the agent's earlier answers too, which can carry its mistakes: they are quoted as unverified earlier answers, and publishing warns.
  • scope ("same-conversation" | "same-user" | "same-segment" | "same-project" | "tenant", required): What the intent selects within what the run may see. Facts: this conversation's; the run's end user's only (same-user: none when the run names no participantId); the run's project's (none without a project); or every fact of the type it may see (tenant). Conversations: this end user's other conversations with the agent (same-user: none when the run names no participantId); this conversation's messages older than the history window (same-conversation); conversations in the run's segment path (same-segment) or its project (same-project), whoever had them: those two quote other people's conversations. same-segment is for conversations only, tenant for facts only.
  • limit (integer): Cap on facts (or recalled messages) per turn. Default 10.
  • mode ("keyword" | "semantic" | "both"): With the user's message as the query: full-text (keyword), by meaning (semantic, which fails the turn with semantic-unavailable on a runtime without embeddings), or both fused by rank (without embeddings, the keyword half). Absent: the newest facts (or messages), no query.

ConversationPolicy

Section titled “ConversationPolicy”
  • historyLimit (integer)
  • hitlAfterTurns (integer)

TurnBudget

Section titled “TurnBudget”
  • maxSteps (integer): Maximum model→tool→model iterations per turn. Default 8.
  • maxCostUsd (number): Maximum USD spend per turn.
  • maxWallMs (integer): Wall-clock cap in ms. Default 120000.