Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
127 changes: 127 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
# Agents.KT

_Source: [sdlc/agents/parts/project/project.md](sdlc/agents/parts/project/project.md)._

## Project

Agents.KT is the JVM runtime for an AI factory. A factory is a line of `Agent<IN, OUT>` stations: one input type, one output type, one job. The same line builds a software agent or an embodied agent. Software tools are compilers, repos, HTTP, and MCP. Body tools are sensors and actuators, attached the same way. The handoff for a partner agent is [docs/ai-factories.md](docs/ai-factories.md). The product site is [agents-kt.dev](https://agents-kt.dev/). The Maven coordinate is `ai.deep-code:agents-kt`. The license is MIT, held by Deep-Code.AI. The repository is [Deep-CodeAI/Agents.KT](https://github.com/Deep-CodeAI/Agents.KT).

The published version, the provider count, and the protocol status live in [release-metadata.yaml](release-metadata.yaml). [README.md](README.md) tracks that file. `ReleaseMetadataConsistencyTest` fails when a surface drifts. The [wiki](https://github.com/Deep-CodeAI/Agents.KT/wiki) is the learning path. When the wiki names an older published version, `release-metadata.yaml` and the README win.

| Path | Holds |
| --- | --- |
| `AGENTS.md` | This law, assembled from `sdlc/agents/parts/project/`. Edit the part, then copy the same text into the matching import block. |
| [docs/ai-factories.md](docs/ai-factories.md) | Partner handoff: one factory, software lines and embodied lines. |
| `README.md` | Product contract: security model, shipped surface, limitations, documentation index. |
| `docs/` | In-repo guides. Start with [docs/testing.md](docs/testing.md), [docs/source-layout.md](docs/source-layout.md), [docs/composition.md](docs/composition.md), [docs/threat-model.md](docs/threat-model.md). The README Documentation list names the rest. |
| [Wiki Home](https://github.com/Deep-CodeAI/Agents.KT/wiki) | Learning path, from Installation through Best Practices. |
| `release-metadata.yaml` | `currentRelease`, `developmentVersion`, `providers`, and `protocols`. |
| `src/main/kotlin/agents_engine/` | Core runtime. |
| `agents-kt-*` | Feature modules named in `settings.gradle.kts`. |

JDK 21 or newer. Kotlin version and the dependency line are the ones the README Current Release section states. The Gradle wrapper is the build. `./gradlew build` is the environment check in [Building From Source](https://github.com/Deep-CodeAI/Agents.KT/wiki/Building-From-Source).

<!-- END IMPORT: sdlc/agents/parts/project/project.md -->

<!-- BEGIN IMPORT: sdlc/agents/parts/project/legacy.md -->

_Source: [sdlc/agents/parts/project/legacy.md](sdlc/agents/parts/project/legacy.md)._

## Authority

Read these, in this order, before changing a claim or a boundary:

1. [release-metadata.yaml](release-metadata.yaml) for a version, a provider count, or a protocol status (`shipped`, `partial`, `experimental`, `spiked`).
2. [README.md](README.md) for the security model, the shipped list, and the known limitations.
3. [docs/threat-model.md](docs/threat-model.md) for which boundary the runtime enforces and which boundary the deployer owns.
4. The matching page under `docs/`.
5. The wiki page for the same topic, as the long-form narrative. [Best Practices](https://github.com/Deep-CodeAI/Agents.KT/wiki/Best-Practices) holds the DO and DON'T list.

### What the runtime owns

- Typed `Agent<IN, OUT>` contracts and the composition operators.
- Per-skill tool authorization and typed tool handles.
- MCP client and server surfaces on the same tool and skill shape.
- Permission manifests, declarative tool policies, and runtime audit correlation.
- JSONL audit export and the OTel, LangSmith, and Langfuse adapters through `ObservabilityBridge`.
- Local-first JVM execution. Ollama is the default local provider. Cloud providers are opt-in.

The README section "What Agents.KT Owns" is the full statement. [docs/permission-manifest.md](docs/permission-manifest.md) and [docs/cli.md](docs/cli.md) cover the manifest and the `agents-kt` CLI (`generate`, `inspect`, `verify`).

### What the deployer owns

The README section "What Agents.KT Does Not Own" is the full statement. The durable split:

| Boundary | Owner |
| --- | --- |
| Legal classification of a use case | Counsel and the compliance team. The runtime emits evidence. |
| Side effects inside a Kotlin tool lambda | The deployer. Layer 1 gates declared filesystem-path arguments. `processTool` adds the Layer 2 OS sandbox for subprocess tools. |
| Public MCP request rate | The gateway, plus `McpServer` auth and policy. |
| Prompt-injection classification | The deployer, through `onBeforeTurn`. |
| Vector storage, an eval product, hosted orchestration | The surrounding system. The runtime is the typed JVM boundary under those integrations. |

A change that widens one of these claims updates the README, the threat model, and `release-metadata.yaml` in the same edit.

<!-- END IMPORT: sdlc/agents/parts/project/legacy.md -->

<!-- BEGIN IMPORT: sdlc/agents/parts/project/new_wave.md -->

_Source: [sdlc/agents/parts/project/new_wave.md](sdlc/agents/parts/project/new_wave.md)._

## Working on the runtime

### Modules

`settings.gradle.kts` is the module list. The root project `agents-kt` holds `src/main/kotlin/agents_engine/`. Feature modules stay out of the core classpath:

| Module | Role |
| --- | --- |
| `agents-kt-ksp` | `@Generable` metadata. `kotlin-reflect` stays optional. |
| `agents-kt-no-reflect-test` | Consumer classpath that excludes `kotlin-reflect`. |
| `agents-kt-manifest` | Deterministic permission manifests. |
| `agents-kt-cli` | `generate`, `inspect`, `verify` outside Gradle. |
| `agents-kt-observability`, `agents-kt-otel`, `agents-kt-langsmith`, `agents-kt-langfuse` | Audit export and bridges. |
| `agents-kt-rag`, `agents-kt-rag-langchain4j`, `agents-kt-rag-spring-ai` | RAG seam. |
| `agents-kt-identity`, `agents-kt-dir` | AGNTCY Identity and DIR. |
| `agents-kt-detekt` | `ToolBodyForbiddenApis` and `ToolCapabilityExtractor`. |
| `agents-kt-whisper-jni` | Optional native Whisper backend. |

### Packages

The wiki [Architecture Overview](https://github.com/Deep-CodeAI/Agents.KT/wiki/Architecture-Overview) describes the original four packages: `core`, `composition`, `model`, `generation`. The tree also has `a2a`, `agui`, `agntcy`, `content`, `mcp`, `nlweb`, `runtime`, `sandbox`, `testing`, `x402`, and `internal`. Match the package that already owns the behavior.

[docs/source-layout.md](docs/source-layout.md) is the file rule. One top-level type per file. The file name is the type name. A sealed type stays with its direct subtypes. `./gradlew checkOneTypePerFile` enforces it. A real sealed-ADT exception goes in `config/one-type-per-file-allowlist.txt` with a `# sealed-ADT: keep` reason. The allowlist only shrinks.

### Agent shape

Follow the wiki [Best Practices](https://github.com/Deep-CodeAI/Agents.KT/wiki/Best-Practices) and [Agent and Type Contract](https://github.com/Deep-CodeAI/Agents.KT/wiki/Agent-and-Type-Contract).

- One agent, one job. A second job is a second agent composed with `then`, `/`, `forum`, `.loop`, `.branch`, or `handoff`.
- Skill and knowledge descriptions say when the model should pick them. Ambiguous skill routing throws `SkillRoutingException`. Predicate `skillSelection { }` stays the path when the input already decides.
- Tool allowlists take typed handles from `tool(...)`. String names stay for built-ins and MCP names discovered at runtime.
- An agentic agent sets `budget { maxTurns = N }`. A loop has an exit. `maxAgentDepth` bounds nested re-entry.
- Each agent instance is placed once. A second placement throws at construction. Reuse goes through a factory. [Single-Placement Rule](https://github.com/Deep-CodeAI/Agents.KT/wiki/Single-Placement-Rule).
- Agents pass data through typed input and output, or through `MemoryBank`. A public signature stays a concrete `IN` and `OUT`.
- Structured model output uses `@Generable` and `@Guide`. A long prompt lives in a classpath resource and loads with `loadResource`.
- Knowledge entries hold no secrets.
- Public API on the 0.x line stays additive. A behavior change is named in the CHANGELOG.

### Verification

[docs/testing.md](docs/testing.md) is the in-repo test guide. The wiki [Building From Source](https://github.com/Deep-CodeAI/Agents.KT/wiki/Building-From-Source) is the environment guide.

| Command | When |
| --- | --- |
| `./gradlew test` | Before a commit. Excludes `live-llm`, `live-mcp`, and `interactive`. |
| `./gradlew :test --tests "pkg.Class"` | One class. Scope the module. A root-wide `test --tests` also hits modules that lack that class. |
| `./gradlew detekt` | With the change. `detekt.yml` holds new code to the rules. The baseline only shrinks. |
| `./gradlew check` | Includes `checkOneTypePerFile`, `checkReadmeVersion`, and `checkDetektBaseline`. |
| `./gradlew integrationTest` | LLM client or agentic-loop work. Needs Ollama. |
| `./gradlew mcpIntegrationTest` | MCP client or server work. Needs `MCP_REDMINE_URL`. |
| `./gradlew pitest` | After a new behavior, to see mutants the tests leave alive. |

Unit tests inject a `ModelClient`. Live tests stay tagged. Linux sandbox tests (`bwrap`, `firejail`) need a Linux kernel and skip on macOS. CI runs them on Ubuntu.

A reported defect gets a regression test that fails on the current code before the fix. An existing assertion stays. When a contract change forces an edit, the test name and the contract that replaced it go in the task note.

<!-- END IMPORT: sdlc/agents/parts/project/new_wave.md -->
68 changes: 68 additions & 0 deletions docs/ai-factories.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# AI factories on Agents.KT

Handoff for a partner agent. This file is the project picture. Shipped behavior lives in [README.md](../README.md) and [release-metadata.yaml](../release-metadata.yaml). When this file and those two disagree about a version, a provider, or a protocol, those two win.

## Aim

Agents.KT is the runtime for building an AI factory. A factory is a repeatable line: a typed job goes in, bounded stations do one job each, and a typed result comes out. The same line shape builds two kinds of agent.

| Factory | The job | The tools | The result |
| --- | --- | --- | --- |
| Software | A spec, a ticket, a file, or a user turn | Compilers, repos, HTTP, MCP servers, other agents | A patch, a document, a decision, or a tool result |
| Embodied | A mission, a pose, or a sensor frame | Cameras, drivers, grippers, navigation, motion primitives | A command a controller can run, or a stop |

One runtime serves both. The body is a set of tools and typed messages. It is a second product of the same factory, and it is a second framework.

## What a station is

A station is `Agent<IN, OUT>`: one input type, one output type, one job. A skill on that station allowlists the tools that station may call. The compiler checks that one station's output is the next station's input.

A line is composition:

| Line | Code | Use |
| --- | --- | --- |
| Sequence | `a then b` | Software: parse, then generate, then review. Embodied: perceive, then plan, then act. |
| Same input, concurrent stations | `a / b` | Two reviewers, or two sensors, on one workpiece. |
| Council | `forum { }` | Several stations, one captain, one verdict. |
| Repeat until done | `.loop { }` | Refine a patch, or replan while the goal is open. The loop has an exit. |
| Route on type | `.branch { }` | Send a sealed result to the station that owns that case, including a stop. |
| Hand off | `triage handoff { }` | Pass the typed input to a specialist. The specialist does not receive the source history. |

Each station instance sits on one line. A second use is a new instance from a factory function. Stations pass work through typed input and output, or through `MemoryBank`.

## What the factory freezes before a shift

Before a line runs, the factory can show the boundary:

- The permission manifest lists agents, skills, tools, policies, providers, and budgets, and hashes that graph.
- A budget caps turns, tool calls, time, and tokens. `maxAgentDepth` caps nested calls.
- A tool policy records filesystem, network, and environment scope. Declared filesystem paths are gated in the JVM. Subprocess tools can run in an OS sandbox.
- Runtime events carry the manifest hash. A JSONL log and a tamper-evident tool ledger record what the line did.
- A human gate is an interceptor or a HITL interrupt. For an embodied line, a stop is a station outcome, not a sentence in a prompt.

The deployer still owns legal classification, rate limits on public MCP, prompt-injection detection, and any safety controller under the actuators. The runtime emits evidence and enforces the boundaries declared in code. [docs/threat-model.md](threat-model.md) is the table of which layer enforces which boundary.

## Software factory, as it stands

This repository is that factory's runtime. Kotlin on JDK 21+. Maven coordinate `ai.deep-code:agents-kt`. License MIT, Deep-Code.AI. Product site [agents-kt.dev](https://agents-kt.dev/). Source [github.com/Deep-CodeAI/Agents.KT](https://github.com/Deep-CodeAI/Agents.KT).

A software line is a library inside a JVM service, an MCP server, an A2A peer, or a same-JVM swarm. Local models start with Ollama. Cloud providers are opt-in. The provider count and the protocol status (`mcp`, `a2a`, `agui`, `nlweb`, `x402`, `agntcy`) are the fields in `release-metadata.yaml`.

Core code is `src/main/kotlin/agents_engine/`. Feature modules are the `agents-kt-*` projects in `settings.gradle.kts`. Factory work goes in `src/` and those modules.

## Embodied factory, as a target

The embodied line uses the same station, the same allowlist, and the same manifest. A camera frame is an input type. A motion primitive is a tool. A pose is an output type. The partner agent designs that line in types and tools.

This repository has no robot, ROS, or actuator package. Do not treat a body driver as shipped code. Attach a body by giving the act station tools whose arguments are commands the existing controller already accepts, with a budget, a policy, and a branch whose stop case runs before motion.

## What the partner agent does with this

1. Read [README.md](../README.md) for the security model and the shipped list.
2. Read `currentRelease`, `providers`, and `protocols` in [release-metadata.yaml](../release-metadata.yaml) before stating a version.
3. Design a line as `Agent<IN, OUT>` stations. One station, one job.
4. Choose software tools or body tools. Keep both behind the skill allowlist.
5. Put a stop, a human gate, and a budget on any line that can move code into production or move a body.
6. Verify runtime changes with `./gradlew test`. The in-repo guide is [docs/testing.md](testing.md). The learning path is the [wiki](https://github.com/Deep-CodeAI/Agents.KT/wiki).

Contributor rules for editing this repository are in [AGENTS.md](../AGENTS.md).
34 changes: 34 additions & 0 deletions sdlc/agents/parts/project/legacy.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
## Authority

Read these, in this order, before changing a claim or a boundary:

1. [release-metadata.yaml](release-metadata.yaml) for a version, a provider count, or a protocol status (`shipped`, `partial`, `experimental`, `spiked`).
2. [README.md](README.md) for the security model, the shipped list, and the known limitations.
3. [docs/threat-model.md](docs/threat-model.md) for which boundary the runtime enforces and which boundary the deployer owns.
4. The matching page under `docs/`.
5. The wiki page for the same topic, as the long-form narrative. [Best Practices](https://github.com/Deep-CodeAI/Agents.KT/wiki/Best-Practices) holds the DO and DON'T list.

### What the runtime owns

- Typed `Agent<IN, OUT>` contracts and the composition operators.
- Per-skill tool authorization and typed tool handles.
- MCP client and server surfaces on the same tool and skill shape.
- Permission manifests, declarative tool policies, and runtime audit correlation.
- JSONL audit export and the OTel, LangSmith, and Langfuse adapters through `ObservabilityBridge`.
- Local-first JVM execution. Ollama is the default local provider. Cloud providers are opt-in.

The README section "What Agents.KT Owns" is the full statement. [docs/permission-manifest.md](docs/permission-manifest.md) and [docs/cli.md](docs/cli.md) cover the manifest and the `agents-kt` CLI (`generate`, `inspect`, `verify`).

### What the deployer owns

The README section "What Agents.KT Does Not Own" is the full statement. The durable split:

| Boundary | Owner |
| --- | --- |
| Legal classification of a use case | Counsel and the compliance team. The runtime emits evidence. |
| Side effects inside a Kotlin tool lambda | The deployer. Layer 1 gates declared filesystem-path arguments. `processTool` adds the Layer 2 OS sandbox for subprocess tools. |
| Public MCP request rate | The gateway, plus `McpServer` auth and policy. |
| Prompt-injection classification | The deployer, through `onBeforeTurn`. |
| Vector storage, an eval product, hosted orchestration | The surrounding system. The runtime is the typed JVM boundary under those integrations. |

A change that widens one of these claims updates the README, the threat model, and `release-metadata.yaml` in the same edit.
Loading
Loading