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

> Report bugs or issues in embabel-agent by opening a GitHub issue with a reproducible example and logs. Help us fix problems fast.

- Repository: [Embabel/embabel-agent](https://github.com/embabel/embabel-agent)
- Tags: how-to-guide
- Published: 2026-08-14

---

**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`](https://github.com/embabel/embabel-agent/blob/main/README.md) lines 35-41

Common modules where issues arise include:

- **`embabel-agent-api`** – Core annotations (`@Agent`, `@Goal`, `@Action`) defined in [`Agent.kt`](https://github.com/embabel/embabel-agent/blob/main/Agent.kt)
- **`embabel-agent-rag-core`** – RAG pipeline components including [`TikaHierarchicalContentReader.kt`](https://github.com/embabel/embabel-agent/blob/main/TikaHierarchicalContentReader.kt)
- **`embabel-agent-starter-ollama`** – Ollama integration starters
- **`embabel-agent-shell`** – CLI entry point with interactive commands

Providing the correct [`pom.xml`](https://github.com/embabel/embabel-agent/blob/main/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`](https://github.com/embabel/embabel-agent/blob/main/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:

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

For CLI-based reproduction, use the `--debug` flag available in [`ShellCommands.kt`](https://github.com/embabel/embabel-agent/blob/main/ShellCommands.kt) lines 312-324:

```bash
./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:

```bash

# 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`](https://github.com/embabel/embabel-agent/blob/main/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`](https://github.com/embabel/embabel-agent/blob/main/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`](https://github.com/embabel/embabel-agent/blob/main/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`](https://github.com/embabel/embabel-agent/blob/main/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:

```markdown

## 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
   ```

2. Build the module
   ```bash
   ./mvnw -pl embabel-agent-rag-core test
   ```

3. Run the failing test
   ```bash
   ./mvnw -Dtest=ContentChunkerTest test
   ```

## Expected Behavior

*What should happen*

## Actual Behavior

*Full stack trace or console output*

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

```

## Debug Log

```text
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.