Utility Functions

The shell module provides utility functions for formatting agent process output and converting Markdown to ANSI-styled console output.

Imports

import com.embabel.agent.shell.formatProcessOutput
import com.embabel.agent.shell.markdownToConsole

Process Output Formatting

formatProcessOutput

Formats the output of an agent process execution for display in the console.

fun formatProcessOutput(
    result: AgentProcessExecution,
    colorPalette: ColorPalette,
    objectMapper: ObjectMapper,
    lineLength: Int
): String

Parameters:

• result: The AgentProcessExecution result to format
• colorPalette: Color scheme for styling the output
• objectMapper: Jackson ObjectMapper for JSON serialization
• lineLength: Maximum line length for text wrapping

Returns: Formatted string with agent process information, output, cost information, and tool statistics

Behavior:

1. Processes the execution output based on its type:
   • HasContent: Formats content, checks for Markdown (presence of "#"), applies markdown-to-console conversion if detected, otherwise wraps text
   • InternetResources: Appends list of links with URLs and summaries
   • Other types: Pretty-prints as JSON
2. Wraps text according to specified line length
3. Applies color palette for styling
4. Returns formatted string with sections:
   • Agent process information (verbose)
   • User's original request
   • Formatted output
   • Cost information (verbose)
   • Tool statistics (verbose)

Output Format:

|
|{agent process info}
|
|You asked: {basis}
|
|{formatted output}
|
|{cost info}
|{tool statistics}
|

Usage:

import com.embabel.agent.shell.formatProcessOutput
import com.embabel.agent.api.common.autonomy.AgentProcessExecution
import com.embabel.agent.spi.logging.ColorPalette
import com.fasterxml.jackson.databind.ObjectMapper

val result: AgentProcessExecution = ... // from execution
val colorPalette: ColorPalette = ... // injected
val objectMapper: ObjectMapper = ... // injected
val lineLength: Int = 140

val formatted = formatProcessOutput(
    result = result,
    colorPalette = colorPalette,
    objectMapper = objectMapper,
    lineLength = lineLength
)

println(formatted)

Markdown to Console Conversion

markdownToConsole

Converts Markdown text to ANSI-styled console output with colors and formatting.

fun markdownToConsole(md: String): String

Parameters:

• md: Markdown text to convert

Returns: String with ANSI escape codes for styled console output

Supported Markdown Features:

Text Styling

• Bold: **text** → Bold text (ANSI code: \u001B[1m)
• Italic: *text* → Italic text (ANSI code: \u001B[3m)
• Underline: __text__ → Underlined text (ANSI code: \u001B[4m)
• Strikethrough: ~~text~~ → Strikethrough text (ANSI code: \u001B[9m)

Block Elements

• Blockquote: > text → Italic, blue, bold text
• Code Blocks: ```language\ncode\n``` → Language in italic bold, code in black on gray background
• Inline Code: `code` → Black text on gray background

Headers

• ATX Headers: # text, ## text, etc. → Cyan bold text
• Setext Headers (underlined with =): text\n=== → Cyan bold text
• Setext Headers (underlined with -): text\n--- → Cyan bold text

Lists

• Numbered Lists: 1. item → Magenta bold number, regular text
• Bulleted Lists: - item or * item → Magenta bold bullet, regular text

Links and Images

• Links: [text](url) → Blue text, blue underlined URL in parentheses
• Images: ![alt](url) → Blue alt text, blue underlined URL in parentheses

ANSI Color Codes Used:

• Bold: \u001B[1m
• Italic: \u001B[3m
• Underline: \u001B[4m
• Strikethrough: \u001B[9m
• Blue: \u001B[34m
• Magenta: \u001B[35m
• Cyan: \u001B[36m
• Black on gray: \u001B[57;107m
• Reset: \u001B[0m, \u001B[22m

Usage:

import com.embabel.agent.shell.markdownToConsole

val markdown = """
# Welcome to the Agent

This agent can:
- **Execute** tasks
- *Analyze* data
- Generate `code`

> Important: Always verify results

Visit [Documentation](https://example.com) for more info.
""".trimIndent()

val styled = markdownToConsole(markdown)
println(styled)

Example Input and Output:

Input:

# Agent Report

The agent found **3 results**:
1. Item one
2. Item two
3. Item three

See `agent.log` for details.

Output (with ANSI codes):

[Cyan Bold]# Agent Report[Reset]

The agent found [Bold]3 results[Reset]:
[Magenta Bold]1.[Reset] Item one
[Magenta Bold]2.[Reset] Item two
[Magenta Bold]3.[Reset] Item three

See [Black on Gray]agent.log[Reset] for details.

Integration with formatProcessOutput:

The formatProcessOutput function automatically uses markdownToConsole when it detects Markdown content (presence of "#" character) in HasContent output:

if (hasContentOutput.content.contains("#")) {
    markdownToConsole(hasContentOutput.content)
} else {
    hasContentOutput.content
}

Regex Patterns Used:

The function uses regex patterns to match Markdown syntax:

• Bold: \\*\\*(.*?)\\*\\*
• Italic: \\*(.*?)\\*
• Underline: __(.*?)__
• Strikethrough: ~~(.*?)~~
• Blockquote: (> ?.*)
• Lists: ([\\d]+\\.|-|\\*) (.*)
• Code blocks: (?s)\``(\w+)?\n(.*?)\n````
• Inline code: `(.*?)`
• Headers: (#{1,6}) (.*?)\\n
• Links/Images: !?\\[(.*?)]\\((.*?)\\)

Attribution:

This function is based on work by Guillaume Laforge (https://glaforge.dev/posts/2025/02/27/pretty-print-markdown-on-the-console/).

Limitations:

• Simple regex-based parsing, may not handle all edge cases
• Nested formatting may not work correctly
• No support for tables, definition lists, or other advanced Markdown features
• Code block language highlighting is minimal (just shows language name in italic bold)