Skip to main content

Component Overview

The following explains the main components of the Arc Agent Framework.

See the Manual Setup section for an example on how these components work together.

Agent Interface​

The Agent interface is at the core of the Arc Framework and defines an Agent. The interface is very generic allowing for different types of agents to be implemented.

interface Agent<I, O> {

    val name: String

    val description: String

    /**
     * Executes the agent with the given input and context.
     * The objects passed as the context can be accessed within the Agents DSL using DSLContext#context.
     */
    suspend fun execute(input: I, context: Set<Any> = emptySet()): Result<O, AgentFailedException>
}

ChatAgent​

The ChatAgent is the main implementation of the Arc Agent interface.

As the name suggests, ChatAgents are agents that conduct a conversation with the client/user. They take a Conversation object as input and outputs the Conversation containing a new message.

See the Conversations section for more details on conversations.

AgentProvider/LLMFunctionProvider Interface​

The AgentProvider provides Agents to other components in an application and the LLMFunctionProvider provides LLM functions to the Agents.

These Providers usually consolidate all Loaders, see Loaders, within an application. Therefore, each application should have at most one AgentProvider.

When using the arc-spring-boot-starter, the CompositeAgentProvider and CompositeLLMFunctionProvider are automatically configured as the default Providers.

These Providers combine all AgentLoaders, LLMFunctionLoaders and any Agents or LLM functions that were injected directly into the Spring Context.

AgentLoader/LLMFunctionLoader Interface​

AgentLoaders and LLMFunctionLoaders create and load Agents and LLM functions respectively.

Unlike Providers, an application may have multiple Loaders.

The common Loaders are the ScriptAgentLoader and ScriptingLLMFunctionLoader that loads Agents and functions from Kotlin scripts.

Agents and functions can also be loaded as Spring Beans. See Spring Agent Beans

AgentFactory Interface​

The AgentFactory is responsible for converting Agents defined in the Agent DSL into an actual implementation.

 /**
  * Factory for creating agents from Agent Definitions.
  */
 fun interface AgentFactory<T : Agent<*, *>> {
     fun createAgent(agentDefinition: AgentDefinition): T
 }

The most common implementation is the ChatAgentFactory which creates ChatAgent instances from the agent DSL.

ChatCompleter Interface​

A ChatCompleter generates a response to a given message. In most cases, this interface is implemented by an LLM client.

See the Clients section for a list of supported clients.

ChatCompleterProvider Interface​

The ChatCompleterProvider simply provides a ChatCompleter for a given model id. The model id is defined in the model field of an Agent.

Note: It is up to the implementation of the ChatCompleterProvider to decide how to handle cases where a ChatCompleter is not found for a given model id.

Checkout the LangChain4J client for an example of a ChatCompleterProvider.

BeanProvider Interface​

A BeanProvider provides arbitrary beans that are used within the Arc Agent DSL.

These beans can be accessed from anywhere within the Agent DSL using the get<BeanClass>() method.

Example

agent {
    name = "weather-agent"
    description = "A helpful assistant that can provide information about the weather."
    prompt {
        val weather = get<Weather>()
        """
         You are a helpful assistant that provides weather information.
         The current weather is $weather.
        """
    }
}

When using the arc-spring-boot-starter, a BeanProvider providing access to all beans in the spring context is configured automatically.

Conversation Model​

The Conversation object represents a conversation between a client and an Arc Agent, such as a ChatAgent. It contains the entire transcript of the conversation, both client and agent messages, plus some metadata about the conversation.

Each Conversation object should be associated with a User who acts as the owner of the conversation. This prevents unauthorized users/clients from accessing a conversation. Furthermore, the User id may also be used as a key to store user/client specific data.

Messages are usually be one of 2 types:

  • UserMessage - messages sent by the user/client.
  • AssistantMessage - messages generated by the Agent.

SystemMessages, messages that contain instructions for the Agent, are usually not store in the conversation transcript.