Embabel Agent Documentation/com.embabel.agent.core

Package-level declarations

Types

interface Action : DataFlowStep, GoapAction, ActionRunner, DataDictionary, ToolGroupConsumer

Core Action model in Agent system. An individual action step used in an Agent Not intended for direct use by application code. User applications should use the annotation programming model with @Agentic and @Action or the Kotlin DSL, or a non-code representation such as YML.

ActionInvocation

data class ActionInvocation(val actionName: String, val timestamp: Instant = Instant.now(), val runningTime: Duration)

History element

ActionMetadata

data class ActionMetadata(val name: String, val description: String, val inputs: Set<IoBinding>, val outputs: Set<IoBinding>, val preconditions: EffectSpec, val effects: EffectSpec, val cost: <Error class: unknown class>, val value: <Error class: unknown class>, val canRerun: Boolean, val qos: ActionQos)

Serializable action metadata

ActionQos

data class ActionQos(val maxAttempts: Int = 5, val backoffMillis: Long = 10000, val backoffMultiplier: Double = 5.0, val backoffMaxInterval: Long = 60000, val idempotent: Boolean = false) : RetryProperties

Quality of service requirements for an action

ActionRunner

interface ActionRunner

ActionSource

interface ActionSource

ActionStatus

open class ActionStatus(val runningTime: Duration, val status: ActionStatusCode) : OperationStatus<ActionStatusCode>

Status of action execution. Concrete results of running the action will be side effects: typically, changes to the ProcessContext blackboard. This just indicates what happened.

ActionStatusCode

enum ActionStatusCode : Enum<ActionStatusCode>

Agent

data class Agent(val name: String, val provider: String, val version: <Error class: unknown class> = Semver(), val description: String, val conditions: Set<Condition> = emptySet(), val actions: List<Action>, val goals: Set<Goal>, val stuckHandler: StuckHandler? = null, val opaque: Boolean = false, val domainTypes: Collection<DomainType> = mergeTypes( agentName = name, defaultDataTypes = emptyList(), actions = actions, )) : AgentScope

An agent defines a set of actions and conditions that enable planning.

AgentMetadata

data class AgentMetadata(val name: String, val provider: String, val version: <Error class: unknown class>, val description: String, val goals: Set<Goal>, val actions: List<ActionMetadata>, val conditions: Set<String>)

Safely serializable agent metadata

AgentPlatform

interface AgentPlatform : AgentScope

An AgentPlatform can run agents. It can also act as an agent itself, drawing on all of its agents as its own actions, goals, and conditions. An AgentPlatform is stateful, as agents can be deployed to it. See TypedOps for a higher level API with typed I/O. Typically, there is one AgentPlatform per Spring Boot application, with agents discovered by classpath scanning for @Agent annotations, but this is not a requirement.

AgentProcess

interface AgentProcess : Blackboard, OperationStatus<AgentProcessStatusCode> , LlmInvocationHistory

Run of an agent

AgentProcessStatusCode

enum AgentProcessStatusCode : Enum<AgentProcessStatusCode>

Stuck means we failed to find a plan from here

AgentProcessStatusReport

data class AgentProcessStatusReport(val id: String, val status: AgentProcessStatusCode, val timestamp: Instant, val runningTime: Duration) : OperationStatus<AgentProcessStatusCode>

Safely serializable status for agent processes.

AgentScope

interface AgentScope : GoalSource, ConditionSource, ActionSource, DataDictionary

Defines the scope of an agent or agents: Goals, conditions and actions. Both Agents and AgentPlatforms are AgentScopes.

AgentSystemStep

interface AgentSystemStep : GoapStep, Operation

Bindable

interface Bindable

Allows binding and retrieval of objects using Kotlin operator functions and traditional get/set

Blackboard

interface Blackboard : Bindable, MayHaveLastResult

How agent processes maintain context

Budget

data class Budget(val cost: Double = DEFAULT_COST_LIMIT, val actions: Int = DEFAULT_ACTION_LIMIT, val tokens: Int = DEFAULT_TOKEN_LIMIT)

Budget for an agent process.

ComputedBooleanCondition

class ComputedBooleanCondition(val name: String, val cost: <Error class: unknown class> = 0.0, evaluator: (context: OperationContext, condition: Condition) -> Boolean) : Condition

Convenient class for a condition that evaluates to true or false.

Condition

interface Condition : Operation

A Condition is a named, well known predicate that can be evaluated and reused across multiple Actions.

ConditionSource

interface ConditionSource

ContextId

value class ContextId(val value: String)

Id of a context.

CoreToolGroups

object CoreToolGroups

Core tool groups exposed by the platform These should be supported in any AgentPlatform instance.

DataDictionary

interface DataDictionary

Implemented by types that reference data types

DataDictionaryImpl

class DataDictionaryImpl(val domainTypes: Collection<DomainType>) : DataDictionary

DataFlowStep

interface DataFlowStep : AgentSystemStep

Step that takes data as input and produces data as output.

Delay

enum Delay : Enum<Delay>

DomainType

sealed interface DomainType

Type known to the Embabel agent platform. May be backed by a domain object or by a map.

