GenAI-powered agent for Zammad

Zammad-AI is a Python-based microservice that integrates Generative AI capabilities into the Zammad ticketing system. It operates as an event-driven service, listening to ticket events via Kafka and generating AI-assisted responses.

• Event-Driven Architecture: Built with FastStream and Kafka for robust message processing.
• AI-Powered Triage: Classifies tickets and applies automated actions based on configurable rules.
• Vector Database Support: Uses Qdrant for knowledge retrieval via semantic search.
• Full Observability: Integration with Langfuse for tracing, cost monitoring, and dynamic prompt management.
• Zammad Integration: Supports both REST API and custom EAI integration paths.
• Secure Communication: Supports mTLS for secure Kafka connections using truststore.
• Modern Stack: Powered by Python 3.13, Pydantic, and LangChain.

Detailed documentation is available in the docs/ folder:

• Architecture (ADRs): Explore the technical decisions and system design.
• Software Components: Details on Kafka, Triage, Zammad integration, and Qdrant.
• Configuration Guide: How to set up the service and manage secrets.
• REST API Reference: Documentation for the FastAPI endpoints.

1. Ingest: Listens to the Kafka topic or receives synchronous REST API requests.
2. Triage: Analyzes input using GenAI to determine category, reasoning, and next steps.
3. Action: Evaluates triggers (conditions) to execute specific tasks (e.g., generate a response).
4. Integration: Interacts with Zammad to fetch ticket context or post final results.

• Python: 3.13+
• Package Manager: uv
• Docker: For running the local development stack.

The service is highly configurable via YAML, environment variables, and .env files. For a full list of settings and examples, please refer to the Configuration Guide.

Example config.yaml:

kafka:
  broker_url: "localhost:9092"
  topic: "ticket-events"

valid_request_types:
  - "general_inquiry"
  - "support"

Start the local Kafka broker, Zookeeper, and Mailpit using Docker Compose:

docker compose up -d

• Kafka UI: http://localhost:8089
• Mailpit: http://localhost:8025

Use uv to install the project dependencies:

uv sync

Run the application:

uv run python zammad-ai/main.py

The service can mount a Gradio frontend at / for local developer workflows.

In zammad-ai/config.yaml:

frontend:
  enabled: true
  request_timeout_seconds: 30.0
  auth_username: "admin"
  auth_password: "change-me"

Then start the service and open:

• Frontend UI: http://localhost:8080/
• OpenAPI docs (development mode): http://localhost:8080/api/docs

When frontend mode is enabled, basic auth is required.

Run the test suite using pytest:

uv run pytest

The project uses ruff for linting and formatting.

Check for issues:

uv run ruff check .

Format code:

uv run ruff format .

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please open an issue with the tag "enhancement", fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Open an issue with the tag "enhancement"
2. Fork the Project
3. Create your Feature Branch (git checkout -b feature/AmazingFeature)
4. Commit your Changes (git commit -m 'Add some AmazingFeature')
5. Push to the Branch (git push origin feature/AmazingFeature)
6. Open a Pull Request

More about this in the CODE_OF_CONDUCT file.

Distributed under the MIT License. See LICENSE file for more information.

it@M - opensource@muenchen.de