Shell Commands

The ShellCommands class is the main entry point for the interactive shell interface, providing comprehensive commands for agent management, task execution, and system operations.

Import

import com.embabel.agent.shell.ShellCommands

Component Declaration

@ShellComponent
class ShellCommands(
    private val autonomy: Autonomy,
    private val modelProvider: ModelProvider,
    private val terminalServices: TerminalServices,
    private val environment: ConfigurableEnvironment,
    private val objectMapper: ObjectMapper,
    private val colorPalette: ColorPalette,
    loggingPersonality: LoggingPersonality,
    private val toolsStats: ToolsStats,
    private val context: ConfigurableApplicationContext,
    private val shellProperties: ShellProperties = ShellProperties(),
    @param:Autowired(required = false)
    private val chatbot: Chatbot? = null
)

The class is automatically instantiated by Spring when included in your application's component scan.

Optional Dependencies: The chatbot parameter is marked with @Autowired(required = false), meaning the chatbot dependency is optional. If no Chatbot bean is available in the Spring context, chatbot will be null and the shell will function without chat capabilities. When a Chatbot bean is provided, the chat command becomes available.

Agent Management Commands

List Agents

List all available agents in the platform with detailed information.

@ShellMethod("List agents")
fun agents(): String

Returns: Formatted string with agent details including name, description, goals, actions, and conditions.

Usage:

embabel> agents

List Actions

List all available actions with detailed information.

@ShellMethod("List actions")
fun actions(): String

Returns: Formatted string with action details including name and description.

Usage:

embabel> actions

List Goals

List all available goals with detailed information.

@ShellMethod("List goals")
fun goals(): String

Returns: Formatted string with goal details including name and description.

Usage:

embabel> goals

List Conditions

List all available conditions with detailed information.

@ShellMethod("List conditions")
fun conditions(): String

Returns: Formatted string with condition details including name and description.

Usage:

embabel> conditions

Choose Goal

Try to choose a goal for a given intent, showing all goal rankings.

@ShellMethod("Try to choose a goal for a given intent. Show all goal rankings")
fun chooseGoal(
    @ShellOption(help = "what the agent system should do") intent: String
): String

Parameters:

• intent: String describing what the agent system should do

Returns: Goal rankings and chosen agent information, or error message if goal not found/approved

Usage:

embabel> chooseGoal "Find news about technology"

Task Execution Commands

Execute Task

Execute a task with a given natural language intent.

@ShellMethod(
    "Execute a task. Put the task in double quotes. For example:\n\tx \"Lynda is a scorpio. Find news for her\" -p",
    key = ["execute", "x"]
)
fun execute(
    @ShellOption(help = "what the agent system should do") intent: String,
    @ShellOption(
        value = ["-o", "--open"],
        help = "run in open mode, choosing a goal and using all actions that can help achieve it"
    ) open: Boolean = false,
    @ShellOption(value = ["-p", "--showPrompts"], help = "show prompts to LLMs") showPrompts: Boolean,
    @ShellOption(value = ["-r", "--showResponses"], help = "show LLM responses") showLlmResponses: Boolean = false,
    @ShellOption(value = ["-d", "--debug"], help = "show debug info") debug: Boolean = false,
    @ShellOption(value = ["-s", "--state"], help = "Use existing blackboard") state: Boolean = false,
    @ShellOption(value = ["-td", "--toolDelay"], help = "Tool delay") toolDelay: Boolean = false,
    @ShellOption(value = ["-od", "--operationDelay"], help = "Operation delay") operationDelay: Boolean = false,
    @ShellOption(
        value = ["-P", "--showPlanning"],
        help = "show detailed planning info",
        defaultValue = "true"
    ) showPlanning: Boolean = true
): String

Parameters:

• intent: Natural language description of what to do
• open: Run in open mode (choose goal and use all helpful actions)
• showPrompts: Display prompts sent to LLMs
• showLlmResponses: Display LLM responses
• debug: Show debug information
• state: Use existing blackboard state
• toolDelay: Add delay between tool calls
• operationDelay: Add delay between operations
• showPlanning: Show detailed planning information (default: true)

Returns: Formatted execution result with agent process information, output, cost info, and tool statistics

Aliases: execute, x

Usage:

embabel> x "Find news about technology" -p
embabel> execute "Summarize this article" -d --showPrompts

Chat Commands

Start Chat Session

Start an interactive chat session with an agent.

@ShellMethod("Chat")
fun chat(): String

Returns: "Conversation finished" when chat session ends

Behavior:

• Creates a chat session with configured or default chatbot
• Displays welcome message and help information
• Reads user input line by line
• Type "exit" to end session
• Type "/help" for available commands
• If redirectLogToFile is enabled, logs are redirected to file during chat

Usage:

embabel> chat

Options Management Commands

Show Options

Display current execution options.

@ShellMethod("Show options")
fun showOptions(): String

