CtrlK
CommunityDocumentationLog inGet started
Tessl Logo

tessl/maven-com-embabel-agent--embabel-agent-shell

Interactive Spring Shell-based command-line interface for the Embabel Agent platform, providing terminal interaction, chat sessions, and agent management commands.

Overview
Eval results
Files

chat-sessions.mddocs/guides/

Chat Sessions Guide

Learn how to create and manage interactive chat sessions with agents.

Interactive Chat from Shell

Starting a Chat

Start a chat session from the shell:

embabel> chat

The chat session:

  • Displays welcome message and help information
  • Prompts with "You: " for input
  • Processes messages through the agent
  • Continues until you type "exit"

Chat Commands

Within a chat session:

You: Hello, how can you help?
Agent: I can assist with...

You: /help
# Shows available commands

You: exit
# Ends the session

Log Management

When redirectLogToFile is enabled, logs are redirected during chat to avoid interfering with the UI:

embabel:
  agent:
    shell:
      redirectLogToFile: true

Logs are written to logs/chat-session.log in your working directory.

Programmatic Chat Sessions

Basic Setup

Create and run a chat session programmatically:

import com.embabel.agent.shell.TerminalServices
import com.embabel.chat.Chatbot
import com.embabel.chat.ChatSession
import org.springframework.stereotype.Component

@Component
class MyChatService(
    private val terminalServices: TerminalServices,
    private val chatbot: Chatbot
) {
    fun startChat() {
        val chatSession = chatbot.createSession()

        val result = terminalServices.chat(
            chatSession = chatSession,
            welcome = "Welcome to my agent chat!",
            colorPalette = DefaultColorPalette()
        )

        println(result)  // "Conversation finished"
    }
}

Custom Welcome Message

Provide a custom welcome message:

val result = terminalServices.chat(
    chatSession = chatSession,
    welcome = """
        Welcome to Customer Support Agent!

        I can help you with:
        - Product information
        - Order status
        - Technical support

        Type 'exit' to end the session.
    """.trimIndent()
)

Custom Color Palette

Use a themed color palette:

import com.embabel.agent.shell.personality.starwars.StarWarsColorPalette

val result = terminalServices.chat(
    chatSession = chatSession,
    welcome = "May the Force be with you!",
    colorPalette = StarWarsColorPalette()
)

Java Interoperability

The chat method is annotated with @JvmOverloads for Java compatibility:

// Java code
TerminalServices terminalServices = ...;
ChatSession chatSession = ...;

// Use defaults
String result = terminalServices.chat(chatSession);

// With welcome message
String result = terminalServices.chat(chatSession, "Welcome!");

// With all parameters
String result = terminalServices.chat(chatSession, "Welcome!", new StarWarsColorPalette());

Managing Chat Session Logs

Redirect Logging to File

Manually control log redirection:

import com.embabel.agent.shell.TerminalServices

val terminalServices: TerminalServices = ...

val restoreLogging = terminalServices.redirectLoggingToFile(
    filename = "my-chat-session",
    dir = System.getProperty("user.dir")
)

try {
    // Run chat with logs redirected
    terminalServices.chat(chatSession)
} finally {
    // Restore original logging
    restoreLogging()
}

Log File Location

Logs are written to:

{dir}/logs/{filename}.log

Example: /Users/me/myapp/logs/my-chat-session.log

Log Format

The log pattern is:

%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n

Example output:

14:23:45.123 [main] INFO  c.e.agent.core.AgentPlatform - Processing user message
14:23:45.456 [main] DEBUG c.e.agent.llm.LLMService - Sending prompt to LLM
14:23:46.789 [main] INFO  c.e.agent.core.AgentPlatform - Response generated

Chat Session Behavior

Session Start

When a session starts:

  1. Welcome message is displayed (if provided)
  2. Session start message with conversation ID
  3. Prompt appears: "You: " (highlighted in color palette)

Message Processing

For each user input:

  1. Input is sent to the chat session
  2. Agent processes the message
  3. Response is displayed
  4. Prompt appears for next input

