GOAP 智能体

Beta

此功能属于 Beta 模块 (1.2.0-beta)，其 API 可能在后续版本中发生变化。

有关详细信息，请参阅模块版本控制。

GOAP 是一种算法规划方法，它使用 A* 搜索寻找在满足目标条件的同时使总代价最小的最优操作序列。与使用 LLM 生成方案的基于 LLM 的规划器不同，GOAP 智能体根据预定义的目标和操作，通过算法发现操作序列。

GOAP 规划器围绕三个核心概念工作：

状态 (State)：代表世界的当前状态。
操作 (Actions)：定义可以执行的任务，包括前置条件、效果（信念）、代价和执行逻辑。
目标 (Goals)：定义目标条件、启发式代价和价值函数。

前提条件

确保您的开发环境和项目满足以下要求：

JDK 17+
Kotlin 2.2.0+
Gradle 8.0+ 或 Maven 3.8+ 添加 Koog 依赖项：

Gradle (Kotlin)Gradle (Groovy)Maven


dependencies {

    // 稳定版

    implementation("ai.koog:koog-agents:1.2.0")

    // Beta 版

    implementation("ai.koog:koog-agents-additions:1.2.0-beta")

}


dependencies {

    // 稳定版

    implementation 'ai.koog:koog-agents:1.2.0'

    // Beta 版

    implementation 'ai.koog:koog-agents-additions:1.2.0-beta'

}

xml


<dependency>

    <!-- 稳定版 -->

    <dependency>

        <groupId>ai.koog</groupId>

        <artifactId>koog-agents-jvm</artifactId>

        <version>1.2.0</version>

    </dependency>

    <!-- Beta 版 -->

    <dependency>

        <groupId>ai.koog</groupId>

        <artifactId>koog-agents-additions-jvm</artifactId>

        <version>1.2.0-beta</version>

    </dependency>

</dependency>

从 LLM 提供商处获取 API 密钥，或者通过 Ollama 在本地运行 LLM。

有关详细信息，请参阅快速入门。本页面中的示例假设您已设置 OPENAI_API_KEY 环境变量。

在 Koog 中，您可以使用 DSL 通过声明式地指定目标和操作来定义 GOAP 智能体。

要创建一个 GOAP 智能体，您需要：

将状态定义为一个数据类，其属性代表特定于目标的各个方面。
使用 goap() 函数创建一个 GOAPPlanner 实例。
1. 使用 action() 函数定义带有前置条件和信念的操作。
2. 使用 goal() 函数定义带有完成条件的目标。
使用 AIAgentPlannerStrategy 包装规划器，并将其传递给 PlannerAIAgent 构造函数。

Note

规划器选择单个操作及其序列。每个操作都包含一个必须为真才能执行的前置条件，以及一个定义预测结果的信念。有关信念的更多信息，请参阅状态信念与实际执行的比较。

在以下示例中，GOAP 处理创建文章的高级规划（大纲 → 草稿 → 审核 → 发布），而 LLM 在每个操作中执行实际的内容生成。

KotlinJava

kotlin

// 为内容创作定义一个状态
data class ContentState(
    val topic: String,
    val hasOutline: Boolean = false,
    val outline: String = "",
    val hasDraft: Boolean = false,
    val draft: String = "",
    val hasReview: Boolean = false,
    val isPublished: Boolean = false
): GoapAgentState<String, String>() {
    override val agentInput = topic
    override fun provideOutput(): String = draft
}

