convez.ai
AgenteAutomaçãoAvançado
simonamador

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 GitHub
InicialPluginScore · de 0 a 100

Sistema 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-architecture

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 6 meses
Versão
—
Issues abertas
0
Contribuidores
1

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.

Status Users Queries Stack Interface


Table of Contents


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

CapabilityDescription
Doctor IntelligencePrescription behavior, therapeutic preferences, visit history, general profile
Pharmacy IntelligenceSales performance, geolocation-aware nearby pharmacy lookup, stock observations
Pre-Visit Strategic PrepAI-generated briefings synthesizing all available data before a scheduled visit
KPIsReal-time personal and team performance indicators on demand
Schedule & VisitsUpcoming visit agenda, pending follow-ups, next visits by territory
Scientific LiteratureRAG-powered queries over clinical studies and product technical documents
Observation RegistrationNatural language field note capture for doctors or pharmacies
Visit RegistrationEnd-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

LayerTechnology
RuntimePython 3.x
Web FrameworkFlask
DatabaseOracle SQL (Yachai application schema over enterprise CRM views)
LLM ProviderOpenAI GPT-4 class (migrating to Anthropic Claude)
Messaging APIMeta Business API (WhatsApp)
RAG / EmbeddingsCustom pipeline; OpenAI text-embedding models
DeploymentDocker, internal enterprise infrastructure
Agent OrchestrationCustom 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)

MetricValue
Active users120 sales representatives
Weekly query volume4,000+
Primary use casePre-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.

Ver o original no GitHub

Bom para

Relacionados