How padmanabhamkiran1234/ai-support-agent works
This repository is a small Python multi-agent support automation system, centered on a single orchestration flow that turns a customer message into a classified, research-backed support response and, when needed, a structured ticket.
1. Top-level architecture
- The code is split into four main boundaries: agents (decision-making and orchestration), tools (data access and side effects), llm (model adapter), and memory (session state).
- utils/ provides cross-cutting concerns such as logging.
2. Primary entry points
- main.py is the likely CLI/demo runner for the agent pipeline.
- web_app.py suggests an alternate interactive front end, but the repository is not primarily organized as a web service.
- tests/test_demo_flow.py exercises the end-to-end demo path.
3. Agent layer
- agents/query_agent.py handles query interpretation or normalization before downstream processing.
- agents/classifier_agent.py performs intent/category classification, which the README describes as part of a parallelized multi-agent flow.
- agents/summary_agent.py is the final synthesis step that turns the collected evidence and tool outputs into the user-facing answer.
4. Tool layer
- tools/knowledge_base_tool.py and tools/vector_kb_tool.py are the retrieval side of the system; they represent knowledge-base lookup, with the vector tool likely providing semantic search.
- tools/ticket_tool.py is the action side of the system, generating a structured support ticket when the query cannot be fully resolved from the KB.
- These tools are the main boundary between reasoning and external data/action workflows.
5. LLM integration
- llm/gemini_client.py isolates calls to the Gemini model.
- This wrapper keeps model-specific behavior out of the agents, so the orchestration layer can stay focused on pipeline logic rather than API details.
6. Session and memory
- memory/session_service.py manages in-memory session state.
- This provides conversational continuity across turns, allowing the system to reuse prior context without relying on a persistent database.
7. End-to-end data flow
- A user query enters through the CLI or web entry point.
- The query agent prepares the input, the classifier agent determines what kind of support issue it is, and the system consults KB tools in parallel where relevant.
- If the issue needs escalation or tracking, the ticket tool creates a structured ticket.
- The summary agent combines the classification, retrieval results, and ticket outcome into the final response, then the session service stores the interaction state.
8. Execution model
- The README explicitly calls out a multi-agent flow with parallel classification and KB lookup.
- That implies the core architecture is orchestration-first: one coordinator fans out to specialized workers, then gathers results for a final response.
9. Observability
- utils/logger.py provides basic logging across the system.
- This is likely the main operational visibility layer, since there is no separate monitoring stack in the repository.
10. Testing and evaluation
- tests/eval_agent.py appears to support agent-level evaluation.
- tests/test_demo_flow.py validates the integrated demo path, which is important for a system whose behavior depends on orchestration between agents and tools.
11. Runtime and packaging
- requirements.txt defines the Python dependencies, and Dockerfile packages the app for containerized execution.
- The README indicates Python 3.9+ as the local runtime baseline.
12. Architectural summary
- This is a modular, LLM-driven support assistant where agents decide, tools retrieve or act, memory preserves context, and the Gemini client supplies language intelligence.
- The cleanest diagram would show a central orchestration path with side branches to KB retrieval, ticket creation, and session storage, all wrapped by logging and exposed through CLI/web entry points.
Main entry points: classifier_agent.py Classifier · summary_agent.py Summary agent · query_agent.py Query agent · logger.py Logger
Components 13
Entry Points
Ways to invoke the support pipeline.
- CLI runner · Primary command-line/demo entry for the support flow.
main.py - Web app · Alternate interactive front end for the same orchestration flow.
web_app.py
Agents
Decision and orchestration components.
- Query agent · Normalizes or interprets incoming customer queries.
agents/query_agent.py - Classifier · Determines intent and support category.
agents/classifier_agent.py - Summary agent · Synthesizes evidence into the final response.
agents/summary_agent.py
Tools
Knowledge retrieval and ticketing actions.
- KB lookup · Knowledge-base access for direct lookups.
tools/knowledge_base_tool.py - Vector search · Semantic retrieval against the knowledge base.
tools/vector_kb_tool.py - Ticket tool · Creates structured support tickets when escalation is needed.
tools/ticket_tool.py
Core Services
Shared runtime services and model access.
- Gemini client · Isolates model calls and prompt execution.
llm/gemini_client.py - Session service · Stores in-memory conversation state across turns.
memory/session_service.py
Ops
Cross-cutting support and validation.
- Logger · Shared logging for the pipeline.
utils/logger.py - Demo flow test · Validates the end-to-end orchestration path.
tests/test_demo_flow.py - Agent eval · Supports agent-level evaluation and benchmarking.
tests/eval_agent.py
Connections 24
- CLI runner → Query agent: starts · CLI/demo execution enters the agent pipeline.
- Web app → Query agent: starts · Web interaction routes into the same orchestration flow.
- Query agent → Classifier: normalizes for · Prepared query is handed to classification.
- Classifier → KB lookup: looks up · Classification can trigger knowledge-base retrieval.
- Classifier → Vector search: semantic search · Parallel retrieval path for relevant support content.
- Classifier → Ticket tool: escalates to · Unresolved or actionable issues can become tickets.
- KB lookup → Summary agent: provides evidence · KB results feed the final synthesis step.
- Vector search → Summary agent: provides evidence · Semantic search results are merged into the response.
- Ticket tool → Summary agent: returns status · Ticket creation outcome is included in the final answer.
- Classifier → Summary agent: hands off · Classification output is part of the final synthesis context.
- Query agent → Gemini client: uses · Agent logic relies on the LLM adapter for language tasks.
- Classifier → Gemini client: uses · Classification is driven through the model wrapper.
- Summary agent → Gemini client: uses · Final response generation uses the model wrapper.
- CLI runner → Session service: stores state · CLI run updates session continuity.
- Web app → Session service: stores state · Interactive sessions persist conversation context in memory.
- Query agent → Session service: reads context · Current query can be interpreted using prior turns.
- Summary agent → Session service: updates context · Final response and interaction state are stored.
- CLI runner → Logger: logs · Pipeline execution is logged.
- Web app → Logger: logs · Interactive execution is logged.
- Query agent → Logger: logs · Agent activity is observed through shared logging.
- Classifier → Logger: logs · Classification steps emit logs.
- Summary agent → Logger: logs · Synthesis and response generation emit logs.
- Demo flow test → CLI runner: exercises · Integration test validates the demo entry path.
- Agent eval → Classifier: evaluates · Evaluation focuses on agent behavior and outputs.