how-to-guide

How to Report a Bug or Issue in the Embabel Agent Framework: A Complete Guide

August 14, 2026 embabel/embabel-agent ↗

Open a GitHub Issue with a minimal reproducible example, complete environment details, and debug logs to get bugs in embabel-agent triaged and fixed quickly.

The Embabel Agent Framework is a multi-module Maven/Gradle project that provides Spring Boot-compatible libraries for building AI-augmented agents on the JVM. Because the codebase spans numerous sub-projects—such as embabel-agent-api, embabel-agent-rag-core, and embabel-agent-observability—bugs can surface anywhere from the core planning engine to a specific starter or integration test. Reporting issues effectively requires understanding the monorepo structure and providing maintainers with precise, actionable information.

Step 1: Identify the Affected Module

The embabel-agent repository uses a multi-module Maven layout. Before opening an issue, determine which module contains the bug by examining your stack trace or failing test.

Look for package prefixes like com.embabel.agent.rag or com.embabel.agent.shell
Cross-reference with the module structure documented in README.md lines 35-41

Common modules where issues arise include:

embabel-agent-api – Core annotations (@Agent, @Goal, @Action) defined in Agent.kt
embabel-agent-rag-core – RAG pipeline components including TikaHierarchicalContentReader.kt
embabel-agent-starter-ollama – Ollama integration starters
embabel-agent-shell – CLI entry point with interactive commands

Providing the correct pom.xml path helps maintainers assign the right code owners.

Step 2: Gather Complete Environment Details

Reproducibility is the biggest barrier to fixing bugs. Document your environment precisely as shown in README.md lines 31-34:

Detail to Record	Example Value
embabel-agent version	0.3.0 or latest snapshot
Java version	21 (OpenJDK)
Spring Boot version	3.2.x
Build tool	Maven 3.9.6 or Gradle 8.5
Operating system	Ubuntu 22.04, macOS 14, etc.

Version mismatches often explain apparent bugs. Verify your dependency against the Maven Central snippet in the repository README.

Step 3: Create a Minimal Reproducible Example

The issue tracker prefers self-contained examples that maintainers can run locally. Your reproduction should isolate the behavior without requiring your full application stack.

Options for reproducible examples:

Unit test – A failing test case in the relevant module's test directory
Shell command – Interactive reproduction using the built-in CLI
Minimal starter project – A small GitHub repo that demonstrates the issue

For CLI-based reproduction, use the --debug flag available in ShellCommands.kt lines 312-324:

./mvnw -pl embabel-agent-shell spring-boot:run

# Then in the shell

agent --debug run "your test prompt"

This flag enables debug logging that captures internal state like planning loops and tool invocations.

Step 4: Capture Logs and Stack Traces

Include complete exception stacks and relevant debug output. Partial traces or summarized errors often omit the critical clue.

To enable debug logging:


# For shell commands

agent --debug <command>

# For tests

./mvnw -Dlogging.level.com.embabel.agent=DEBUG test

Debug logs reveal internal framework state that is otherwise invisible. Paste the full output as code blocks, not screenshots.

Step 5: Describe Expected vs. Actual Behavior

Write clear, contrasting statements that make regressions obvious:

Expected: "The RAG pipeline should return a non-empty list of chunks for any text file under 10MB"
Actual: "Empty list returned with no error; debug shows Tika parser silently skipping .docx files"

Reference the "Quick Start" section in README.md lines 59-66 to align your expectations with documented intended usage.

Step 6: Use GitHub Issue Labels

Apply tags that drive triage dashboards:

Module tags: module:rag-core, module:shell, module:api
Type: bug
Severity: high, medium, low

These labels help maintainers filter and prioritize issues efficiently.

Step 7: Link Directly to Source Locations

Reference exact files and line numbers using GitHub's line-anchored URLs (?plain=1#L123). Direct links let reviewers jump straight to relevant code.

Example citations:

embabel-agent-api/src/main/kotlin/com/embabel/agent/api/Agent.kt – Core annotation definitions
embabel-agent-rag/embabel-agent-rag-tika/src/main/kotlin/com/embabel/agent/rag/ingestion/TikaHierarchicalContentReader.kt – Content ingestion bug suspected at line 162
embabel-agent-shell/src/main/kotlin/com/embabel/agent/shell/ShellCommands.kt – CLI command handling

Ready-to-Use Issue Template

Copy and adapt this template for consistent, complete bug reports:


## Summary

<!-- One-sentence description of the problem -->

