{"id":48331162,"url":"https://github.com/langwatch/bank-example","last_synced_at":"2026-04-05T01:05:17.972Z","repository":{"id":337844197,"uuid":"1060045269","full_name":"langwatch/bank-example","owner":"langwatch","description":null,"archived":false,"fork":false,"pushed_at":"2026-02-11T15:24:30.000Z","size":304,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-11T23:56:36.265Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/langwatch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-19T09:58:27.000Z","updated_at":"2026-01-08T11:47:10.000Z","dependencies_parsed_at":null,"dependency_job_id":"fe79adf3-87b2-4902-ae99-ff76514298bf","html_url":"https://github.com/langwatch/bank-example","commit_stats":null,"previous_names":["langwatch/bank-example"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/langwatch/bank-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/langwatch%2Fbank-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/langwatch%2Fbank-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/langwatch%2Fbank-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/langwatch%2Fbank-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/langwatch","download_url":"https://codeload.github.com/langwatch/bank-example/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/langwatch%2Fbank-example/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31420789,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T00:25:07.052Z","status":"ssl_error","status_checked_at":"2026-04-05T00:25:05.923Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-05T01:05:17.728Z","updated_at":"2026-04-05T01:05:17.950Z","avatar_url":"https://github.com/langwatch.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bank Customer Support Agent System\n\nA comprehensive AI-powered customer support system for banking services, built with **Agno** and tested with **Scenario**. This project demonstrates advanced multi-agent coordination, tool calling, and end-to-end conversation testing.\n\n## 🎯 Project Overview\n\nThis system replicates a real-world bank customer support platform with multiple specialized AI agents working together to provide comprehensive customer service. It showcases:\n\n- **Multi-agent architecture** with specialized agents for different tasks\n- **Tool calling correctness** - ensuring the right tools are called at the right time\n- **Rich customer experiences** with personalized data insights\n- **Comprehensive testing** with Scenario for agent behavior validation\n\n## 🏗️ Architecture\n\n### Main Support Agent\nThe central coordinator that handles customer interactions and delegates to specialized agents when needed.\n\n### Specialized Agents\n\n1. **Summary Agent** 📊\n   - Analyzes conversation threads\n   - Provides sentiment analysis\n   - Identifies key issues and urgency levels\n   - Suggests actions for support teams\n\n2. **Next Message Agent** 💬\n   - Suggests appropriate responses using knowledge base\n   - Provides confidence levels and reasoning\n   - Offers alternative approaches\n   - Determines escalation needs\n\n3. **Customer Explorer Agent** 🔍\n   - Provides rich customer data experiences\n   - Analyzes spending patterns and behavior\n   - Generates interactive components for support agents\n   - Identifies risk factors and opportunities\n\n## 🚀 Key Features\n\n- **Fraud Detection \u0026 Response**: Automatically detects fraud concerns and provides security tools\n- **Escalation Management**: Intelligently escalates urgent or complex issues\n- **Personalized Experiences**: Uses customer data to provide tailored support\n- **Multi-turn Conversations**: Maintains context across complex interactions\n- **Rich Analytics**: Provides behavior analysis and risk assessment\n\n## 📋 Requirements\n\n- Python 3.10+\n- OpenAI API key\n- UV package manager\n\n## 🛠️ Installation\n\n1. **Clone and navigate to the project**:\n   ```bash\n   cd examples/bank_customer_support\n   ```\n\n2. **Install dependencies**:\n   ```bash\n   uv sync\n   ```\n\n3. **Set up environment variables**:\n   Create a `.env` file with:\n   ```env\n   OPENAI_API_KEY=your_openai_api_key_here\n   LANGWATCH_API_KEY=your_langwatch_api_key_here  # Optional\n   ```\n\n## 🎮 Usage\n\n### Basic Usage\n\n```python\nfrom main_support_agent import start_conversation, continue_conversation\n\n# Start a new conversation\nsession_id, response = start_conversation(\n    \"CUST_001\",\n    \"Hi, I'm having trouble with some transactions on my account.\"\n)\nprint(f\"Agent: {response}\")\n\n# Continue the conversation\nnext_response = continue_conversation(\n    session_id,\n    \"I see charges I don't recognize and I'm worried about fraud.\"\n)\nprint(f\"Agent: {next_response}\")\n```\n\n### Individual Agent Usage\n\n```python\n# Summary Agent\nfrom agents.summary_agent import summarize_conversation\n\nmessages = [\n    {\"role\": \"customer\", \"content\": \"I'm frustrated with this issue!\", \"timestamp\": \"2024-01-15 10:30:00\"},\n    {\"role\": \"agent\", \"content\": \"I understand and I'm here to help.\", \"timestamp\": \"2024-01-15 10:31:00\"}\n]\n\nsummary = summarize_conversation(messages)\nprint(f\"Sentiment: {summary.sentiment}\")\nprint(f\"Key Issues: {summary.key_issues}\")\n```\n\n```python\n# Next Message Agent\nfrom agents.next_message_agent import suggest_next_message\n\nsuggestion = suggest_next_message(\n    \"My card was declined at the store\",\n    [{\"role\": \"customer\", \"content\": \"I need help with my card\"}]\n)\nprint(f\"Suggested: {suggestion.suggested_message}\")\nprint(f\"Confidence: {suggestion.confidence_level}\")\n```\n\n```python\n# Customer Explorer Agent\nfrom agents.customer_explorer_agent import explore_customer_context\n\nrich_experiences = explore_customer_context(\n    \"CUST_001\",\n    \"fraud concern, card security\"\n)\n\nfor exp in rich_experiences:\n    print(f\"Component: {exp.title}\")\n    print(f\"Actions: {[action['label'] for action in exp.actions]}\")\n```\n\n## 🧪 Testing\n\nThis project uses **Scenario** framework for comprehensive agent testing with realistic simulations:\n\n### Business-Focused Test Structure\n\n1. **Main Support Agent Tests** (`tests/test_main_support_agent.py`)\n   - Fraud investigation workflows\n   - Complex problem resolution\n   - Customer escalation scenarios\n   - Account inquiries and data exploration\n   - Urgent business issues\n   - Card management and security\n\n2. **Summary Agent Tests** (`tests/test_summary_agent.py`)\n   - Fraud conversation analysis\n   - Escalated conversation patterns\n   - Complex problem resolution summaries\n   - Positive customer experience analysis\n   - Sentiment progression tracking\n\n3. **Customer Explorer Tests** (`tests/test_customer_explorer_agent.py`)\n   - Fraud investigation data analysis\n   - Spending pattern analysis for budgeting\n   - Risk assessment for account protection\n\n4. **Next Message Agent Tests** (`tests/test_next_message_agent.py`)\n   - Complex banking issue guidance\n   - Escalation recommendations\n   - Knowledge base utilization\n\n### Running Tests\n\n```bash\n# Run all Scenario tests\nuv run python -m pytest tests/ -v\n\n# Run specific agent tests\nuv run python -c \"\nimport asyncio\nfrom tests.test_main_support_agent import test_fraud_investigation_workflow\nasyncio.run(test_fraud_investigation_workflow())\n\"\n\n# Run main agent demo\nuv run python main_support_agent.py\n```\n\n### Key Test Features Using Scenario\n\n1. **Realistic User Simulation**\n   ```python\n   @pytest.mark.agent_test\n   @pytest.mark.asyncio\n   async def test_fraud_investigation_workflow():\n       result = await scenario.run(\n           name=\"fraud investigation and card security\",\n           description=\"Customer discovers unauthorized transactions...\",\n           agents=[\n               BankSupportAgentAdapter(),\n               scenario.UserSimulatorAgent(),\n               scenario.JudgeAgent(criteria=[...])\n           ],\n           script=[\n               scenario.user(\"I think my card was stolen...\"),\n               scenario.agent(),\n               scenario.judge(),\n           ],\n       )\n       assert result.success\n   ```\n\n2. **Automated Quality Assessment**\n   - UserSimulatorAgent generates realistic customer responses\n   - JudgeAgent evaluates conversations against business criteria\n   - Tests validate both tool calling and conversation quality\n\n## 📊 Example Conversations\n\n### Fraud Investigation\n```\nCustomer: \"I see transactions I don't recognize. I'm worried about fraud.\"\nAgent: [Calls explore_customer_data tool]\nAgent: \"I've analyzed your account and prepared card management options.\n       You can freeze your card immediately...\"\n```\n\n### Complex Issue Resolution\n```\nCustomer: \"I've been trying to resolve this for weeks and I'm frustrated!\"\nAgent: [Calls get_next_message_suggestion tool]\nAgent: \"I sincerely apologize for the ongoing difficulties.\n       Let me get the best guidance to resolve this comprehensively...\"\n```\n\n### Account Analysis\n```\nCustomer: \"Can you help me understand my spending patterns?\"\nAgent: [Calls explore_customer_data tool]\nAgent: \"I've analyzed your recent transactions and spending behavior.\n       Here are personalized insights and recommendations...\"\n```\n\n## 🎯 Demonstration Features\n\nThis project specifically demonstrates the capabilities mentioned in customer requirements:\n\n### ✅ Tool Calling Validation\n- **Fraud Detection**: Customer mentions unauthorized transactions → Agent calls `explore_customer_data`\n- **Knowledge Base**: Complex issues → Agent calls `get_next_message_suggestion`\n- **Conversation Analysis**: Multi-turn discussions → Agent calls `get_conversation_summary`\n- **Escalation**: Urgent/angry customers → Agent calls `escalate_to_human`\n\n### ✅ Multi-Agent Coordination\n- Main agent coordinates with 3 specialized agents\n- Each agent has distinct responsibilities and expertise\n- Tools abstract the sub-agent complexity (as requested)\n\n### ✅ Rich Customer Experiences\n- Card management interfaces\n- Transaction analysis components\n- Account overview dashboards\n- Risk assessment displays\n\n### ✅ Quality Assurance\n- Comprehensive test coverage\n- Response quality evaluation\n- Sentiment tracking\n- Escalation pattern analysis\n\n## 📁 Project Structure\n\n```\nbank_customer_support/\n├── agents/\n│   ├── __init__.py\n│   ├── summary_agent.py           # Conversation analysis \u0026 sentiment\n│   ├── next_message_agent.py      # Response suggestions \u0026 knowledge base\n│   └── customer_explorer_agent.py # Customer data \u0026 rich experiences\n├── tests/\n│   ├── __init__.py\n│   ├── test_main_support_agent.py # Scenario tests for main agent\n│   ├── test_summary_agent.py      # Unit tests for summary agent\n│   ├── test_next_message_agent.py # Unit tests for next message agent\n│   ├── test_customer_explorer_agent.py # Unit tests for explorer agent\n│   ├── test_integration.py        # Integration tests\n│   └── test_evaluations.py        # Quality evaluation tests\n├── main_support_agent.py          # Main coordinator agent\n├── pyproject.toml                 # Dependencies\n└── README.md                      # This file\n```\n\n## 🔧 Configuration\n\n### Customer Data\nMock customer data is defined in `agents/customer_explorer_agent.py`. In production, this would connect to real banking systems.\n\n### Knowledge Base\nBanking knowledge base is in `agents/next_message_agent.py`. This includes common issues and solutions for:\n- Login problems\n- Card issues\n- Account balance inquiries\n- Transfer problems\n\n### LLM Settings\nAll agents use GPT-4o-mini by default. Change the model in each agent's `create_*_agent()` function.\n\n## 🚀 Next Steps\n\n1. **Enhanced Mock Data**: Add more diverse customer scenarios\n2. **Error Handling**: Implement comprehensive error recovery\n3. **Performance Testing**: Add load testing for multiple concurrent sessions\n4. **Advanced Evaluations**: Implement more sophisticated quality metrics\n5. **Real Integration**: Connect to actual banking APIs and databases\n\n## 🤝 Contributing\n\nThis is a demonstration project for Scenario's agent testing capabilities. The architecture and patterns shown here can be adapted for production banking systems.\n\n## 📝 License\n\nThis project is for demonstration purposes and showcases the integration between Agno (for agent development) and Scenario (for agent testing).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flangwatch%2Fbank-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flangwatch%2Fbank-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flangwatch%2Fbank-example/lists"}