Build and maintain a minimalist financial agent with LangGraph orchestration, Redis message buffering, PostgreSQL conversation persistence, and Chatwoot integration. Handles webhook processing, message debouncing, agent tools, and graceful fallback patterns.
This skill guides you through building and maintaining a minimalist financial agent that uses LangGraph for agent orchestration, Redis for message buffering with debouncing, and PostgreSQL for conversation persistence, all integrated with Chatwoot.
The system consists of:
1. **LangGraph StateGraph** (`app/agent/graph.py`) - Agent orchestration using state machines
2. **Message Buffer** (`app/services/message_buffer.py`) - Redis-based debouncing with 20-second sliding window
3. **Webhook Handler** (`app/api/chatwoot.py`) - Validates and processes Chatwoot webhooks asynchronously
4. **Chatwoot Service** (`app/services/chatwoot_service.py`) - API client for sending messages
5. **Tools** (`app/agent/tools.py`) - LangChain tools available to the agent
**Using Docker (Recommended):**
```bash
docker-compose up -d # Start all services
docker-compose logs -f app # View application logs
docker-compose logs app | grep ERROR # View only errors
docker-compose restart postgres redis # Restart dependencies
docker-compose down # Stop all services
```
**Local Development:**
```bash
source venv/bin/activate # Activate virtual environment
python -m app.main # Run the application
```
1. **Incoming Message**: Chatwoot webhook → FastAPI endpoint
2. **Validation**: Check event type (`message_created`), message type (`incoming`), conversation status (`pending`), contact info
3. **Buffering**: Add to Redis buffer, start/reset debounce timer (20s sliding window)
4. **Aggregation**: After debounce period, concatenate all buffered messages with `\n\n`
5. **Agent Processing**:
- Convert to LangChain messages
- Invoke StateGraph with conversation persistence (`thread_id = chatwoot_conv_{conversation_id}`)
- Agent decides: call tools, split message, or end
6. **Message Splitting**: If response > 200 chars, use LLM with structured output to split intelligently
7. **Response Extraction**: Extract ONLY assistant messages since last user message (critical for avoiding duplicates)
8. **Sending**: Send messages to Chatwoot with 1-second delay between parts
All settings are in `app/config.py` and controlled via environment variables:
**Required:**
**Common Modifications:**
Tools are defined in `app/agent/tools.py`. Use the `@tool` decorator from LangChain:
```python
from langchain_core.tools import tool
@tool
def my_new_tool(param: str) -> str:
"""
Brief description of what the tool does.
Args:
param: Description of parameter
Returns:
Description of return value
"""
# Implementation here
return result
TOOLS = [
get_current_time,
get_random_number,
calculate,
my_new_tool, # Add here
]
```
The agent automatically gains access to new tools - no other changes needed.
**Manual Webhook Testing:**
```bash
curl -X POST http://localhost:8000/api/v1/chatwoot/webhook \
-H "Content-Type: application/json" \
-d '{
"event": "message_created",
"conversation": {"id": 1, "status": "pending"},
"sender": {"id": 1, "type": "contact"},
"content": "test message",
"message_type": "incoming"
}'
```
**Buffer Management:**
```bash
curl http://localhost:8000/api/v1/chatwoot/buffer/stats/123
curl -X DELETE http://localhost:8000/api/v1/chatwoot/buffer/clear/123
```
**Graph Compilation:**
**Message Buffer Fallback:**
**Message Extraction (CRITICAL):**
**Attachment Handling:**
**Conversation Status:**
**PostgreSQL (conversation persistence):**
**Redis (message buffer):**
**Agent not responding:**
1. Check conversation status (must be `"pending"`)
2. Check logs: `docker-compose logs -f app`
3. Verify Redis/PostgreSQL health: `docker-compose ps`
**Messages duplicating:**
**Buffer not working:**
All failures are logged but don't block user experience:
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/langgraph-chatwoot-financial-agent/raw