## Embabel Version

- **embabel-agent version:** 0.3.0 (or snapshot)
- **Java:** 21 (OpenJDK)
- **Spring Boot:** 3.2.x
- **Build tool:** Maven 3.9.6

## Module

`embabel-agent-rag-core` *(replace with relevant module)*

## Reproduction Steps

1. Clone the repository
   ```bash
   git clone https://github.com/embabel/embabel-agent.git
   cd embabel-agent

Build the module
```
./mvnw -pl embabel-agent-rag-core test
```
Run the failing test
```
./mvnw -Dtest=ContentChunkerTest test
```

Expected Behavior

What should happen

Actual Behavior

Full stack trace or console output

java.lang.IllegalArgumentException: ...
    at com.embabel.agent.rag.ingestion.ContentChunker....

Debug Log

2026-08-14 12:34:56.789  DEBUG ... - Created input directory: /tmp/...
2026-08-14 12:34:57.001  DEBUG ... - Parsed file: …

Environment

OS: Ubuntu 22.04
Docker: 24.0 (if using Ollama starter)

Possible Root Cause

embabel-agent-rag-core/src/main/kotlin/com/embabel/agent/rag/ingestion/TikaHierarchicalContentReader.kt line 162

Additional Context

Related issues or PRs
Recent pom.xml changes

Thanks for helping improve Embabel!


## Where to Submit Your Issue

Open issues at the official tracker: **https://github.com/embabel/embabel-agent/issues**

All discussion stays in the GitHub tracker where maintainers actively monitor. Avoid splitting conversation across email, Discord, or other channels.

## Following Up After Submission

Engaged reporters see faster resolution:

- Respond promptly to clarification requests
- Add additional logs or reproduction steps as discovered
- Submit a fix branch if you identify the solution

Review [`CODE_OF_CONDUCT.md`](https://github.com/embabel/embabel-agent/blob/main/CODE_OF_CONDUCT.md) before participating to ensure respectful, constructive communication.

## Summary

- **Identify the module** using stack traces and the monorepo structure in [`README.md`](https://github.com/embabel/embabel-agent/blob/main/README.md)
- **Document environment** completely: Java, Spring Boot, Maven/Gradle, and embabel-agent versions
- **Create minimal reproductions** as unit tests, shell commands with `--debug`, or isolated starter projects
- **Capture full logs** including debug output from [`ShellCommands.kt`](https://github.com/embabel/embabel-agent/blob/main/ShellCommands.kt) or configured loggers
- **Contrast expected vs. actual behavior** clearly and concisely
- **Link source locations** precisely using GitHub's line-anchored URLs
- **Submit to https://github.com/embabel/embabel-agent/issues** and remain engaged for follow-up questions

## Frequently Asked Questions

### What information is most critical for embabel-agent bug reports?

**Environment details and minimal reproduction** matter most. The multi-module structure means a bug in `embabel-agent-rag-core` requires different expertise than one in `embabel-agent-shell`. Precise version numbers (from [`README.md`](https://github.com/embabel/embabel-agent/blob/main/README.md) lines 31-34) and runnable code eliminate back-and-forth clarification cycles.

### How do I enable debug logging in the Embabel shell?

Pass the `--debug` flag to any shell command. As implemented in [`ShellCommands.kt`](https://github.com/embabel/embabel-agent/blob/main/ShellCommands.kt) lines 312-324, this flag increases log verbosity to capture planning loops, tool invocations, and internal state transitions. For programmatic use, set `logging.level.com.embabel.agent=DEBUG` in your `application.properties`.

### Where are the core API definitions located that I should reference?

Core annotations like `@Agent`, `@Goal`, and `@Action` are defined in [`embabel-agent-api/src/main/kotlin/com/embabel/agent/api/Agent.kt`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-api/src/main/kotlin/com/embabel/agent/api/Agent.kt). When reporting bugs involving agent lifecycle or goal planning, link to this file and the specific annotation usage in your code.

### What if I'm unsure which module contains the bug?

Start with your stack trace—look for the deepest `com.embabel.agent.*` package prefix. If ambiguity remains, open the issue against `embabel-agent-core` with your best guess and maintainers will retag during triage. Include the complete dependency tree from `./mvnw dependency:tree` to help locate the relevant module.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:

curl -s "https://instagit.com/install.md"

Add to your MCP client configuration:

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

Ask your agent:

"Use Instagit MCP to understand how embabel/embabel-agent works."

Works with

Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →