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

StatefulSingleUseAIAgent

abstract class StatefulSingleUseAIAgent<Input, Output, TContext : AIAgentContext>(logger: KLogger, id: String? = null) : AIAgent<Input, Output> (source)

Abstract base class representing a single-use AI agent with state.

This AI agent is designed to execute a specific long-running strategy only once, and provides API to monitor and manage it's state.

It maintains internal states including its running status, whether it was started, its result (if available), and the root context associated with its execution. The class enforces safe state transitions and provides thread-safe operations via a mutex.

Parameters

Input

the type of the input accepted by the agent.

Output

the type of the output produced by the agent.

TContext

the type of the context used during the agent's execution, extending AIAgentContext.

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

Inheritors

FunctionalAIAgent

GraphAIAgent

Constructors

StatefulSingleUseAIAgent

constructor(logger: KLogger, id: String? = null)

Properties

agentConfig

abstract val agentConfig: AIAgentConfigBase

The configuration for the AI agent.

override val id: String

Represents the unique identifier for the AI agent.

strategy

abstract val strategy: AIAgentStrategy<Input, Output, TContext>

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

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

abstract suspend fun prepareContext(agentInput: Input, runId: String): TContext

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.