CtrlK

Community Documentation Log in Get started

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

Task Execution Guide

Name: tessl/maven-com-embabel-agent--embabel-agent-shell
Author: tessl

Learn how to execute tasks using the Embabel Agent Shell.

Interactive Task Execution

Basic Execution

Execute a task from the shell:

embabel> execute "Find news about technology"
embabel> x "Summarize this article"  # Short alias

Execution Options

Control execution behavior with flags:

# Show prompts sent to LLMs
embabel> x "Find news" -p

# Show debug information
embabel> x "Find news" -d

# Show LLM responses
embabel> x "Find news" -r

# Combine flags
embabel> x "Find news" -p -d -r

# Run in open mode (choose goal and use all helpful actions)
embabel> x "Find news" -o

# Use existing blackboard state
embabel> x "Find news" --state

# Add delays for debugging
embabel> x "Find news" --toolDelay --operationDelay

# Hide planning information
embabel> x "Find news" --showPlanning false

Flag Reference

Short	Long	Description	Default
`-o`	`--open`	Run in open mode	false
`-p`	`--showPrompts`	Show prompts to LLMs	false
`-r`	`--showResponses`	Show LLM responses	false
`-d`	`--debug`	Show debug info	false
`-s`	`--state`	Use existing blackboard	false
`-td`	`--toolDelay`	Add tool call delays	false
`-od`	`--operationDelay`	Add operation delays	false
`-P`	`--showPlanning`	Show planning info	true

Note: The -s flag conflicts with --showPlanning. Use long form flags (--state and --showPlanning) if you need both.

Programmatic Task Execution

Basic Usage

Execute tasks programmatically:

import com.embabel.agent.shell.ShellCommands
import com.embabel.agent.api.common.autonomy.Autonomy

@Component
class MyService(
    private val shellCommands: ShellCommands
) {
    fun executeTask(intent: String) {
        val result = shellCommands.execute(
            intent = intent,
            open = false,
            showPrompts = false,
            showLlmResponses = false,
            debug = false,
            state = false,
            toolDelay = false,
            operationDelay = false,
            showPlanning = true
        )
        println(result)
    }
}

Using Autonomy API Directly

For more control, use the Autonomy API:

import com.embabel.agent.api.common.autonomy.Autonomy
import com.embabel.agent.api.common.autonomy.AgentProcessExecution
import com.embabel.agent.api.common.autonomy.ProcessOptions
import com.embabel.agent.shell.TerminalServices
import org.springframework.stereotype.Component

@Component
class MyService(
    private val autonomy: Autonomy,
    private val terminalServices: TerminalServices,
    private val agentPlatform: AgentPlatform
) {
    fun executeWithCustomOptions(intent: String): AgentProcessExecution {
        val processOptions = ProcessOptions(
            open = false,
            showPrompts = true,
            showLlmResponses = false,
            debug = false,
            toolDelay = false,
            operationDelay = false,
            showPlanning = true,
            blackboard = null
        )

        val goalSeeker = autonomy.createGoalSeeker(
            intent = intent,
            agentScope = agentPlatform,
            goalChoiceApprover = terminalServices,
            goalSelectionOptions = GoalSelectionOptions()
        )

        val outputChannel = terminalServices.outputChannel(agentPlatform)

        return goalSeeker.achieve(
            processOptions = processOptions,
            outputChannel = outputChannel
        )
    }
}

Managing Execution State

View Blackboard

The blackboard stores state from previous operations:

# View current blackboard
embabel> blackboard
embabel> bb  # Short alias

# Clear blackboard
embabel> clear

Reuse State

Use --state flag to reuse the previous blackboard:

embabel> x "Find news about AI" -p
embabel> x "Summarize the results" --state  # Reuses previous blackboard

View Recent Runs

See execution history:

embabel> runs

Output includes:

Goal names
Usage and cost information
Actual execution history (not just planning)

Setting Default Options

Configure default execution options:

# Set options for all subsequent executions
embabel> setOptions -p -d

# View current options
embabel> showOptions

The setOptions command accepts the same flags as execute.

Handling Execution Errors

Common Exceptions

The shell handles these exceptions gracefully:

NoGoalFound: No suitable goal found for the intent
GoalNotApproved: User declined goal approval
NoAgentFound: No suitable agent found
ProcessExecutionStuckException: Process cannot proceed
ProcessExecutionTerminatedException: Process was terminated
ProcessWaitingException: Process waiting for user input

Error Responses

Errors are formatted as user-friendly messages:

embabel> x "impossible task"
Error: No goal found for intent: impossible task

Interactive Approval

When goal approval is required:

embabel> x "Find sensitive information"
Do you approve this goal: Search for sensitive data? (y/n): n
Error: Goal not approved by user

Output Formatting

Process Output Format

Execution results include:

Agent Process Info (verbose mode):
- Process ID
- Agent details
- Goal information
User Request:
```
You asked: {original intent}
```
Formatted Output:
- Markdown content converted to ANSI-styled console output
- Text wrapped to configured line length
- JSON pretty-printed for structured data
Cost Information (verbose mode):
- Token usage
- API costs
- Model information
Tool Statistics (verbose mode):
- Tool call counts
- Execution times

Customizing Output

Configure line length in application.yaml:

embabel:
  agent:
    shell:
      lineLength: 120  # Default: 140

Advanced Execution Patterns

Goal Selection

Test goal selection without full execution:

embabel> chooseGoal "Find news about technology"

This shows:

All goal rankings
Chosen goal information
No actual execution

Open Mode

In open mode, the system:

Automatically chooses an appropriate goal
Uses all available actions that can help achieve it
Provides more flexibility in problem-solving

embabel> x "Help me with my task" -o

Debugging Execution

Enable all debug options:

embabel> x "Complex task" -p -r -d --toolDelay --operationDelay

This shows:

All prompts sent to LLMs (-p)
All LLM responses (-r)
Debug information (-d)
Delays between operations for inspection

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

task-execution.mddocs/guides/

Task Execution Guide

Interactive Task Execution

Basic Execution

Execution Options

Flag Reference

Programmatic Task Execution

Basic Usage

Using Autonomy API Directly

Managing Execution State

View Blackboard

Reuse State

View Recent Runs

Setting Default Options

Handling Execution Errors

Common Exceptions

Error Responses

Interactive Approval

Output Formatting

Process Output Format

Customizing Output

Advanced Execution Patterns

Goal Selection

Open Mode

Debugging Execution

Related Documentation

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

task-execution.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/guides/

Task Execution Guide

Interactive Task Execution

Basic Execution

Execution Options

Flag Reference

Programmatic Task Execution

Basic Usage

Using Autonomy API Directly

Managing Execution State

View Blackboard

Reuse State

View Recent Runs

Setting Default Options

Handling Execution Errors

Common Exceptions

Error Responses

Interactive Approval

Output Formatting

Process Output Format

Customizing Output

Advanced Execution Patterns

Goal Selection

Open Mode

Debugging Execution

Related Documentation

task-execution.mddocs/guides/