// 创建带有 LLM 驱动操作的 GOAP 规划器
val planner = goap("content-planner", ::ContentState) {
    // 定义带有前置条件和信念的操作
    action(
        name = "Create outline",
        precondition = { state -> !state.hasOutline },
        belief = { state -> state.copy(hasOutline = true, outline = "Outline") },
        cost = { 1.0 }
    ) { ctx, state ->
        // 使用 LLM 创建大纲
        val response = ctx.llm.writeSession {
            appendPrompt {
                user("Create a detailed outline for an article about: ${state.topic}")
            }
            requestLLM()
        }
        state.copy(hasOutline = true, outline = response.parts.filterIsInstance<MessagePart.Text>().joinToString("
") { it.text })
    }

    action(
        name = "Write draft",
        precondition = { state -> state.hasOutline && !state.hasDraft },
        belief = { state -> state.copy(hasDraft = true, draft = "Draft") },
        cost = { 2.0 }
    ) { ctx, state ->
        // 使用 LLM 撰写草稿
        val response = ctx.llm.writeSession {
            appendPrompt {
                user("Write an article based on this outline:
${state.outline}")
            }
            requestLLM()
        }
        state.copy(hasDraft = true, draft = response.parts.filterIsInstance<MessagePart.Text>().joinToString("
") { it.text })
    }

    action(
        name = "Review content",
        precondition = { state -> state.hasDraft && !state.hasReview },
        belief = { state -> state.copy(hasReview = true) },
        cost = { 1.0 }
    ) { ctx, state ->
        // 使用 LLM 审核草稿
        val response = ctx.llm.writeSession {
            appendPrompt {
                user("Review this article and suggest improvements:
${state.draft}")
            }
            requestLLM()
        }
        println("Review feedback: ${response.parts.filterIsInstance<MessagePart.Text>().joinToString("
") { it.text }}")
        state.copy(hasReview = true)
    }

    action(
        name = "Publish",
        precondition = { state -> state.hasReview && !state.isPublished },
        belief = { state -> state.copy(isPublished = true) },
        cost = { 1.0 }
    ) { ctx, state ->
        println("Publishing article...")
        state.copy(isPublished = true)
    }

    // 定义带有完成条件的目标
    goal(
        name = "Published article",
        description = "Complete and publish the article",
        condition = { state -> state.isPublished }
    )
}

// 创建并运行智能体
val agentConfig = AIAgentConfig(
    prompt = prompt("writer") {
        system("You are a professional content writer.")
    },
    model = OpenAIModels.Chat.GPT4o,
    maxAgentIterations = 20
)

val agent = AIAgent(
    promptExecutor = simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY")),
    strategy = planner,
    agentConfig = agentConfig
)

suspend fun main() {
    val result = agent.run("The Future of AI in Software Development")
    println("Final state: $result")
}

java

// 为内容创作定义一个状态
static class ContentState extends GoapAgentState<String, String> {
    public String topic;
    public boolean hasOutline = false;
    public String outline = "";
    public boolean hasDraft = false;
    public String draft = "";
    public boolean hasReview = false;
    public boolean isPublished = false;

    public ContentState(String topic) {
        this.topic = topic;
    }

    @Override
    public String getAgentInput() {
        return topic;
    }

    public ContentState copy(boolean hasOutline, String outline, boolean hasDraft,
                             String draft, boolean hasReview, boolean isPublished) {
        ContentState state = new ContentState(topic);
        state.hasOutline = hasOutline;
        state.outline = outline;
        state.hasDraft = hasDraft;
        state.draft = draft;
        state.hasReview = hasReview;
        state.isPublished = isPublished;
        return state;
    }

    @Override
    public String provideOutput() {
        return draft;
    }
}

public static void main(String[] args) {
    var promptExecutor = PromptExecutor.builder()
        .openAI("OPENAI_API_KEY")
        .build();

    var strategy = Planners.goap("content-planner", ContentState::new)
        .action("Create outline", builder -> builder
            .precondition(state -> !state.hasOutline)
            .belief(state -> state.copy(true, "Outline", false, "", false, false))
            .cost(state -> 1.0)
            .execute((context, state) -> {
                String response = context.llm().writeSession(session -> {
                    session.appendPrompt(prompt -> {
                        prompt.user("Create a detailed outline for an article about: " + state.topic);
                        return null;
                    });
                    return session.requestLLM().getParts().stream()
                        .filter(p -> p instanceof MessagePart.Text)
                        .map(p -> ((MessagePart.Text) p).getText())
                        .collect(Collectors.joining());
                });
                return state.copy(true, response, state.hasDraft, state.draft,
                                state.hasReview, state.isPublished);
            })
        )
        .action("Write draft", builder -> builder
            .precondition(state -> state.hasOutline && !state.hasDraft)
            .belief(state -> state.copy(state.hasOutline, state.outline, true, "Draft", false, false))
            .cost(state -> 2.0)
            .execute((context, state) -> {
                String response = context.llm().writeSession(session -> {
                    session.appendPrompt(prompt -> {
                        prompt.user("Write an article based on this outline:
" + state.outline);
                        return null;
                    });
                    return session.requestLLM().getParts().stream()
                        .filter(p -> p instanceof MessagePart.Text)
                        .map(p -> ((MessagePart.Text) p).getText())
                        .collect(Collectors.joining());
                });
                return state.copy(state.hasOutline, state.outline, true, response,
                                state.hasReview, state.isPublished);
            })
        )
        .action("Review content", builder -> builder
            .precondition(state -> state.hasDraft && !state.hasReview)
            .belief(state -> state.copy(state.hasOutline, state.outline, state.hasDraft,
                                       state.draft, true, false))
            .cost(state -> 1.0)
            .execute((context, state) -> {
                String response = context.llm().writeSession(session -> {
                    session.appendPrompt(prompt -> {
                        prompt.user("Review this article and suggest improvements:
" + state.draft);
                        return null;
                    });
                    return session.requestLLM().getParts().stream()
                        .filter(p -> p instanceof MessagePart.Text)
                        .map(p -> ((MessagePart.Text) p).getText())
                        .collect(Collectors.joining());
                });
                System.out.println("Review feedback: " + response);
                return state.copy(state.hasOutline, state.outline, state.hasDraft,
                                state.draft, true, state.isPublished);
            })
        )
        .action("Publish", builder -> builder
            .precondition(state -> state.hasReview && !state.isPublished)
            .belief(state -> state.copy(state.hasOutline, state.outline, state.hasDraft,
                                       state.draft, state.hasReview, true))
            .cost(state -> 1.0)
            .execute((context, state) -> {
                System.out.println("Publishing article...");
                return state.copy(state.hasOutline, state.outline, state.hasDraft,
                                state.draft, state.hasReview, true);
            })
        )
        .goal("Published article", builder -> builder
            .description("Complete and publish the article")
            .condition(state -> state.isPublished)
        )
        .build();

    var agent = AIAgent.builder()
        .plannerStrategy(strategy)
        .promptExecutor(promptExecutor)
        .llmModel(OpenAIModels.Chat.GPT4o)
        .systemPrompt("You are a professional content writer.")
        .maxIterations(20)
        .build();

    String result = agent.run("The Future of AI in Software Development");
    System.out.println("Final state: " + result);
}

自定义代价函数

由于 A* 搜索使用代价作为寻找最优操作序列的一个因素，您可以为操作和目标定义自定义代价函数来引导规划器：

KotlinJava

kotlin

action(
    name = "Expensive operation",
    precondition = { true },
    belief = { state -> state.copy(operationDone = true) },
    cost = { state ->
        // 基于状态的动态代价
        if (state.hasOptimization) 1.0 else 10.0
    }
) { ctx, state ->
    // 执行操作
    state.copy(operationDone = true)
}

java

.action("Expensive operation", builder -> builder
    .precondition(state -> true)
    .belief(state -> state.copy(true))
    .cost(state -> {
        // 基于状态的动态代价
        return state.hasOptimization ? 1.0 : 10.0;
    })
    .execute((context, state) -> {
        // 执行操作
        return state.copy(true);
    })
)

状态信念与实际执行的比较

GOAP 区分了信念（乐观预测）和实际执行的概念：

信念 (Belief)：规划器认为会发生什么，用于规划。
执行 (Execution)：实际发生了什么，用于真实的状态更新。

这使得规划器能够根据预期结果制定计划，同时妥善处理实际结果：

KotlinJava

kotlin

action(
    name = "Attempt complex task",
    precondition = { state -> !state.taskComplete },
    belief = { state ->
        // 乐观信念：任务将会成功
        state.copy(taskComplete = true)
    },
    cost = { 5.0 }
) { ctx, state ->
    // 实际执行可能会失败或产生不同的结果
    val success = performComplexTask()
    state.copy(
        taskComplete = success,
        attempts = state.attempts + 1
    )
}

java

.action("Attempt complex task", builder -> builder
    .precondition(state -> !state.taskComplete)
    .belief(state -> {
        // 乐观信念：任务将会成功
        return state.copy(true, state.attempts);
    })
    .cost(state -> 5.0)
    .execute((context, state) -> {
        // 实际执行可能会失败或产生不同的结果
        boolean success = performComplexTask();
        return state.copy(success, state.attempts + 1);
    })
)

概览

代理

规划代理

提示词

创建提示词

运行提示词

工具

特性

聊天记忆

OpenTelemetry

A2A 协议

子图

GOAP 智能体

自定义代价函数

状态信念与实际执行的比较

规划代理

创建提示词

聊天记忆

OpenTelemetry

GOAP 智能体 ​

自定义代价函数 ​

状态信念与实际执行的比较 ​

GOAP 智能体

自定义代价函数

状态信念与实际执行的比较