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 strategy: AIAgentGraphStrategy<Input, Output>, val toolRegistry: ToolRegistry = ToolRegistry.EMPTY, 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.

Unique identifier for the agent. Random UUID will be generated if set to null.

Constructors

GraphAIAgent

constructor(inputType: KType, outputType: KType, promptExecutor: PromptExecutor, agentConfig: AIAgentConfig, strategy: AIAgentGraphStrategy<Input, Output>, toolRegistry: ToolRegistry = ToolRegistry.EMPTY, 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

Represents the unique identifier for the AI agent.

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.

promptExecutor

val promptExecutor: PromptExecutor

Executor used to manage and execute prompt strings.

strategy

open override val strategy: AIAgentGraphStrategy<Input, Output>

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<Input, AIAgentTool.AgentToolResult<Output>>

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

fun <TFeature : Any> feature(featureClass: KClass<TFeature>, feature: AIAgentFeature<*, TFeature>): TFeature?

Retrieves a feature from the agent's pipeline associated with this agent using the specified key.

feature

inline fun <TFeature : Any> StatefulSingleUseAIAgent<*, *, *>.feature(feature: AIAgentFeature<*, TFeature>): TFeature?

Retrieves a feature from the StatefulSingleUseAIAgent.pipeline associated with this agent using the specified key.

featureOrThrow

inline fun <TFeature : Any> StatefulSingleUseAIAgent<*, *, *>.featureOrThrow(feature: AIAgentFeature<*, TFeature>): TFeature

Retrieves a feature from the StatefulSingleUseAIAgent.pipeline associated with this agent using the specified key or throws an exception if it is not available.

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.