Release adk-agui-middleware

[DennySORA]

Hello,

On behalf of my company, I have open-sourced adk-agui-middleware. I would like to ask if it could be listed in your README as part of third-party support. I will continue to actively develop and maintain it.

The functionality is already stable, although some usage tips have not yet been fully documented. I will be adding those later, and the project already includes support for History.

If you have any suggestions for improvements, I would be glad to hear them and make enhancements. Thank you for your consideration.

adk-agui-middleware
pypi

---

🚀 ADK AGUI Middleware v1.0.0 - Major Release

Release Date: January 2025Python Version: 3.13+

First major release of ADK AGUI Middleware - a professional Python library that bridges Agent Development Kit (ADK) with
AGUI protocol for real-time agent interactions via Server-Sent Events.

---

✨ Key Features

Real-Time Agent Streaming

• Server-Sent Events (SSE) support for live agent responses
• Seamless ADK to AGUI event translation
• Complete streaming message lifecycle management

Human-in-the-Loop (HITL) Workflows

• Advanced HITL pattern implementation
• Intelligent tool call management with human approval
• Pending action tracking and state persistence

Session Management

• Multi-tenant architecture support
• Session locking with configurable timeouts
• JSON Patch support for incremental state updates
• Complete conversation history management

Professional Architecture

• Extensible event processing pipeline
• Comprehensive error handling and logging
• Graceful shutdown and resource cleanup
• Structured audit trails

---

🏗️ Core Components

• SSEService: Primary agent execution and streaming service
• SessionManager: Session lifecycle and state management
• EventTranslator: ADK to AGUI event conversion engine
• HistoryService: Conversation history and retrieval
• HITL Handlers: Human intervention workflow management

---

🛠️ Technical Highlights

• Python 3.13 compatibility with modern async/await
• Pydantic v2 for robust data validation
• FastAPI integration ready
• Structured JSON logging with configurable levels
• Type hints throughout for excellent IDE support
• 100% docstring coverage for all APIs

---

📋 API Endpoints

• POST / - Agent execution with SSE streaming
• GET /thread/list - List user conversations
• DELETE /thread/{thread_id} - Delete conversation
• GET /state_snapshot/{thread_id} - Get session state
• PATCH /state/{thread_id} - Update session state
• GET /message_snapshot/{thread_id} - Get conversation history

---

🔧 Configuration

Session Locking

• Configurable timeout and retry logic
• Concurrent access protection
• Automatic cleanup of expired locks

Logging

• Structured JSON output
• Configurable log levels
• Optional raw event debugging

Multi-Tenant Support

• Flexible app/user/session context extraction
• Pluggable service configuration
• Customizable endpoint paths

---

📚 Documentation

• Complete API documentation with examples
• HITL workflow implementation guide
• Configuration reference
• Professional docstrings for all functions and classes

---

🔄 Getting Started

pip install adk-agui-middleware

Ready for production use with comprehensive documentation and professional-grade architecture.

Welcome to ADK AGUI Middleware v1.0.0! 🎉

[boyangsvl]

Thank you for the contribution! I will move this to Issues so someone can take a look and work on this.

[DennySORA]

Thank you very much!

I implemented the following:

1. Fully redesigned and rewrote the system on top of the original contextablemark codebase.
2. Fixed logic bugs that in some cases prevented data from being sent.
3. Added APIs:
   • get_agui_thread_list: retrieve multiple conversations.
   • delete_agui_thread: delete a conversation.
   • patch_agui_state: update state, such as the title.
   • get_agui_message_snapshot: fetch historical messages.
   • get_agui_state_snapshot: fetch backend state to keep frontend and backend in sync.
4. Introduced a middleware plugin layer. Processing is scoped to a single “dialog state.” Each request instantiates a class with a lifecycle, allowing temporary storage and event aggregation, with conversions such as:
   • ADK → ADK: e.g., event_filter to drop ADK events before dispatch.
   • ADK → AGUI: handle A2A-origin content, custom transforms, or batch ADK events and have AI summarize them into a Thinking payload before emitting; convert specific ADK events to AGUI.
   • AGUI → AGUI: post-process and mutate already-converted AGUI payloads.
   • Timeout handling: special logic when a timeout occurs.
   • https://github.com/trendmicro/adk-agui-middleware/blob/main/src/adk_agui_middleware/data_model/context.py
   • https://github.com/trendmicro/adk-agui-middleware/blob/main/src/adk_agui_middleware/data_model/config.py
   • https://github.com/trendmicro/adk-agui-middleware/blob/main/src/adk_agui_middleware/base_abc/handler.py
   • 
5. Provided a lock abstraction (default: in-memory). You can swap in Redis, configure retries, etc. The original contextablemark code kept heavy in-memory state and could not run cleanly across multiple k8s pods; cross-pod execution triggered many issues. This abstraction resolves that.
6. Added an input/output logging plugin. If you use something like Langfuse or have an external history system, integrate it here. Each request still gets its own lifecycle class.
7. The I/O logging plugin can also capture the final outbound result and transform it. For example, if an error is about to be emitted, intercept it and map it to a specific error code not visible to end users.
8. Extraction of app_name, user_id, session_id, and extract_initial_state no longer relies only on RunAgentInput. The raw request is also passed in so headers can be read and transformed.
9. Added a plugin to mutate incoming AGUI input. It receives the pending name and id and can perform special transforms, such as converting certain user messages into tool messages routed to ADK long-running tools. (This supports our special design.)
10. Code adheres strictly to SOLID. Functions are small and simple. You can subclass and override targeted methods to meet custom needs.
11. Comprehensive typing with strict mypy settings for near-static verification.
12. A rich utils module with many conversion helpers.
13. Support for ThinkingMessage and Thinking Mode, plus a fix for the official SSE event encoder that was not spec-compliant.
    • https://github.com/trendmicro/adk-agui-middleware/blob/main/src/adk_agui_middleware/event/agui_event.py
14. Completely reworked the contextablemark “human-in-the-loop” mechanism to use efficient long-running tools.
15. Multiple performance wins and simplified control flow.

To address this, we completed the entire middleware layer, and after discussion, decided to open source it. We also plan to maintain it long-term.

Thank you for your question, and we hope this will help more people in the future.

[dylan-apex]

Will test this out - had some issues with the official ag-ui implementation that I hope this will fix (re memory issues).

If this works well, I do think it would be useful to add in the docs a 'How to deploy for production' example with an AG-UI frontend and this as the middlware.

[DennySORA]

Thank you.
If you encounter any issues, please feel free to open an issue and I will fix it as soon as possible.

[trend-denny-lee]

Is there any issue with using my middleware at the moment? Feel free to report it.

[surajksharma07]

Really appreciate the detailed writeup and for following through with the full rewrite, plugin layer and HITL work Denny. This ended up getting triaged in #3023 where the suggestion was to list adk-agui-middleware over in the adk-python-community repo rather than the core README, hope that path still works for you and gets it in front of more people. Closing this one out since the follow-up already happened there, really appreciate you open-sourcing it and sticking around to help others in the thread.