agents-core/ai.koog.agents.core.agent/GraphAIAgent

GraphAIAgent

open class GraphAIAgent<Input, Output>(val inputType: KType, val outputType: KType, val promptExecutor: PromptExecutor, val agentConfig: AIAgentConfig, val toolRegistry: ToolRegistry = ToolRegistry.EMPTY, strategy: AIAgentGraphStrategy<Input, Output>, id: String? = null, val clock: Clock = Clock.System, val installFeatures: GraphAIAgent.FeatureContext.() -> Unit = {}) : StatefulSingleUseAIAgent<Input, Output, AIAgentGraphContextBase> , Closeable(source)

Represents an implementation of an AI agent that provides functionalities to execute prompts, manage tools, handle agent pipelines, and interact with various configurable strategies and features.

The agent operates within a coroutine scope and leverages a tool registry and feature context to enable dynamic additions or configurations during its lifecycle. Its behavior is driven by a local agent strategy and executed via a prompt executor.

Parameters

Input

Type of agent input.

Output

Type of agent output.

Constructors

GraphAIAgent

constructor(inputType: KType, outputType: KType, promptExecutor: PromptExecutor, agentConfig: AIAgentConfig, toolRegistry: ToolRegistry = ToolRegistry.EMPTY, strategy: AIAgentGraphStrategy<Input, Output>, id: String? = null, clock: Clock = Clock.System, installFeatures: GraphAIAgent.FeatureContext.() -> Unit = {})

Initializes the AI agent instance and prepares the feature context and pipeline for use.

Types

FeatureContext

class FeatureContext

The context for adding and configuring features in a Kotlin AI Agent instance.

Properties

agentConfig

open override val agentConfig: AIAgentConfig

Configuration details for the local agent that define its operational parameters.

clock

val clock: Clock

The clock used to calculate message timestamps

override val id: String

A unique identifier represented as a string. This identifier is lazily initialized. If a value is present in agentId, it will use that; otherwise, it will generate a random UUID string.

inputType

val inputType: KType

KType representing Input - agent input.

installFeatures

val installFeatures: GraphAIAgent.FeatureContext.() -> Unit

Lambda for installing additional features within the agent environment.

outputType

val outputType: KType

KType representing Output - agent output.

pipeline

open override val pipeline: AIAgentGraphPipeline

Represents the pipeline used by the AI agent for processing tasks or data.

promptExecutor

val promptExecutor: PromptExecutor

Executor used to manage and execute prompt strings.

strategy

val strategy: AIAgentStrategy<Input, Output, AIAgentGraphContextBase>

the execution strategy defining how the agent processes input and produces output.

toolRegistry

val toolRegistry: ToolRegistry

Registry of tools the agent can interact with, defaulting to an empty registry.

Functions

asTool

inline fun <Input, Output> AIAgent<Input, Output>.~~asTool~~(agentName: String, agentDescription: String, inputDescription: String? = null, inputSerializer: KSerializer<Input> = serializer(), outputSerializer: KSerializer<Output> = serializer(), json: Json = Json.Default): Tool<AIAgentTool.AgentToolArgs, AIAgentTool.AgentToolResult>

Converts the current AI agent into a tool to allow using it in other agents as a tool.

suspend override fun close()

Closes the AI Agent and performs necessary cleanup operations.

feature

open override fun <Feature : Any> feature(key: AIAgentStorageKey<Feature>): Feature?

Retrieves a feature associated with the given key from the current context.

featureOrThrow

open fun <Feature : Any> featureOrThrow(feature: AIAgentFeature<*, Feature>): Feature

Retrieves a specific agent feature of type Feature from the AI agent's storage. If the requested feature is not found, throws an IllegalStateException.

getState

suspend override fun getState(): AIAgent.Companion.State<Output>

Retrieves the current state of the AI agent during its lifecycle.

isFinished

suspend fun AIAgent<*, *>.isFinished(): Boolean

Checks whether the AI agent has reached a finished state.

isRunning

suspend fun AIAgent<*, *>.isRunning(): Boolean

Checks whether the AI agent is currently in a running state.

prepareContext

open suspend override fun prepareContext(agentInput: Input, runId: String): AIAgentGraphContextBase

Prepares and initializes the agent context required to handle the given input and run ID.

result

open suspend fun result(): Output

Retrieves the result of the operation if the current state is State.Finished. Throws an IllegalStateException if the operation is not in a finished state.

run

suspend override fun run(agentInput: Input): Output

Executes the agent's main functionality, coordinating with various components such as pipelines and strategies. Ensures the agent is run in a thread-safe manner using locking mechanisms.