How the Interactive Shell Feature Works in Embabel Agent

Embabel Agent's interactive shell feature provides a Spring Shell-based REPL console that activates when configured via application-shell.yml, allowing developers to execute agent commands from a command prompt without starting a web server.

The Embabel Agent framework includes a built-in interactive shell feature that transforms your agent application into a command-line REPL environment. Powered by Spring Shell, this capability enables developers to interact with agent logic directly from the terminal using custom commands. When activated through specific configuration properties in the embabel.agent.shell.* namespace, the shell bypasses the traditional web server startup and presents an interactive prompt for real-time agent execution.

Core Architecture Components

The interactive shell feature relies on four key components that orchestrate the transition from a standard Spring Boot application to an interactive command environment.

AgentShellProperties

AgentShellProperties serves as the configuration holder for all shell-related settings. Located in the auto-configuration module, this class binds properties prefixed with embabel.agent.shell.* from the environment. It defines flags for exit commands, quit commands, interactive mode, history settings, and critically sets web-application-type=none to prevent embedded server startup.

ShellEnvironmentPostProcessor

ShellEnvironmentPostProcessor implements Spring Boot’s EnvironmentPostProcessor interface to inject shell settings before the application context refreshes. According to the Embabel source code, this processor reads the AgentShellProperties and constructs a high-priority MapPropertySource named shellModeProperties. This property source translates Embabel-specific flags into Spring Shell properties such as spring.shell.command.exit.enabled and spring.shell.interactive.enabled, ensuring the shell beans receive correct configuration during initialization.

AgentShellAutoConfiguration

AgentShellAutoConfiguration provides the Spring Boot auto-configuration that registers shell components when shell mode is detected. This configuration class uses @ComponentScan(basePackages = "com.embabel.agent.shell") to discover command classes and instantiates the core Shell bean along with prompt providers and collaborators required for the REPL interface.

Spring Shell Integration

Spring Shell (via the spring-shell dependency) supplies the actual REPL implementation, including command parsing, prompt display, history management, and termination logic. The Shell bean reads the properties injected by ShellEnvironmentPostProcessor and initiates a prompt loop when spring.shell.interactive.enabled evaluates to true. Commands annotated with @ShellComponent within the com.embabel.agent.shell package become available at the prompt.

Configuration and Startup Flow

Activating the interactive shell feature requires a specific YAML configuration profile and follows a precise initialization sequence.

Enabling Shell Mode

Create an application-shell.yml file in your resources directory with the following structure:

embabel:
  agent:
    shell:
      web-application-type: none          # Prevents web server startup

      command:
        exit-enabled: true                # Enables `exit` command

        quit-enabled: true                # Enables `quit` command

      interactive:
        enabled: true                     # Activates the REPL prompt

Initialization Sequence

When the application boots with this configuration:

1. ShellEnvironmentPostProcessor executes early in the lifecycle, adding the shellModeProperties source to the environment
2. AgentShellAutoConfiguration detects embabel.agent.shell.interactive.enabled=true and registers Spring Shell beans
3. The Shell bean initializes, displaying a prompt (provided by a PromptProvider implementation) and awaiting input
4. User input routes to @ShellComponent methods located in the com.embabel.agent.shell package
5. Termination commands respect the exit-enabled and quit-enabled properties, shutting down the JVM when invoked

Starting the Application

Run your agent with the shell configuration using Maven:

mvn spring-boot:run -Dspring.config.location=classpath:/application-shell.yml

Or execute the packaged JAR:

java -jar my-agent-app.jar --spring.config.location=classpath:/application-shell.yml

Upon successful startup, you will see the Embabel prompt:

embabel>

Creating Custom Shell Commands

Developers extend the interactive shell by creating Spring Shell commands in the scanned package. The following example demonstrates a custom command that delegates to agent functionality:

package com.embabel.agent.shell;

import org.springframework.shell.standard.ShellComponent;
import org.springframework.shell.standard.ShellMethod;

@ShellComponent
public class AgentExecutionCommands {

    @ShellMethod(key = "run", value = "Execute the agent with provided input")
    public String runAgent(String input) {
        // Delegate to your Embabel agent business logic
        return AgentService.process(input);
    }
    
    @ShellMethod(key = "status", value = "Display current agent status")
    public String showStatus() {
        return AgentService.getCurrentStatus();
    }
}

Commands defined with @ShellMethod automatically appear in the shell's help system and become accessible at the embabel> prompt.

Non-Interactive Batch Mode

The interactive shell feature supports headless execution by disabling the REPL. Set interactive.enabled to false in your configuration:

embabel:
  agent:
    shell:
      interactive:
        enabled: false

In this mode, the application runs without displaying a prompt, executing any specified commands immediately and terminating upon completion. This configuration suits CI/CD pipelines and scheduled tasks that require shell command parsing without human interaction.

Summary

• Embabel Agent leverages Spring Shell to provide a REPL environment through the embabel.agent.shell.* property namespace
• ShellEnvironmentPostProcessor injects configuration early by creating a high-priority MapPropertySource named shellModeProperties
• AgentShellAutoConfiguration scans the com.embabel.agent.shell package to register commands and the Shell bean when interactive mode is enabled
• application-shell.yml configures the feature by setting web-application-type=none and interactive.enabled=true
• Custom commands use the @ShellComponent and @ShellMethod annotations to expose agent functionality at the command prompt
• The feature supports both interactive REPL mode and non-interactive batch execution via configuration flags

Frequently Asked Questions

How do I enable the interactive shell feature in Embabel Agent?

Enable the feature by creating an application-shell.yml file with embabel.agent.shell.interactive.enabled=true and web-application-type=none, then start the application with --spring.config.location=classpath:/application-shell.yml. This configuration prevents the web server from starting and initializes the Spring Shell REPL instead.

What controls the exit and quit commands in the shell?

The AgentShellProperties class defines exit-enabled and quit-enabled flags under embabel.agent.shell.command.*. These properties map to Spring Shell's spring.shell.command.exit.enabled and spring.shell.command.quit.enabled settings via the ShellEnvironmentPostProcessor, determining whether typing exit or quit terminates the application.

Can I run Embabel Agent in shell mode without the interactive prompt?

Yes. Set embabel.agent.shell.interactive.enabled=false in your configuration to run in batch mode. This configuration parses and executes commands without displaying the REPL prompt, suitable for automated scripts and headless environments.

Where should I place my custom shell command classes?

Place @ShellComponent classes in the com.embabel.agent.shell package or its subpackages. The AgentShellAutoConfiguration automatically scans this base package during startup, registering any discovered commands with the Spring Shell infrastructure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}