跳转至

基础智能体

基础智能体采用预定义策略和简单执行流程，适用于大多数常见场景。 它接收字符串输入（问题、请求或任务描述）并将其发送至配置的 LLM。 LLM 可决定是否调用提供的工具。 智能体将执行工具并将结果返回给 LLM。 此过程重复进行，直到 LLM 不再请求工具调用并返回字符串响应。 随后智能体输出该响应。

在基于图的智能体中， 您可了解如何重建基础智能体使用的预定义策略图。

前置条件

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

  • JDK 17+
  • Kotlin 2.2.0+
  • Gradle 8.0+ 或 Maven 3.8+

添加 Koog 包 作为依赖项：

build.gradle.kts
dependencies {
    implementation("ai.koog:koog-agents:0.7.1")
}
build.gradle
dependencies {
    implementation 'ai.koog:koog-agents:0.7.1'
}
pom.xml
<dependency>
    <groupId>ai.koog</groupId>
    <artifactId>koog-agents-jvm</artifactId>
    <version>0.7.1</version>
</dependency>

从 LLM 提供商获取 API 密钥，或通过 Ollama 运行本地 LLM。 更多信息请参阅 快速入门。

本页示例假设您已设置 OPENAI_API_KEY 环境变量。

创建最小化智能体

要创建最基础的智能体，请实例化 AIAgent 并提供包含语言模型的提示执行器：

val agent = AIAgent(
    promptExecutor = simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY")),
    llmModel = OpenAIModels.Chat.GPT4o
)

该智能体将接收字符串输入并返回字符串输出。 运行智能体时，使用 run() 函数并传入用户输入：

fun main() = runBlocking {
    val result = agent.run("Hello! How can you help me?")
    println(result)
}

<!--- INCLUDE import ai.koog.agents.core.agent.AIAgent; import ai.koog.prompt.executor.clients.openai.OpenAIModels;

import static ai.koog.prompt.executor.llms.all.SimplePromptExecutorsKt.simpleOpenAIExecutor;

