diff --git a/docs/docs/planner-agents.md b/docs/docs/planner-agents.md index d976810cfd..264e4b3adf 100644 --- a/docs/docs/planner-agents.md +++ b/docs/docs/planner-agents.md @@ -1,9 +1,27 @@ # Planner agents -Planner agents are AI agents that can plan and execute multi-step tasks through iterative planning cycles. -They continuously build or update plans, execute steps, and check if goals have been achieved. +Planner agents are AI agents that can plan and execute multistep tasks through iterative planning cycles. +They continuously build or update plans, execute steps, and check completion criteria against the current state. -Planner agents are suitable for complex tasks that require breaking down a high-level goal into smaller, actionable steps, and adapting the plan based on the results of each step. +Planner agents are suitable for complex tasks +that require breaking down a high-level goal into smaller, actionable steps +and adapting the plan based on the results of each step. + +Planner agents operate through an iterative planning cycle: + +1. The planner creates or updates a plan based on the current state. +2. The planner executes a single step from the plan, updating the state. +3. The planner determines whether the plan is completed according to the current state. + - If the plan is completed, the cycle ends. + - If the plan is not completed, the cycle repeats from the first step. + +```mermaid +graph LR + A[Create or update plan] --> B["Execute step and update state"] + B --> C["Check completion"] + C -->|Completed| D[[Done]] + C -->|"Not completed"| A +``` ## Prerequisites @@ -11,7 +29,8 @@ Before you start, make sure that you have the following: - A working Kotlin/JVM project. - Java 17+ installed. -- A valid API key from the LLM provider used to implement an AI agent. For a list of all available providers, refer to [LLM providers](llm-providers.md). +- A valid API key from the LLM provider that you use to implement an AI agent. For a list of all available providers, +see [LLM providers](llm-providers.md). !!! tip Use environment variables or a secure configuration management system to store your API keys. @@ -23,29 +42,30 @@ To use planner agents, include the following dependencies in your build configur ``` dependencies { - implementation("ai.koog:koog-agents:$koog_version") - implementation("ai.koog.agents:agents-planner:$koog_version") - // Include Ktor client dependency explicitly - implementation("io.ktor:ktor-client-cio:$ktor_version") + implementation("ai.koog:koog-agents:VERSION") } ``` For all available installation methods, see [Install Koog](getting-started.md#install-koog). -## How planner agents work +## Simple LLM-based planners -Planner agents operate through an iterative planning cycle: +Simple LLM-based planners use LLMs to generate and evaluate plans. +They operate on a string-based state and execute steps through LLM requests. +String-based state means that the agent state is noted as a single string, +where the agent accepts an initial state string and returns the final state string as the result. -1. **Build a plan**: The planner creates or updates a plan based on the current state -2. **Execute a step**: The planner executes a single step from the plan, updating the state -3. **Check completion**: The planner determines if the goal has been achieved by checking the state against the goal condition -4. **Repeat**: If the goal is not achieved, the cycle repeats from step 1 +Koog provides two simple planners: -## Simple LLM-based planners +- [SimpleLLMPlanner](https://api.koog.ai/agents/agents-planner/ai.koog.agents.planner.llm/-simple-l-l-m-planner/index.html) + generates a plan only once at the very beginning and then follows the plan until it is completed. + To include replanning, extend `SimpleLLMPlanner` and override the `assessPlan` method, + indicating when the agent should replan. +- [SimpleLLMWithCriticPlanner](https://api.koog.ai/agents/agents-planner/ai.koog.agents.planner.llm/-simple-l-l-m-with-critic-planner/index.html) + implements the `assessPlan` method that uses an LLM. + The method checks the validity of the plan via an LLM request and assesses whether the agent should replan. -Simple LLM-based planners use LLMs to generate and evaluate plans. -They operate on a string state, i.e., just a single `String`, and execute steps through LLM requests. -Out-of-the-box, Koog provides two simple planners: `SimpleLLMPlanner` and `SimpleLLMWithCriticPlanner`: +The following example shows how to create a simple planner agent using `SimpleLLMPlanner`: - ```kotlin // Create the planner @@ -88,39 +103,46 @@ val agent = PlannerAIAgent( agentConfig = agentConfig ) -// Run the agent with a task -val result = agent.run("Create a plan to organize a team meeting") -println(result) +suspend fun main() { + // Run the agent with a task + val result = agent.run("Create a plan to organize a team meeting") + println(result) +} ``` ## GOAP (Goal-Oriented Action Planning) -GOAP is an algorithmic planning approach that uses A* search to find optimal action sequences. -Instead of using an LLM to generate plans, GOAP automatically discovers action sequences based on predefined goals and actions. - -### Key concepts +GOAP is an algorithmic planning approach that uses [A* search](https://en.wikipedia.org/wiki/A*_search_algorithm) to find optimal action sequences. +Instead of using an LLM to generate plans, +a GOAP agent automatically discovers action sequences based on predefined goals and actions. +In Koog, GOAP is implemented through a DSL that lets you define goals and actions declaratively. GOAP planners work with three main concepts: -- **State**: Represents the current state of the world -- **Actions**: Define what can be done, including preconditions, effects (beliefs), costs, and execution logic -- **Goals**: Define target conditions, heuristic costs, and value functions +- **State**: Represents the current state of the world. +- **Actions**: Define what can be done, including preconditions, effects (beliefs), costs, and execution logic. +- **Goals**: Define target conditions, heuristic costs, and value functions. -The planner uses A* search to find the sequence of actions that satisfies the goal condition while minimizing total cost. - -### Creating a GOAP agent +A GOAP planner uses A* search to find the sequence of actions that satisfies the goal condition while minimizing total cost. To create a GOAP agent, you need to: -1. Define your state type -2. Define actions with preconditions and effects -3. Define goals with completion conditions -4. Create the GOAP planner using the DSL -5. Wrap it in a planner strategy and agent +1. Define the state as a data class with properties representing various aspects specific to your goal. +2. Create a [GOAPPlanner](https://api.koog.ai/agents/agents-planner/ai.koog.agents.planner.goap/-g-o-a-p-planner/index.html) instance using the [goap()](https://api.koog.ai/agents/agents-planner/ai.koog.agents.planner.goap/goap.html) function. + 1. Define actions with preconditions and beliefs using the [action()](https://api.koog.ai/agents/agents-planner/ai.koog.agents.planner.goap/-g-o-a-p-planner-builder/action.html) function. + 2. Define goals with completion conditions using the [goal()](https://api.koog.ai/agents/agents-planner/ai.koog.agents.planner.goap/-g-o-a-p-planner-builder/goal.html) function. +3. Wrap the planner with [AIAgentPlannerStrategy](https://api.koog.ai/agents/agents-planner/ai.koog.agents.planner/-a-i-agent-planner-strategy/index.html) and pass it to the [PlannerAIAgent](https://api.koog.ai/agents/agents-planner/ai.koog.agents.planner/-planner-a-i-agent/index.html) constructor. + +!!! note -In the following example, GOAP handles the high-level planning (outline → draft → review → publish), + The planner selects individual actions and their sequence. + Each action includes a precondition that must hold true for the action to be executed + and a belief that defines the predicted outcome. + For more information about beliefs, see [State beliefs compared to actual execution](#state-beliefs-compared-to-actual-execution). + +In the following example, GOAP handles the high-level planning for creating an article (outline → draft → review → publish), while the LLM performs the actual content generation within each action. - ```kotlin // Define a state for content creation @@ -155,6 +172,7 @@ data class ContentState( // Create GOAP planner with LLM-powered actions val planner = goap(typeOf()) { + // Define actions with preconditions and beliefs action( name = "Create outline", precondition = { state -> !state.hasOutline }, @@ -213,7 +231,8 @@ val planner = goap(typeOf()) { println("Publishing article...") state.copy(isPublished = true) } - + + // Define the goal with a completion condition goal( name = "Published article", description = "Complete and publish the article", @@ -222,7 +241,6 @@ val planner = goap(typeOf()) { } // Create and run the agent -val strategy = AIAgentPlannerStrategy("content-planner", planner) val agentConfig = AIAgentConfig( prompt = prompt("writer") { system("You are a professional content writer.") @@ -233,12 +251,14 @@ val agentConfig = AIAgentConfig( val agent = PlannerAIAgent( promptExecutor = simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY")), - strategy = strategy, + strategy = AIAgentPlannerStrategy("content-planner", planner), agentConfig = agentConfig ) -val result = agent.run(ContentState(topic = "The Future of AI in Software Development")) -println("Final state: $result") +suspend fun main() { + val result = agent.run(ContentState(topic = "The Future of AI in Software Development")) + println("Final state: $result") +} ``` @@ -247,7 +267,8 @@ println("Final state: $result") ### Custom cost functions -You can define custom cost functions for actions and goals to guide the planner: +As A* search uses cost as a factor in finding the optimal sequence of actions, +you can define custom cost functions for actions and goals to guide the planner: ```kotlin action( @@ -264,12 +285,12 @@ action( } ``` -### State beliefs vs actual execution +### State beliefs compared to actual execution -GOAP distinguishes between beliefs (optimistic predictions) and actual execution: +GOAP distinguishes between the concepts of beliefs (optimistic predictions) and actual execution: -- **Belief**: What the planner thinks will happen (used for planning) -- **Execution**: What actually happens (used for real state updates) +- **Belief**: What the planner thinks will happen, used for planning. +- **Execution**: What actually happens, used for real state updates. This allows the planner to make plans based on expected outcomes while handling actual results properly: