Roadmap

Roadmap

Development plan for Agents.KT, organized into four phases through Q4 2026.

---

Phase 1 -- Core DSL (Current)

The foundation: typed agents, skills, knowledge, all six composition operators, guided generation, and the agentic execution loop.

• Agent<IN, OUT> with SRP enforcement
• Agent.prompt -- base context string for the LLM
• Skills-only execution -- all agents run through skills { implementedBy { } }
• Skill.description (mandatory) -- sells the skill to the LLM alongside its type signature
• Skill.knowledge("key", "description") { } -- named lazy context providers; loadFile() inside lambdas
• Skill.toLlmDescription() -- auto-generated markdown (name, types, description, knowledge index); llmDescription("...") override
• Skill.toLlmContext() -- full context: description markdown + all knowledge content
• Skill.knowledgeTools() / KnowledgeTool(name, description, call) -- tools model with lazy per-entry loading
• then -- sequential pipeline with composed execution (no runtime casts)
• / -- parallel fan-out with coroutine concurrency
• * -- forum (multi-agent discussion) with concurrent participants, captain, and onMentionEmitted debate tracking
• Single-placement enforcement across all structure types
• .loop {} -- iterative execution with (OUT) -> IN? feedback block
• .branch {} -- conditional routing on sealed types, composable with then
• @Generable("desc") / @Guide / @LlmDescription -- runtime reflection: toLlmDescription(), jsonSchema(), promptFragment(), fromLlmOutput<T>(), PartiallyGenerated<T>
• model { } -- Ollama backend; host, port, temperature; injectable ModelClient for tests
• Agentic execution loop -- multi-turn tool calling with budget controls (maxTurns) + onToolUse observability hook
• Skill selection -- predicate-based skillSelection {} + automatic LLM routing when multiple skills match
• Agent memory -- MemoryBank, memory_read/memory_write/memory_search auto-injected tools
• >> -- security/education wrap

---

Phase 2 -- Runtime + Distribution (Q2 2026)

MCP integration, permissions, compile-time annotation processing, native distribution, and session management.

Priority

• MCP client -- mcp { server(name) { url=/command=/host+port= } } agent DSL with HTTP / stdio / TCP transports, McpAuth.Bearer, tool name namespacing (server.tool), in-process mock servers for hermetic tests. (Note: we deliberately did not introduce a Tool<IN, OUT> hierarchy with an McpTool<IN, OUT> subclass — MCP-discovered tools are minted as standard ToolDefs, keeping local-tool code untouched.)
• MCP server -- McpServer.from(agent) { expose("skill") }.start() exposes agent skills as MCP tools; inputSchema generated from @Generable IN types via reflection
• MCP 2025-03-26 conformance -- ping, explicit capabilities.tools.listChanged, protocolVersion negotiation, cursor/nextCursor, Content-Type/415, 405 with Allow: POST, Mcp-Session-Id, plain-prose tool descriptions
• McpRunner -- McpRunner.serve(agent, args, configure) picocli-style one-line main for runnable agent JARs; --port, --expose, -h, -V; JVM shutdown hook + graceful stop
• grants { tools(...) } -- Layer 2 permissions use actual Tool<*,*> references
• Permission model: 3 states -- Granted (auto-runs), Confirmed (user approval), Absent (unavailable)
• KSP annotation processor -- compile-time @Generable; constrained decoding (Ollama) + guided JSON mode (Anthropic/OpenAI)
• Native CLI binary (GraalVM -- no JRE required); brew, npm, pip, curl, apt
• jlink minimal JRE bundle for runtime (~35MB)

Secondary

• Session model -- multi-turn AgentSession, automatic compaction (SUMMARIZE, SLIDING_WINDOW, CUSTOM)
• Reactive context hooks -- beforeInference, afterToolCall, onBudgetThreshold
• .spawn {} -- independent sub-agent lifecycle, AgentHandle<OUT>, parent-managed join
• Pipeline observability -- observe {} event handler, Flow<PipelineEvent> for streaming UIs
• Serialization -- agent.json, A2A AgentCard
• JAR bundles and folder-based assembly
• Gradle plugin (auto-wires application { mainClass } for McpRunner-based agents)
• Incoming auth on McpServer (Bearer / OAuth validation on requests)
• OAuth 2.1 client (PKCE flow, token refresh) for McpClient
• Origin header validation + MCP-Protocol-Version response header (deferred from conformance audit)
• Custom tool deserializers -- per-tool / per-server lambdas to map raw MCP content[] to typed Kotlin values

---

Phase 3 -- Production (Q3 2026)

Full production readiness: advanced structure DSL, testing framework, protocol support, and observability.

• Layer 2: Full Structure DSL with delegates, grants, authority, routing, escalation
• All 37 compile-time validations enforced by Gradle plugin
• AgentUnit testing framework -- unit, semantic (LLM-as-judge), Skill Coverage metrics
• A2A protocol support (server + client)
• File-based knowledge: skill.md, reference, examples, checklist + RAG pipeline
• Production observability: OpenTelemetry traces
• Team DSL -- swarm coordination (if isolated execution available)

---

Phase 4 -- Ecosystem (Q4 2026)

Developer experience, marketplace, and tooling.

• Knowledge packs -- battle-tested prompt libraries for common domains
• Agent generation from natural language (NL -> Kotlin DSL)
• Skillify -- extract reusable skills from session transcripts
• Visual structure editor, UML bidirectional conversion
• Knowledge marketplace

---

Timeline Overview

2026
  Q1  ████████████████  Phase 1: Core DSL (current)
  Q2  ████████████████  Phase 2: Runtime + Distribution
  Q3  ████████████████  Phase 3: Production
  Q4  ████████████████  Phase 4: Ecosystem

---

What You Can Build Today (Phase 1)

Capability	Status
Typed agents with Agent<IN, OUT>	Available
Pure Kotlin skills (implementedBy)	Available
LLM-driven skills (tools())	Available
Knowledge (lazy and eager)	Available
Sequential pipelines (then)	Available
Parallel fan-out (/)	Available
Forum deliberation (*) -- concurrent participants, captain verdict, onMentionEmitted	Available
Iterative loops (.loop {})	Available
Conditional branching (.branch {})	Available
Ollama integration	Available
Mock testing with ModelClient	Available
Guided generation (@Generable, @Guide)	Available
Lenient JSON parsing (fromLlmOutput)	Available
Partial generation (PartiallyGenerated)	Available
Agent memory (MemoryBank)	Available
Skill selection (predicate + LLM)	Available
Budget controls (maxTurns)	Available
Observability hooks	Available
Tool error types (ToolError)	Available
MCP client -- mcp { server() } agent DSL (HTTP / stdio / TCP, Bearer auth, namespacing)	Available
MCP server -- McpServer.from(agent) { expose() }, @Generable schema gen	Available
McpRunner -- picocli-style one-liner main for standalone agent JARs	Available

What is Coming Next (Phase 2)

Capability	ETA
Incoming auth on McpServer (Bearer / OAuth validation)	Q2 2026
OAuth 2.1 client for McpClient (PKCE, refresh)	Q2 2026
Permission model	Q2 2026
KSP compile-time generation	Q2 2026
Native CLI (no JRE)	Q2 2026
Gradle plugin (auto-wires McpRunner mainClass)	Q2 2026
Session management	Q2 2026
Pipeline observability	Q2 2026

---

See also: Architecture Overview | API Quick Reference | Installation and Setup