DynamicType

data class DynamicType(val name: String, val description: String = name, val properties: List<PropertyDefinition> = emptyList()) : DomainType

Simple data type

EarlyTermination

class EarlyTermination(val agentProcess: AgentProcess, val reason: String, val policy: EarlyTerminationPolicy) : AbstractAgentProcessEvent

Event triggered when an agent process is terminated early by a policy.

EarlyTerminationPolicy

interface EarlyTerminationPolicy

Enables early termination of an agent process.

Export

data class Export(val name: String? = null, val remote: Boolean = false, val local: Boolean = true, val startingInputTypes: Set<Class<*>> = emptySet())

Metadata describing how a goal will be exported

Goal

data class Goal(val name: String, val description: String, val pre: Set<String> = emptySet(), val inputs: Set<IoBinding> = emptySet(), val outputClass: Class<*>?, val value: <Error class: unknown class> = 0.0, val tags: Set<String> = emptySet(), val examples: Set<String> = emptySet(), val export: Export = Export()) : GoapGoal, AgentSystemStep

Agent platform goal. Exposes GOAP metadata.

GoalSource

interface GoalSource

Identities

data class Identities(val forUser: User? = null, val runAs: User? = null)

Identities associated with an agent process.

InjectedType

interface InjectedType : Operation

Access to agent infrastructure via injected parameter.

InProcess

interface InProcess

IoBinding

value class IoBinding(val value: String)

Binding definition of form name:Type If name is omitted, it is assumed to be 'it' Used to build preconditions from input and output bindings. Default name ("it") has a special meaning. It will be satisfied by an instance of the correct type being bound to "it", but also by the final result of the action having the correct type.

JvmType

data class JvmType(val clazz: Class<*>) : DomainType

Typed backed by a JVM object

LlmInvocation

data class LlmInvocation(val llm: <Error class: unknown class>, val usage: <Error class: unknown class>, val agentName: String? = null, val timestamp: Instant, val runningTime: Duration)

LlmInvocationHistory

interface LlmInvocationHistory

LlmVerbosity

interface LlmVerbosity

MayHaveLastResult

interface MayHaveLastResult

Operation

sealed interface Operation

Named operation in agent system: Action, Goal or Condition

OperationStatus

interface OperationStatus<S : Enum<S>>

Status of an agent or action

ProcessContext

data class ProcessContext(val processOptions: ProcessOptions = ProcessOptions(), platformServices: PlatformServices, val outputChannel: OutputChannel = platformServices.outputChannel, val agentProcess: AgentProcess) : LlmOperations, AgenticEventListener

Process state and services. Created by the platform, not user code.

ProcessControl

data class ProcessControl(val toolDelay: Delay = Delay.NONE, val operationDelay: Delay = Delay.NONE, val earlyTerminationPolicy: EarlyTerminationPolicy)

Controls Process running. Prevents infinite loops, enforces budget limits, and manages delays.

ProcessOptions

data class ProcessOptions(val contextId: ContextId? = null, val identities: Identities = Identities(), val blackboard: Blackboard? = null, val test: Boolean = false, val verbosity: Verbosity = Verbosity(), val allowGoalChange: Boolean = true, val budget: Budget = Budget(), val control: ProcessControl = ProcessControl( toolDelay = Delay.NONE, operationDelay = Delay.NONE, earlyTerminationPolicy = budget.earlyTerminationPolicy(), ), val prune: Boolean = false, val listeners: List<AgenticEventListener> = emptyList())

How to run an AgentProcess

PropertyDefinition

data class PropertyDefinition(val name: String, val type: String = "string", val description: String? = name)

ToolCallbackConsumer

interface ToolCallbackConsumer : ToolCallbackSpec

ToolCallbackPublisher

interface ToolCallbackPublisher : ToolCallbackSpec

Implemented by classes that want to publish tool callbacks

ToolCallbackSpec

interface ToolCallbackSpec

ToolConsumer

interface ToolConsumer : ToolCallbackConsumer, ToolGroupConsumer

Allows consuming tools and exposing them to LLMs. Interface allowing abstraction between tool concept and specific tools.

ToolGroup

interface ToolGroup : ToolCallbackPublisher

A group of tools to accomplish a purpose, such as web search. Introduces a level of abstraction over tool callbacks.

ToolGroupConsumer

interface ToolGroupConsumer

ToolGroupDescription

interface ToolGroupDescription

ToolGroupMetadata

interface ToolGroupMetadata : ToolGroupDescription

Metadata about a tool group. Interface as platforms may extend it

ToolGroupPermission

enum ToolGroupPermission : Enum<ToolGroupPermission>

ToolGroupRequirement

data class ToolGroupRequirement(val role: String)

Specifies a tool group that a tool consumer requires.

ToolGroupResolution

data class ToolGroupResolution(val resolvedToolGroup: ToolGroup?, val failureMessage: String? = null)

Resolution of a tool group request

Verbosity

data class Verbosity(val showPrompts: Boolean = false, val showLlmResponses: Boolean = false, val debug: Boolean = false, val showPlanning: Boolean = false) : LlmVerbosity

Controls log output.