Returns: JSON-formatted string of current process options (excluding blackboard content)

Usage:

embabel> showOptions

Set Options

Configure execution options for subsequent commands.

@ShellMethod("Set options")
fun setOptions(
    @ShellOption(
        value = ["-o", "--open"],
        help = "run in open mode, choosing a goal and using all actions that can help achieve it"
    ) open: Boolean = false,
    @ShellOption(value = ["-t", "--test"], help = "run in help mode") test: Boolean = false,
    @ShellOption(value = ["-p", "--showPrompts"], help = "show prompts to LLMs") showPrompts: Boolean,
    @ShellOption(value = ["-r", "--showResponses"], help = "show LLM responses") showLlmResponses: Boolean = false,
    @ShellOption(value = ["-d", "--debug"], help = "show debug info") debug: Boolean = false,
    @ShellOption(value = ["-s", "--state"], help = "Use existing blackboard") state: Boolean = false,
    @ShellOption(value = ["-td", "--toolDelay"], help = "Tool delay") toolDelay: Boolean = false,
    @ShellOption(value = ["-od", "--operationDelay"], help = "Operation delay") operationDelay: Boolean = false,
    @ShellOption(
        value = ["-s", "--showPlanning"],
        help = "show detailed planning info",
        defaultValue = "true"
    ) showPlanning: Boolean = true
): String

Parameters: Same as execute command

Returns: Confirmation message with updated options

Usage:

embabel> setOptions -p -d

Information Commands

Platform Information

Show AgentPlatform information.

@ShellMethod("Information about the AgentPlatform")
fun platform(): String

Returns: Platform name

Usage:

embabel> platform

Show Blackboard

Show the last blackboard state from a previous operation.

@ShellMethod(
    "Show last blackboard: The final state of a previous operation",
    key = ["blackboard", "bb"]
)
fun blackboard(): String

Returns: Blackboard contents in verbose format, or message if no blackboard available

Aliases: blackboard, bb

Usage:

embabel> bb
embabel> blackboard

Clear Blackboard

Clear the current blackboard state.

@ShellMethod(value = "Clear blackboard")
fun clear(): String

Returns: "Blackboard cleared"

Usage:

embabel> clear

Show Recent Runs

Show recent agent process runs with actual execution history.

@ShellMethod(value = "Show recent agent process runs. This is what actually happened, not just what was planned.")
fun runs(): String

Returns: List of recent runs with goal names, usage/cost information, and execution history

Usage:

embabel> runs

Tool Management Commands

List Tool Groups

List available tool groups.

@ShellMethod("List available tool groups")
fun tools(): String

Returns: Formatted list of available tool groups with metadata

Usage:

embabel> tools

Show Tool Statistics

Display tool usage statistics.

@ShellMethod("Show tool stats")
fun toolStats(): String

Returns: Tool usage statistics in verbose format

Usage:

embabel> toolStats

Model Commands

List Models

List available LLM models.

@ShellMethod("List available models")
fun models(): String

Returns: Formatted list of available models with details

Usage:

embabel> models

System Commands

List Active Profiles

List all active Spring profiles.

@ShellMethod(value = "List all active Spring profiles")
fun profiles(): String

Returns: Comma-separated list of active profile names

Usage:

embabel> profiles

Exit Application

Exit the shell application gracefully.

@ShellMethod(value = "Exit the application", key = ["exit", "quit", "bye"])
fun exit(): String

Returns: "Goodbye!" message

Aliases: exit, quit, bye

Behavior:

• Clears active agent processes
• Performs graceful Spring application shutdown
• Exits with code 0

Usage:

embabel> exit
embabel> quit
embabel> bye

Exception Handling

The shell commands handle several exception types:

import com.embabel.agent.core.NoGoalFound
import com.embabel.agent.core.GoalNotApproved
import com.embabel.agent.core.NoAgentFound
import com.embabel.agent.core.ProcessExecutionStuckException
import com.embabel.agent.core.ProcessExecutionTerminatedException
import com.embabel.agent.core.ProcessWaitingException

• NoGoalFound: When no suitable goal can be found for the intent
• GoalNotApproved: When the chosen goal is not approved
• NoAgentFound: When no suitable agent can be found
• ProcessExecutionStuckException: When the process cannot proceed
• ProcessExecutionTerminatedException: When the process is terminated
• ProcessWaitingException: When the process is waiting for user input (forms, confirmations)

These exceptions are caught and formatted into user-friendly error messages.

Known Issues

Duplicate -s Short Flag

The setOptions method has a bug where both the state and showPlanning parameters use the same -s short flag:

• state parameter: -s / --state
• showPlanning parameter: -s / --showPlanning

This prevents both flags from being used simultaneously via the short form. When using -s, only one of these options can be specified. To work around this issue, use the long form flags (--state and --showPlanning) if you need to specify both options.

This same issue also affects the execute command, which shares the same parameter definitions.