Packs and primitives

This page explains what a pack holds and how Kindgi finds it, so you know where each part of your app's Kindgi code goes.

A pack is everything Kindgi runs for your app, defined in your app's own language. It has an id, such as acme-desk, and a version. It holds four kinds of primitives: tools, agents, flows and guardrails. Each has its own id under the pack's, such as acme-desk.triage.

Tools: your code

A tool is a function with a typed input and output. Kindgi checks both on every call, so an agent can't hand your code something malformed.

• Code tools are your functions (TypeScript defineTool, Python @tool). They run in the pack service, so they import your app's modules and reach what your app reaches.
• HTTP tools are one HTTP request, declared with no handler (http_tool in Python, an http spec in TypeScript). The runtime makes the request, resolving its secret for each call.
• A tool declares whether it changes anything. One declared read-only (mutating: false) runs in a dry run, and approval rules can skip it.

Agents: a model with instructions and tools

An agent is data: its instructions, the tools it may call, the guardrails on its answers, a budget and what it needs from a model. The budget caps its steps, cost and time. What it needs from a model can be tool use or typed output.

An agent can answer with a typed result, a schema Kindgi checks. If the model's answer doesn't fit, Kindgi asks the model to repair it once. If it still doesn't fit, the turn fails instead of passing on bad data.

Flows: your process

A flow is your process as data: steps and the edges between them.

• Steps run a tool or an agent, with their input mapped from the run's input or earlier steps' outputs.
• Edges can carry conditions (when), so a flow branches: an agent triages, and only an urgent message reaches the step that writes a ticket.
• Flows can join branches, loop over items, and fan out to run steps in parallel.

Guardrails: checks on what an agent does

A guardrail is a check over an agent's turn: its answer, its tool calls, their results. It passes or fails, with a reason. A failed check can halt the turn or be recorded as a violation.

How a pack is found

Kindgi finds primitives by folder: tools/, agents/, flows/ and guardrails/ (under kindgi/ when the pack lives inside an app). The indexer reads them into the pack's index.json, the same file for a TypeScript or a Python pack. The runtime registers what it lists. kindgi dev indexes the pack again on every save, and kindgi build puts the index in the image.

Each tool, guardrail, agent and flow version is defined in one file. A second file with the same id and version is refused, with both files named. kindgi dev still loads the rest of the pack:

✗ indexer: tools/greet/index.ts [manifest-validation-failed] tools/greet/index.ts: duplicate tool 'acme-ops.greet' version 0.1.0 (also defined in tools/greet-copy/index.ts)

Two versions of one id, in two files, are fine: see Agent and tool versions.

Every field is in the reference: Packages and JSON Schemas.