Session End

Session ends when:

  • User types "exit" (case-insensitive)
  • Chat session terminates
  • Returns "Conversation finished"

Error Handling

If chat session encounters errors:

  • Error message is displayed
  • Session may continue or terminate based on error type
  • User can always type "exit" to force end

Chatbot Configuration

Optional Chatbot

The chatbot is an optional dependency:

@ShellComponent
class ShellCommands(
    // ... other dependencies
    @Autowired(required = false)
    private val chatbot: Chatbot? = null
)

If no Chatbot bean is available:

  • The chat command will not be available
  • Other shell commands work normally

Providing a Chatbot

Implement and register a Chatbot bean:

import com.embabel.chat.Chatbot
import com.embabel.chat.ChatSession
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration

@Configuration
class ChatConfiguration {
    @Bean
    fun chatbot(): Chatbot {
        return object : Chatbot {
            override fun createSession(): ChatSession {
                // Return your chat session implementation
                return MyChatSession()
            }
        }
    }
}

Output Channel Integration

Chat with Output Channel

Combine chat with custom output handling:

import com.embabel.agent.shell.TerminalServices
import com.embabel.agent.api.channel.OutputChannel

@Component
class ChatWithOutputService(
    private val terminalServices: TerminalServices,
    private val agentPlatform: AgentPlatform,
    private val chatbot: Chatbot
) {
    fun startChatWithOutput() {
        // Create output channel for agent communication
        val outputChannel = terminalServices.outputChannel(agentPlatform)

        // Create and configure chat session
        val chatSession = chatbot.createSession()

        // Run chat
        terminalServices.chat(
            chatSession = chatSession,
            welcome = "Chat session with output channel"
        )
    }
}

Handling Chat Events

The output channel handles various event types during chat:

  • MessageOutputChannelEvent: Display messages from agents
  • ContentOutputChannelEvent: Display content events
  • ProgressOutputChannelEvent: Show progress updates with "▶" prefix
  • LoggingOutputChannelEvent: Show log messages with "🪵" prefix

All events are automatically formatted and wrapped according to lineLength configuration.

Advanced Chat Patterns

Multi-Turn Conversations

Chat sessions maintain state across turns:

You: What is the weather in San Francisco?
Agent: The weather in San Francisco is currently 65°F and sunny.

You: What about tomorrow?  # Context from previous turn
Agent: Tomorrow in San Francisco will be 68°F with partly cloudy skies.

Handling Awaitables

Chat automatically handles interactive elements:

  • Confirmation requests: Prompts user for yes/no
  • Form requests: Prompts user to fill out forms
  • Choice requests: Prompts user to select options

These are handled transparently by the terminal services.

Chat with Personality

Configure personality for themed chat experience:

embabel:
  agent:
    logging:
      personality: starwars

The prompt and colors will match the selected personality theme.

Troubleshooting

Chat Command Not Available

If chat command is not available:

  1. Ensure Chatbot bean is registered
  2. Check component scanning includes chatbot configuration
  3. Verify no bean definition errors in startup logs

Logs Interfering with Chat UI

Enable log redirection:

embabel:
  agent:
    shell:
      redirectLogToFile: true

Chat Session Hangs

If chat session hangs:

  1. Check for blocking operations in chat session implementation
  2. Verify LLM service is responding
  3. Enable debug logging to diagnose issues

Unable to Exit Chat

If "exit" doesn't work:

  1. Ensure case-insensitive matching is working
  2. Try Ctrl+C to force exit
  3. Check chat session termination logic

Related Documentation

  • Task Execution: Task Execution Guide
  • Output Handling: Output Handling Guide
  • Customization: Customization Guide
  • Full API: Terminal Services Reference
tessl i tessl/maven-com-embabel-agent--embabel-agent-shell@0.3.0

docs

guides

chat-sessions.md

customization.md

output-handling.md

task-execution.md

examples.md

index.md

quickstart.md

troubleshooting.md

tile.json