# Packs and primitives

> Tools, agents, flows and guardrails — what each one is, and how a pack holds them.

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:

```text
✗ 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](https://docs.kindgi.com/v0.1.9/guides/agents/agent-and-tool-versions.md).

Every field is in the reference: [Packages](https://docs.kindgi.com/v0.1.9/reference/packages.md) and [JSON Schemas](https://docs.kindgi.com/v0.1.9/reference/schemas.md).