Sistema simples de Cadastro com MCP e Agentes de IA
Como criar um sistema inteligente de cadastro usando MCP, agentes de IA e Gradio?Integre modelos avançados com uma interface simples e prática.
Introdução
A transformação digital em várias áreas, como a área da saúde, exige soluções tecnológicas que sejam eficientes, escaláveis e seguras. Neste artigo, vamos demonstrar como construir um sistema inteligente de cadastro e consulta de pacientes utilizando um conjunto moderno de ferramentas:
MCPServer: protocolo robusto de comunicação assíncrona.
IA Agentics e Pydantic-AI: para orquestração de agentes inteligentes.
Gradio: criação rápida de interfaces web.
SQLAlchemy e Pydantic: estruturação e validação de dados.
O projeto final oferece um painel para cadastrar pacientes, consultar registros e interagir com uma LLM para responder questões clínicas.
Por que usar MCP e Agentes de IA neste contexto?
A escolha por adotar o MCP (Multi-Connection Protocol) e Agentes de IA neste projeto não é apenas uma decisão tecnológica, mas uma estratégia arquitetural que amplia significativamente a eficiência, a escalabilidade e a modularidade do sistema.
O que é o MCP (Multi-Connection Protocol)?
O MCP é um protocolo que permite a comunicação eficiente entre múltiplos componentes ou agentes de software, geralmente utilizando canais assíncronos como Server-Sent Events (SSE) ou WebSockets.
Ele foi desenhado para resolver um problema clássico em sistemas distribuídos: como permitir que várias partes de um sistema conversem de maneira rápida e ordenada, sem depender de chamadas síncronas e bloqueantes.
No contexto deste projeto, o MCP permite que:
O agente de IA receba uma consulta do usuário pela interface Gradio.
O agente processe a consulta, possivelmente interagindo com múltiplos servidores ou modelos.
A resposta seja devolvida de forma rápida e segura, sem travar a interface.
Exemplo prático:
Enquanto o usuário cadastra um paciente, outro módulo — talvez um agente de IA para análise de risco — pode estar simultaneamente processando sinais vitais e sugerindo alertas. Tudo isso ocorre de forma independente, paralela e integrada graças ao MCP.
O que são Agentes de IA?
Agentes de IA são componentes de software que tomam decisões, processam informações ou realizam tarefas de maneira autônoma, normalmente baseados em modelos de Machine Learning ou Processamento de Linguagem Natural (PLN).
Neste projeto, o agente é construído com Pydantic-AI e orquestrado por IA Agentics, conectando-se ao MCP para interagir com outros sistemas.
Características dos agentes de IA utilizados:
Especialização: o agente neste exemplo responde especificamente sobre informações de pacientes.
Flexibilidade: pode mudar dinamicamente de modelo, como de
Llama-3para outro modelo mais específico.Autonomia: processa consultas sem intervenção humana direta.
Como o MCP e os Agentes de IA se Integram?
A integração é feita de forma natural e modular. Veja como cada peça se conecta:
O Agente é inicializado com uma configuração padrão, apontando para um ou mais servidores MCP.
O MCP gerencia a comunicação assíncrona, recebendo mensagens da interface de usuário (Gradio) e repassando para o agente.
O Agente de IA processa a mensagem usando o modelo configurado — por exemplo, o
Llama-3— e retorna a resposta.O MCP envia de volta a resposta ao frontend, onde o usuário vê o resultado em tempo real.
Visualmente:
Esse fluxo proporciona uma experiência fluida e altamente reativa.
Vantagens do uso de MCP + IA Agentics
Orquestração de múltiplos agentes especializados:
Cada agente pode ser focado em uma tarefa — por exemplo, um para cadastro, outro para triagem, outro para análise preditiva.Comunicação assíncrona eficiente via Server-Sent Events (SSE):
Evita bloqueios, melhora a escalabilidade e suporta milhares de conexões simultâneas.Modularidade:
Novos agentes podem ser facilmente adicionados ao ecossistema, como um módulo para previsão de tempo de internação ou sugestão de medicamentos.Facilidade de integração com modelos de última geração:
ComoLlama-3eGroq, que oferecem capacidades robustas de entendimento de linguagem natural, fundamentais para interações clínicas complexas.
Entendendo o Pipeline Completo do Projeto
O pipeline deste projeto é o fio condutor que conecta todas as partes essenciais da aplicação, garantindo que o fluxo de dados seja coerente, eficiente e seguro. Ele inicia no momento em que o usuário interage com a interface gráfica, passando pelo processamento inteligente via Agente de IA, seguido pela persistência e consulta no banco de dados, e finaliza com a resposta apresentada ao usuário de forma clara e interativa.
O mais interessante desse pipeline é que ele se apoia em conceitos modernos como:
Arquitetura orientada a agentes
Comunicação assíncrona com o MCP
Validação e segurança de dados com Pydantic
Interatividade e usabilidade com Gradio
A seguir, vamos esmiuçar cada etapa desse pipeline, explicando como elas se interligam, qual o papel de cada tecnologia e como o código implementa essas operações.
1. Entrada do Usuário: O Gatilho Inicial
Tudo começa com a interação do usuário na interface gráfica criada com Gradio.
A interface possui dois grandes fluxos:
Consulta: quando o usuário quer obter informações sobre pacientes.
Cadastro: quando deseja inserir novos pacientes no sistema.
Em ambos os casos, o usuário utiliza elementos gráficos como textboxes, dropdowns e botões, que são intuitivos e fáceis de usar.
Exemplo no código:
user_input = gr.Textbox(placeholder="Digite uma pergunta sobre pacientes...")
send_button = gr.Button("📤 Enviar")O clique no botão ou o envio pelo teclado aciona uma função Python, que é o primeiro passo da engrenagem do pipeline.
2. Encaminhamento Assíncrono com o MCP
Assim que a interação ocorre, o dado é encaminhado pelo MCP (Multi-Connection Protocol).
O MCP é o componente responsável por fazer a ponte entre a interface e o Agente de IA, gerenciando a troca de mensagens de forma assíncrona e eficiente.
paciente_server = MCPServerHTTP(url="http://127.0.0.1:7865/gradio_api/mcp/sse")O Server-Sent Events (SSE) é utilizado para manter a conexão aberta e reativa, permitindo que a resposta do agente seja enviada assim que estiver pronta, sem necessidade de polling ou reenvio de requisições.
3. Processamento da Mensagem pelo Agente de IA
A mensagem enviada é processada pelo MCPAgentClient, que faz a intermediação com o Agente de IA.
class MCPAgentClient:
"""
Interação com MCP e Groq Agent.
"""
def __init__(self, model_name: str = AVAILABLE_MODELS[0]):
self.model_name = model_name
self.agent = self._create_agent(model_name)
self.status_message = "Conectando ao servidor MCP..."
def _create_agent(self, model_name: str) -> Agent:
return Agent(
f"groq:{model_name}",
mcp_servers=[paciente_server],
system="Você é um agente que responde sobre pacientes cadastrados."
)
def process_query(self, message: str, model_name: str) -> Tuple[str, Optional[float]]:
"""
Processa uma consulta ao agente, com troca dinâmica de modelo.
"""
if model_name != self.model_name:
logger.info(f"Modelo alterado: {self.model_name} → {model_name}")
self.model_name = model_name
self.agent = self._create_agent(model_name)
else:
logger.info(f"Reutilizando modelo atual: {self.model_name}")
self.status_message = f"Processando com modelo: {self.model_name}"
try:
with ThreadPoolExecutor() as executor:
start_time = time.time()
future = executor.submit(self._run_agent_sync, message)
result = future.result(timeout=10.0)
elapsed = time.time() - start_time
self.status_message = f"Resposta em {elapsed:.2f}s"
logger.info(f"Resposta recebida em {elapsed:.2f}s")
return result, elapsed
except asyncio.TimeoutError:
self.status_message = "Timeout"
logger.warning("Operação excedeu 10 segundos.")
return "A operação demorou mais de 10s. Tente novamente.", None
except Exception as e:
self.status_message = f"Erro: {e}"
logger.exception("Erro ao processar a consulta")
return f"Erro: {e}", None
def _run_agent_sync(self, message: str) -> str:
"""
Executa o agente de forma síncrona dentro de um novo loop de evento.
"""
loop = asyncio.new_event_loop()
asyncio.set_event_loop(loop)
return loop.run_until_complete(self._run_agent_async(message))
async def _run_agent_async(self, message: str) -> str:
async with self.agent.run_mcp_servers():
response = await self.agent.run(message)
return response.output
def get_status(self) -> str:
return self.status_message
# Instância única para interação com o agente
agent_client = MCPAgentClient()
# Configuração da interface Gradio
with gr.Blocks(theme="soft") as demo:
with gr.Row():
gr.Markdown("## 🩺 Painel de Controle - Cliente MCP + Groq Agent")
with gr.Row():
with gr.Column(scale=1):
gr.Markdown("### ⚙️ Configurações")
model_selector = gr.Dropdown(
choices=AVAILABLE_MODELS,
label="Selecione o Modelo",
value=DEFAULT_MODEL
)
status_display = gr.Textbox(
label="📡 Status do Sistema",
value=agent_client.get_status(),
interactive=False,
lines=2
)
with gr.Column(scale=2):
gr.Markdown("### 💬 Interação com o Agente")
chatbot = gr.Chatbot(
label="Diálogo com o Agente",
height=400,
show_label=True,
avatar_images=("user.png", "agent.png") # opcional se tiver imagens
)
with gr.Row():
user_input = gr.Textbox(
placeholder="Digite uma pergunta sobre pacientes...",
label="Mensagem"
)
send_button = gr.Button("📤 Enviar")
# Função de resposta
def respond(msg: str, history: list) -> tuple[str, list]:
if not msg:
return "", history
try:
history.append(["user", msg])
response, _ = agent_client.process_query(msg, model_selector.value)
history.append(["assistant", response])
except Exception as e:
logger.exception("Erro no processamento da mensagem")
history.append(["assistant", f"⚠️ Erro: {str(e)}"])
return "", historyEste agente:
Recebe a consulta do usuário.
Executa o modelo de IA configurado — por exemplo, Llama-3 ou Groq.
Gera uma resposta baseada nos dados disponíveis e no modelo cognitivo.
Esse processamento ocorre dentro de um loop assíncrono, para garantir que múltiplas consultas possam ser processadas simultaneamente sem travar o sistema.
async def _run_agent_async(self, message: str) -> str:
async with self.agent.run_mcp_servers():
response = await self.agent.run(message)
return response.outputAqui, o agente pode inclusive consultar o banco de dados ou combinar múltiplas fontes de dados para formular a resposta.
4. Acesso e Persistência de Dados com SQLAlchemy e Pydantic
No caso de cadastros ou consultas que envolvem o banco de dados, o pipeline inclui a camada de persistência.
O modelo de dados é criado com SQLAlchemy:
class PacienteDB(Base):
__tablename__ = "pacientes"
id = Column(Integer, primary_key=True, index=True)
nome = Column(String(100), nullable=False)
idade = Column(Integer, nullable=False)
sintoma = Column(String(255), nullable=False)
data_internacao = Column(Date, nullable=False)
data_alta = Column(Date, nullable=True)
medico_responsavel = Column(String(100), nullable=False)Cada vez que um paciente é cadastrado, ele é inserido na tabela pacientes de forma transacional, garantindo a consistência do banco.
Antes disso, os dados passam pela validação com Pydantic:
class CadastroPaciente(BaseModel):
nome: str = Field(..., min_length=2, max_length=100)
idade: int = Field(..., gt=0, lt=130)
sintoma: str = Field(..., min_length=3)
data_internacao: Optional[date] = Field(default_factory=date.today)
data_alta: Optional[date] = None
medico_responsavel: str = Field(..., min_length=3)
@model_validator(mode='after')
def check_datas_coerentes(self):
if self.data_internacao and self.data_alta and self.data_alta < self.data_internacao:
logger.warning(f"❗ Inconsistência nas datas: {self.data_internacao} -> {self.data_alta}")
raise ValueError("A data de alta não pode ser anterior à data de internação.")
return selfIsso garante que o sistema seja resiliente a erros humanos ou inconsistências nos dados.
5. Retorno da Resposta ao Usuário
Depois do processamento pelo Agente de IA ou da execução das operações de banco de dados, a resposta é devolvida ao usuário através da interface Gradio.
No fluxo de consulta, por exemplo, isso acontece pela função:
def respond(msg: str, history: list) -> tuple[str, list]:
...
response, _ = agent_client.process_query(msg, model_selector.value)
history.append(["assistant", response])
return "", history
A resposta é inserida no histórico do chatbot, permitindo que o usuário acompanhe o diálogo de forma contínua e compreensível.
Conclusão
Este projeto demonstra, na prática, como é possível criar um sistema inteligente, modular e escalável para cadastro e consulta de pacientes ao integrar tecnologias modernas e sinérgicas.
Utilizando o MCP como protocolo de comunicação assíncrona, conseguimos garantir eficiência e fluidez na troca de informações entre a interface e os agentes de IA. A adoção de Agentes de IA, configurados com Pydantic-AI e orquestrados por IA Agentics, permite a criação de componentes autônomos, especializados e dinâmicos, que podem evoluir conforme as necessidades do sistema.
A interface gráfica criada com Gradio mostra como é possível construir rapidamente aplicações com experiência de usuário acessível e moderna, tornando a interação com modelos de IA e bancos de dados mais intuitiva, mesmo para profissionais não técnicos.
O uso conjunto de SQLAlchemy e Pydantic reforça a importância de uma modelagem de dados robusta, com validação automática que evita erros e mantém a integridade das informações, fator essencial em sistemas críticos como os da área da saúde.
Link do projeto: https://github.com/FelipeAmaral13/EstudosMCP/tree/main/MCP_IA_Pacientes