Skip to main content

Core concepts

Aigentic has a small set of ideas. Once you know how they fit together, the rest of the docs are details.

InputI

A String, a data class, attachments, or nothing at all.

agent<I, O>
Task
What the agent should do, plus instructions
Model
Any provider: OpenAI, Gemini, VertexAI, Ollama
Tools
Your Kotlin code the model can call

The model calls tools until it can finish the task

run.outcome
  • Finished(response: O)Done, with your typed result
  • Stuck(reason)The model couldn't finish
  • Fatal(message)Something failed, no exception thrown

What happens in a run​

When you call start(), Aigentic does the following:

  1. Sends your task, instructions, context and input to the model.
  2. The model either answers or asks to call one of your tools.
  3. When it calls a tool, Aigentic runs your Kotlin code and sends the result back to the model.
  4. This repeats until the model finishes the task or says it's stuck.
  5. You get a run back. Its outcome is Finished, Stuck or Fatal.

start() doesn't throw when something goes wrong during the run. A failed model request or a tool that throws ends the run with Outcome.Fatal, so you handle errors with a when instead of a try.

Configuration mistakes are different: a missing model or task throws as soon as you build the agent with agent { }, before you can start it.

The parts of an agent​

Agent. agent<I, O> { } builds an agent that takes an I and gives back an O. Both are your own types, usually data classes annotated with @AigenticParameter. Agents

Task. What the agent should do, plus instructions on how to do it. This is your prompt, split into small, readable lines. Defining tasks

Model. The LLM behind the agent. Each provider has its own block, like geminiModel { } or openAIModel { }, and switching providers only changes that block. Providers

Tools. Kotlin functions the model can call, like looking up the weather or saving an invoice. The input type tells the model which arguments to send. Tools

Context. Fixed information the agent gets on every run, like a policy document or a product catalogue. Files that change per request go in as attachments instead. Adding context

Run and outcome. start() returns a run with the outcome, the full message history and the token usage. Processing results

Workflows​

A workflow chains agents with thenProcess. The output type of one agent must be the input type of the next, so the compiler checks the chain for you.

Documentagent<Document, Analysis>Analysisagent<Analysis, Summary>Summary

Workflows