class exampleBasicJava01 { public static void main(String[] args) { --> 

AIAgent<String, String> agent = AIAgent.builder()
    .promptExecutor(simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY")))
    .llmModel(OpenAIModels.Chat.GPT4o)
    .build();

该智能体接收字符串输入并返回字符串输出。 运行智能体时，使用 run() 方法并传入用户输入：

String result = agent.run("Hello! How can you help me?");
System.out.println(result);

智能体将返回通用答复，例如：

I can assist with a wide range of topics and tasks. Here are some examples:

1. **Answering questions**: I can provide information on various subjects, from science and history to entertainment and culture.
2. **Generating text**: I can help with writing tasks, such as suggesting alternative phrases, providing definitions, or even creating entire articles or stories.
3. **Translation**: I can translate text from one language to another, including popular languages such as Spanish, French, German, Chinese, and many more.
4. **Conversation**: I can engage in natural-sounding conversations, using context and understanding to respond to questions and statements.
5. **Brainstorming**: I can help generate ideas for creative projects, such as writing stories, composing music, or coming up with business ideas.
6. **Learning**: I can help with language learning, explaining grammar rules, vocabulary, and pronunciation.
7. **Calculations**: I can perform mathematical calculations, including basic arithmetic, algebra, and more advanced math concepts.

What's on your mind? Do you have a specific question, topic, or task you'd like to tackle?

添加系统提示

通过提供系统消息来定义智能体的角色， 以及任务相关的目的、上下文和指令。

val agent = AIAgent(
    promptExecutor = simpleOpenAIExecutor(System.getenv("YOUR_API_KEY")),
    systemPrompt = "You are an expert in internet memes. Be helpful, friendly, and answer user questions concisely, showing your knowledge of memes.",
    llmModel = OpenAIModels.Chat.GPT4o
)

<!--- INCLUDE import ai.koog.agents.core.agent.AIAgent; import ai.koog.prompt.executor.clients.openai.OpenAIModels;

import static ai.koog.prompt.executor.llms.all.SimplePromptExecutorsKt.simpleOpenAIExecutor;

class exampleBasicJava02 { public static void main(String[] args) { --> 

AIAgent<String, String> agent = AIAgent.builder()
    .promptExecutor(simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY")))
    .systemPrompt("You are an expert in internet memes. Be helpful, friendly, and answer user questions concisely, showing your knowledge of memes.")
    .llmModel(OpenAIModels.Chat.GPT4o)
    .build();
系统提示中的指令将指导代理的响应：

I'm here to help you navigate the wild world of internet memes!

What's on your mind? Are you trying to understand a specific meme, need help finding a popular joke, or perhaps want some recommendations for trending memes? Let me know, and I'll do my best to provide you with some LOLs!

配置 LLM 输出

您可以直接向代理构造函数（Kotlin）或通过构建器方法（Java）提供一些 LLM 参数来自定义 LLM 的行为。 例如，使用 temperature 参数来调整生成响应的随机性：

val agent = AIAgent(
    promptExecutor = simpleOpenAIExecutor(System.getenv("YOUR_API_KEY")),
    systemPrompt = "You are an expert in internet memes. Be helpful, friendly, and answer user questions concisely, showing your knowledge of memes.",
    llmModel = OpenAIModels.Chat.GPT4o,
    temperature = 0.7
)

<!--- INCLUDE import ai.koog.agents.core.agent.AIAgent; import ai.koog.prompt.executor.clients.openai.OpenAIModels;

import static ai.koog.prompt.executor.llms.all.SimplePromptExecutorsKt.simpleOpenAIExecutor;

class exampleBasicJava03 { public static void main(String[] args) { --> 

AIAgent<String, String> agent = AIAgent.builder()
    .promptExecutor(simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY")))
    .systemPrompt("You are an expert in internet memes. Be helpful, friendly, and answer user questions concisely, showing your knowledge of memes.")
    .llmModel(OpenAIModels.Chat.GPT4o)
    .temperature(0.7)
    .build();

以下是不同温度值下的响应示例：

I'm here to help you navigate the wild world of internet memes! Whether you're looking for explanations, examples, or just want to share a meme with someone, I'm your go-to expert. What's on your mind? Got a specific meme in mind that's got you curious? Or maybe you need some meme-related advice? Fire away!


I'm here to help you navigate the wild world of internet memes!

What's on your mind? Need help understanding a specific meme, finding a popular joke or trend, or maybe even creating your own meme? Let's get this meme party started!


I'd be happy to help you navigate the wild world of internet memes!

Whether you're looking for explanations of classic memes, suggestions for new ones to try out, or just want to discuss your favorite meme culture trends, I'm here to assist. What's on your mind?

Do you have a specific question about memes (e.g., "What does this meme mean?"), or are you looking for some meme-related recommendations (e.g., "Can you recommend a funny meme to share with friends?"). Let me know how I can help!

添加工具

代理可以使用 工具 来执行特定任务。

首先，通过使用 @Tool 注解标注函数（Kotlin）或方法（Java）来创建工具：

kotlin @Tool @LLMDescription("Ask the user a question by sending it to stdout and return the answer from stdin") fun askUser( @LLMDescription("Question from the agent") question: String ): String { println(question) return readln() }然后，使用 ToolRegistry 使该工具对代理可用：

```kotlin val agent = AIAgent( promptExecutor = simpleOpenAIExecutor(System.getenv("YOUR_API_KEY")), systemPrompt = "你是一位网络迷因专家。请乐于助人、态度友好，并简洁地回答用户问题，展示你对迷因的了解。", llmModel = OpenAIModels.Chat.GPT4o, temperature = 0.7, toolRegistry = ToolRegistry { tool(::askUser) } ) 

<!--- KNIT example-basic-03.kt -->

在此示例中，`askUser` 是一个工具，通过控制台的打印和读取帮助代理与用户保持对话。
如果代理决定向用户提问，
它可以调用此工具，该工具通过 `println()` 写入 `stdout`，并通过 `readln()` 从 `stdin` 读取。

=== "Java"

    <!--- INCLUDE
    import ai.koog.agents.core.agent.AIAgent;
    import ai.koog.agents.core.tools.ToolRegistry;
    import ai.koog.agents.core.tools.annotations.LLMDescription;
    import ai.koog.agents.core.tools.annotations.Tool;
    import ai.koog.agents.core.tools.reflect.ToolSet;
    import ai.koog.prompt.executor.clients.openai.OpenAIModels;

    import java.util.Scanner;

    import static ai.koog.prompt.executor.llms.all.SimplePromptExecutorsKt.simpleOpenAIExecutor;

    class exampleBasicJava04 {
        public static void main(String[] args) {
    -->
    <!--- SUFFIX
        }
    }
    -->
    ```java
    // 创建 ToolSet 类
    class UserConversationTools implements ToolSet {
        @Tool
        @LLMDescription("通过将问题发送到 stdout 并向代理返回来自 stdin 的答案来询问用户")
        public String askUser(
            @LLMDescription("来自代理的问题")
            String question
        ) {
            System.out.println(question);
            Scanner scanner = new Scanner(System.in);
            return scanner.nextLine();
        }
    }
    ```

    然后，使用 [`ToolRegistry`](https://api.koog.ai/agents/agents-tools/ai.koog.agents.core.tools/-tool-registry/index.html) 使该工具对代理可用：

    ```java
    UserConversationTools askUser = new UserConversationTools();

    ToolRegistry toolRegistry = ToolRegistry.builder()
            .tools(askUser)
            .build();

    AIAgent<String, String> agent = AIAgent.builder()
        .promptExecutor(simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY")))
        .systemPrompt("你是一位网络迷因专家。请乐于助人、态度友好，并简洁地回答用户问题，展示你对迷因的了解。")
        .llmModel(OpenAIModels.Chat.GPT4o)
        .temperature(0.7)
        .toolRegistry(toolRegistry)
        .build();
    ```
    <!--- KNIT exampleBasicJava04.java -->

    在此示例中，`askUser` 是一个工具，通过控制台的打印和读取帮助代理与用户保持对话。

以下是代理的一个交互示例：

```text
Agent: Which meme would you like me to explain? Please choose from: Grumpy Cat, Success Kid, or Doge.

User: Explain Doge

Agent:

**Doge**

Doge is a popular internet meme that originated on the imageboard website 4chan in 2013. The meme features a picture of a Shiba Inu dog with a caption written in a playful, exaggerated style.

The typical format of a Doge meme includes:

* A photo of a Shiba Inu dog
* A caption written in all capital letters, using a intentionally simplistic and childlike tone
* Exaggerated or made-up words or phrases, often used to convey a humorous or nonsensical idea

Examples of Doge memes might include:

* "Such wow. Such happy."
* "I had fun today!"
* "Wow, I am good at napping."

The meme is known for its lighthearted and playful tone, and is often used to express excitement, happiness, or silliness. The meme has since become a cultural phenomenon, with countless variations and parodies emerging online.

调整代理迭代次数

为避免无限循环，Koog 允许任何代理执行有限次数的步骤（默认为 50 步）。 使用 maxIterations 参数来增加此限制（如果你预期代理需要更多步骤， 例如工具调用和 LLM 请求），或减少此限制以适用于仅需少量步骤的代理。 例如，此处描述的简单代理不太可能需要超过 10 步：

=== "Kotlin" 

val agent = AIAgent(
    promptExecutor = simpleOpenAIExecutor(System.getenv("YOUR_API_KEY")),
    systemPrompt = "你是一位网络迷因专家。请保持乐于助人、友好亲切的态度，简洁地回答用户问题，并展现你对迷因的了解。",
    llmModel = OpenAIModels.Chat.GPT4o,
    temperature = 0.7,
    toolRegistry = ToolRegistry {
        tool(::askUser)
    },
    maxIterations = 10
)

<!--- INCLUDE import ai.koog.agents.core.agent.AIAgent; import ai.koog.agents.core.tools.ToolRegistry; import ai.koog.agents.core.tools.annotations.LLMDescription; import ai.koog.agents.core.tools.annotations.Tool; import ai.koog.agents.core.tools.reflect.ToolSet; import ai.koog.prompt.executor.clients.openai.OpenAIModels;

import java.util.Scanner;

import static ai.koog.prompt.executor.llms.all.SimplePromptExecutorsKt.simpleOpenAIExecutor;

class exampleBasicJava05 { public static void main(String[] args) { --> 

// 创建 ToolSet 类
class UserConversationTools implements ToolSet {
    @Tool
    @LLMDescription("通过将问题发送到 stdout 并从 stdin 读取答案来向用户提问")
    public String askUser(
        @LLMDescription("来自智能体的问题")
        String question
    ) {
        System.out.println(question);
        Scanner scanner = new Scanner(System.in);
        return scanner.nextLine();
    }
}

// 在 main 方法中：
UserConversationTools askUser = new UserConversationTools();

ToolRegistry toolRegistry = ToolRegistry.builder()
        .tools(askUser)
        .build();

AIAgent<String, String> agent = AIAgent.builder()
    .promptExecutor(simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY")))
    .systemPrompt("你是一位网络迷因专家。请保持乐于助人、友好亲切的态度，简洁地回答用户问题，并展现你对迷因的了解。")
    .llmModel(OpenAIModels.Chat.GPT4o)
    .temperature(0.7)
    .toolRegistry(toolRegistry)
    .maxIterations(10)
    .build();

Tip

除了直接将模型、温度、最大迭代次数等参数传递给 Kotlin 构造函数 或 Java 构建器，你也可以定义并传递一个独立的配置对象。 更多信息，请参阅智能体配置。

处理智能体运行期间的事件

为了辅助测试和调试，以及为链式智能体交互提供钩子， Koog 提供了 EventHandler 功能。

在智能体构造函数的 lambda 表达式内调用 handleEvents() 函数来安装该功能并注册事件处理器：

val agent = AIAgent(
    promptExecutor = simpleOpenAIExecutor(System.getenv("YOUR_API_KEY")),
    systemPrompt = "你是一位网络迷因专家。请保持乐于助人、友好亲切的态度，简洁地回答用户问题，并展现你对迷因的了解。",
    llmModel = OpenAIModels.Chat.GPT4o,
    temperature = 0.7,
    toolRegistry = ToolRegistry {
        tool(::askUser)
    },
    maxIterations = 10
){
    handleEvents {
        // 处理工具调用
        onToolCallStarting { eventContext ->
            println("工具调用：${eventContext.toolName}，参数 ${eventContext.toolArgs}")
        }
    }
}

使用智能体构建器上的 .install() 方法，通过 EventHandler.Feature 注册事件处理器：<!--- INCLUDE import ai.koog.agents.core.agent.AIAgent; import ai.koog.agents.core.tools.ToolRegistry; import ai.koog.agents.core.tools.annotations.LLMDescription; import ai.koog.agents.core.tools.annotations.Tool; import ai.koog.agents.core.tools.reflect.ToolSet; import ai.koog.agents.features.eventHandler.feature.EventHandler; import ai.koog.prompt.executor.clients.openai.OpenAIModels;

import java.util.Scanner;

import static ai.koog.prompt.executor.llms.all.SimplePromptExecutorsKt.simpleOpenAIExecutor;

class exampleBasicJava06 { public static void main(String[] args) { -->

// 创建一个 ToolSet 类
class UserConversationTools implements ToolSet {
    @Tool
    @LLMDescription("通过向标准输出发送问题来询问用户，并从标准输入返回答案")
    public String askUser(
        @LLMDescription("来自智能体的问题")
        String question
    ) {
        System.out.println(question);
        Scanner scanner = new Scanner(System.in);
        return scanner.nextLine();
    }
}

// 在 main 方法中：
UserConversationTools askUser = new UserConversationTools();

ToolRegistry toolRegistry = ToolRegistry.builder()
        .tools(askUser)
        .build();

AIAgent<String, String> agent = AIAgent.builder()
    .promptExecutor(simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY")))
    .systemPrompt("你是一位网络迷因专家。请保持乐于助人、态度友好，并简洁地回答用户问题，展现你对迷因的了解。")
    .llmModel(OpenAIModels.Chat.GPT4o)
    .temperature(0.7)
    .toolRegistry(toolRegistry)
    .maxIterations(10)
    .install(EventHandler.Feature, config -> {
        config.onToolCallStarting(eventContext -> {
            System.out.println("工具调用开始：" + eventContext.getToolName() +
                "，参数为 " + eventContext.getToolArgs());
        });
    })
    .build();

当智能体调用 askUser 工具时，现在将输出类似以下内容：

Tool called: askUser with args {"question":"Which meme would you like me to explain?"}

有关 Koog 智能体功能的更多信息，请参阅功能。

后续步骤