agents-core

Core library for building and executing AI agents with a graph-based architecture.

Overview

The agents-core module provides the fundamental components for creating, configuring, and executing AI agents. It implements a graph-based architecture where agents are represented as state machines with nodes and edges. Each node processes inputs and produces outputs, and the execution flows through the graph based on conditional edges.

Key features include:

Agent definition and configuration
Graph-based execution model
Exception handling for common agent issues
Interceptors for agent lifecycle, strategy, LLM, tool, and node events
Integration with LLM services
Tool registration and execution

Using in your project

To use the agents-core module in your project, add the following dependency:

dependencies {
    implementation("ai.koog.agents:agents-core:$version")
}

Then, you can create an AI agent by following these steps:

Define the tools your agent will use
Register the tools with a tool registry
Select the appropriate agent type
Configure the agent with the necessary parameters
Subscribe to agent events if needed
Run the agent with the desired input

Using in unit tests

The agents-core module provides utilities for testing AI agents, including:

Mocking LLM responses for deterministic behavior
Mocking tool calls and their results
Testing graph structure and node connections
Validating agent behavior in different scenarios

To enable testing mode on an agent, use the withTesting() function within the agent constructor block:

AIAgent(
    // constructor arguments
) {
    withTesting()
}

Example of usage

// Create a tool registry
val toolRegistry = ToolRegistry { }

// Register tools
toolRegistry.register(CalculatorTool)
toolRegistry.register(SearchTool)

// Configure the agent
val agentConfig = AgentConfig(
    maxAgentIterations = 10,
    // other configuration parameters
)

// Create the agent
val agent = AIAgent(
    promptExecutor = llmExecutor,
    toolRegistry = toolRegistry,
    strategy = simpleSingleRunStrategy(),
    eventHandler = eventHandler,
    agentConfig = agentConfig
)

// Run the agent
val result = agent.execute("Calculate the square root of 16")

Standard Feature Events

Features in the Koog ecosystem consume standardized Feature Events emitted by agents-core during agent execution. These events are defined in this module under the package ai.koog.agents.core.feature.model.events.

Agent events:

AgentStartingEvent
AgentCompletedEvent
AgentExecutionFailedEvent
AgentClosingEvent

Strategy events:

GraphStrategyStartingEvent
FunctionalStrategyStartingEvent
StrategyCompletedEvent

Node execution events:

NodeExecutionStartingEvent
NodeExecutionCompletedEvent
NodeExecutionFailedEvent

LLM call events:

LLMCallStartingEvent
LLMCallCompletedEvent

LLM streaming events:

LLMStreamingStartingEvent
LLMStreamingFrameReceivedEvent
LLMStreamingFailedEvent
LLMStreamingCompletedEvent

Tool execution events:

ToolExecutionStartingEvent
ToolValidationFailedEvent
ToolExecutionFailedEvent
ToolExecutionCompletedEvent

These events are emitted by the agents-core runtime and consumed by features such as Tracing, Debugger, and EventHandler to enable logging, tracing, monitoring, and remote inspection.