Arquitetura de Agent LLM Multi-Agente para Inteligência Farmacêutica
simonamador/enterprise-llm-agent-architecture
Multi-agent LLM em WhatsApp para inteligência de vendas farmacêuticas em escala
Ver no GitHubSistema de produção multi-agente implantado no WhatsApp que serve 120+ gerentes de vendas farmacêuticas com 4.000+ queries semanais. Orquestra customizada sobre Flask, Oracle SQL e RAG, com separação agente-leitor/escritor, memória de janela deslizante e rastreamento de execução. Model-agnostico (OpenAI, Claude, etc).
Instalação
npx convez-ai simonamador/enterprise-llm-agent-architecture1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Briefing pré-visita sintetizando histórico de prescrição, preferências terapêuticas e KPIs
- Consulta RAG em tempo real sobre literatura científica e documentos técnicos de produtos
- Registro conversacional de observações de campo e logs de visita de farmácias/consultórios
Veredito

Projeto de referência sólido para arquitetura de agentes multi-modelo em produção, com padrões maduros de orquestração, separação de responsabilidades e memória. Documentação Mermaid é prática e didática, mas implementação real requer expertise avançada em LLM e infraestrutura.
README
A tradução para o português deste README ainda está na fila.
Enterprise LLM Agent Architecture for Pharmaceutical Sales Intelligence
A production multi-agent system deployed on WhatsApp for pharmaceutical sales intelligence built for the field, designed for scale.
Table of Contents
- Problem Statement
- System Capabilities
- Architecture
- Technology Stack
- Design Decisions
- Evaluation & Outcomes
- Challenges & Tradeoffs
- Lessons Learned
Problem Statement
Pharmaceutical sales representatives operate under significant information pressure. Before visiting a doctor or pharmacy, a rep typically needs to:
- Review the doctor's prescription history and therapeutic preferences
- Check nearby pharmacies and their sales performance
- Access personal KPIs and quota progress
- Recall prior visit notes and field observations
- Consult relevant clinical or scientific literature
- Strategize the visit approach in real time This information was fragmented across multiple disconnected CRM applications, databases, and reporting tools; none conversational, and none capable of synthesizing a unified view. Reps had to context-switch between systems in the field, often under time pressure minutes before entering a clinic.
There was no single interface to prepare for a visit, ask a contextual question, or register an outcome from one.
Yachai was built to solve this entirely through natural conversation on WhatsApp.
The choice of WhatsApp was deliberate: it is already the primary communication tool of every rep in the field. Zero onboarding friction. No new app to install. The system had to meet users where they already were.
System Capabilities
| Capability | Description |
|---|---|
| Doctor Intelligence | Prescription behavior, therapeutic preferences, visit history, general profile |
| Pharmacy Intelligence | Sales performance, geolocation-aware nearby pharmacy lookup, stock observations |
| Pre-Visit Strategic Prep | AI-generated briefings synthesizing all available data before a scheduled visit |
| KPIs | Real-time personal and team performance indicators on demand |
| Schedule & Visits | Upcoming visit agenda, pending follow-ups, next visits by territory |
| Scientific Literature | RAG-powered queries over clinical studies and product technical documents |
| Observation Registration | Natural language field note capture for doctors or pharmacies |
| Visit Registration | End-of-visit logging via conversational flow |
Architecture
High-Level System Flow
┌─────────────────────────────────────────────────┐
│ Sales Rep │
│ (WhatsApp Mobile) │
└────────────────────┬────────────────────────────┘
│ message / media
▼
┌─────────────────────────────────────────────────┐
│ Meta Business API │
│ (Webhook → Flask Gateway) │
└────────────────────┬────────────────────────────┘
│ parsed event
▼
┌─────────────────────────────────────────────────┐
│ Orchestrator Agent │
│ │
│ ┌─────────────┐ ┌──────────────────────────┐ │
│ │ Intent │ │ Conversation Memory & │ │
│ │ Classifier │ │ Context Engineering │ │
│ └──────┬──────┘ └──────────────────────────┘ │
│ │ Route │
└─────────┼───────────────────────────────────────┘
│
├──► Doctor Info Agent ──► Oracle SQL (read)
├──► Pharmacy Agent ──► Oracle SQL (read)
├──► Prescription Agent ──► Oracle SQL (read)
├──► Schedule Agent ──► Oracle SQL (read)
├──► Observation Reg. Agent ──► Oracle SQL (write) *
├──► Visit Registration Agent ──► Oracle SQL (write) *
├──► Pre-Visit Prep Agent ──► Oracle SQL + RAG Pipeline
└──► Literature Agent ──► Vector Store (RAG)
│
▼
┌─────────────────┐
│ LLM Provider │
│ (model-agnostic)│
└─────────────────┘
│
┌──────────────────────────┘
│ formatted response
▼
┌─────────────────────────────────────────────────┐
│ Meta Business API │
│ (Outbound message delivery) │
└─────────────────────────────────────────────────┘
* Write agents require explicit intent confirmation before execution.
Component Details
Ingestion Layer
A Flask webhook receives events from the Meta Business API. It handles message parsing, media extraction, sender identification (mapped to internal rep IDs), rate limiting, and idempotency checks against WhatsApp delivery retries. The normalized payload is then handed off to the orchestration layer.
Orchestrator Agent
The core of the system. Responsible for:
- Intent classification determining which agent(s) to invoke based on the message
- Agent routing single-agent dispatch for simple queries, multi-agent fan-out for complex requests (e.g., pre-visit prep)
- Context management injecting a sliding window of recent messages, summarized older history, user profile, and relevant state into each downstream agent call
- Response synthesis merging multi-agent outputs into a coherent, WhatsApp-formatted reply The orchestrator is stateless per invocation; all state lives in a persistent conversation memory store keyed by user ID.
Specialized Agents
Each agent is a focused, prompt-engineered unit with its own tool set. Agents do not communicate with each other directly, all coordination flows through the orchestrator. This keeps the system debuggable and prevents cascading failures between agents.
RAG Pipeline
The literature agent uses a retrieval-augmented generation pipeline: embedded chunks from clinical studies and product technical sheets are stored in a vector index. At query time, top-k relevant chunks are retrieved and injected into the LLM context alongside the user's question.
Conversation Memory
Multi-turn state is maintained per user session. The memory layer stores recent message history, a running summary of older conversation history, inferred user context (current doctor or pharmacy being discussed, active topic), and session metadata. Each LLM call receives a bounded sliding window of recent messages plus the summary, rather than the full conversation transcript, to respect token budget constraints at scale.
Execution Trace
Yachai persists each WhatsApp message and the tool calls executed between messages for analysis, debugging, audit review, and quality evaluation. Tool call records store the tool name, JSON filters, status, latency, and errors, but not the CRM rows, retrieved documents, or other returned data.
Technology Stack
| Layer | Technology |
|---|---|
| Runtime | Python 3.x |
| Web Framework | Flask |
| Database | Oracle SQL (Yachai application schema over enterprise CRM views) |
| LLM Provider | OpenAI GPT-4 class (migrating to Anthropic Claude) |
| Messaging API | Meta Business API (WhatsApp) |
| RAG / Embeddings | Custom pipeline; OpenAI text-embedding models |
| Deployment | Docker, internal enterprise infrastructure |
| Agent Orchestration | Custom multi-agent framework (no third-party agent library) |
The system was intentionally built without a third-party agent framework. This decision is discussed in Design Decisions.
Design Decisions
Full discussion in docs/design-decisions.md. Key decisions summarized:
1. WhatsApp as the sole interface Adoption is the hardest problem in enterprise tooling. Building on the channel reps already use daily brought onboarding friction to zero. The constraints of a messaging interface (no rich UI, character limits, async delivery) forced simplicity and discipline in response design.
2. Custom orchestration over agent frameworks LangChain and LlamaIndex were evaluated and rejected. The overhead, abstraction leakage, and debugging complexity were not justified for a system with well-defined, stable agent boundaries. The custom orchestrator is lean, fully auditable, and has no transitive dependencies that can break between versions.
3. Model-agnostic design from day one All LLM providers are abstracted behind a single interface layer. The system has operated on OpenAI GPT-4 class models in production and is being migrated to Anthropic Claude with zero agent-level rewrites required.
4. Agents as deterministic tools, not autonomous actors Agents in Yachai are not autonomous. They are invoked by the orchestrator with a defined input schema and return structured outputs. This trades flexibility for reliability, the right tradeoff for an enterprise system where incorrect outputs have real business consequences.
5. Strict read/write agent separation Agents that write to the database (observation registration, visit logging) are strictly separated from read agents and require an explicit intent confirmation step before execution. This prevents accidental writes from ambiguous messages.
Evaluation & Outcomes
Usage Metrics (Production)
| Metric | Value |
|---|---|
| Active users | 120 sales representatives |
| Weekly query volume | 4,000+ |
| Primary use case | Pre-visit doctor and pharmacy lookup |
Business Impact
The primary impact metric was measured by comparing year-over-year market share performance across two cohorts:
- Treatment group doctors visited by reps actively using Yachai during the visit
- Control group doctors visited by the same reps without Yachai usage The treatment cohort showed a +1 percentage point differential in market share growth YoY relative to the control cohort. The effect was consistent across therapeutic areas and territories, providing meaningful signal beyond noise.
This uses a quasi-experimental design, with internal visit-level CRM data used to assign treatment/control status post hoc. While not a randomized controlled trial, the consistency of the effect and the cohort size make it a credible attribution. Selection bias (reps who use Yachai more heavily may differ systematically) is acknowledged as a limitation.
Qualitative Signal
- Reps report reduced pre-visit preparation time
- Field managers cite improved quality and detail in post-visit observations
- System is now part of the standard onboarding process for new sales representatives
Challenges & Tradeoffs
WhatsApp platform constraints The Meta Business API imposes strict rate limits, message format restrictions, 24-hour session windows, and template pre-approval requirements for outbound messages. Significant engineering effort went into handling these constraints without degrading the conversational experience.
Oracle application schema over enterprise CRM data Yachai uses its own Oracle application schema to package the app's database surface through views over broader enterprise CRM systems. Agents query this schema with parameterized SQL, while source enterprise schemas remain owned by the CRM team. Upstream schema changes still require coordination, but the application schema limits coupling and keeps agent queries focused on stable views.
LLM latency on a messaging interface Users expect fast responses in WhatsApp. Multi-agent fan-out for pre-visit prep (triggering 3-4 agents) can produce noticeable latency. Partial mitigations: typing indicators, parallel agent invocation where dependency graphs allow, and pre-loading of data.
Structured output enforcement for writes LLM outputs are non-deterministic. For read-only queries this is acceptable. For write operations (visit and observation registration), structured output schemas and validation layers were added to prevent malformed data from reaching the database.
Attribution methodology The market share finding is a strong business signal but not a controlled experiment. Honest reporting requires acknowledging the quasi-experimental nature of the measurement.
Lessons Learned
Distribution beats capability. The decision to deploy on WhatsApp rather than a custom app was the single most important factor in adoption. A more capable system behind a new login screen would have failed.
Custom orchestration pays off at scale. The initial investment in a lightweight custom framework saved significant debugging time compared to the abstraction overhead of general-purpose agent libraries, particularly when tracing failures in production.
Read/write separation is non-negotiable in enterprise. The first version did not enforce this. One ambiguous message caused a duplicate observation to be registered for a doctor. Explicit intent confirmation before any write operation was shipped immediately after.
Context engineering is the real work. The LLM is the least interesting part of the system. The hard engineering is maintaining a reliable sliding window, keeping older conversation summaries accurate, and formatting retrieved context under token budget constraints at 4,000+ queries per week.
Model-agnostic architecture from day one is worth the overhead. The migration from OpenAI to Anthropic Claude is happening with zero agent-level rewrites. The abstraction layer paid for itself on the first provider switch.
Repository Structure
enterprise-llm-agent-architecture/
├── README.md # This document
├── docs/
│ ├── architecture.md # Extended architecture detail
│ ├── design-decisions.md # Full ADR-style decision log
│ └── lessons-learned.md # Extended reflections
├── diagrams/
│ └── system-overview.mmd # Mermaid source for architecture diagram
└── examples/
└── synthetic-conversations.md # Anonymized example interactions
Author
Simón — Lead AI Engineer
Biomedical Engineer · AI/ML Systems · Healthcare & Pharma
LinkedIn · GitHub
This repository documents system architecture and design for portfolio and research purposes. No proprietary source code, internal prompts, confidential data, or sensitive business metrics are included.