Prontagenda AI Agent

Prontagenda AI — Automação inteligente para clínicas.

Comment

Inspiration

Prontagenda did not start as an AI project.

It started from a real problem I experience in healthcare: managing a clinic requires much more than maintaining an appointment calendar.

Every day, clinic staff handle patient messages, appointment requests, confirmations, schedule changes, patient records, financial information, inventory, treatments, documents, and many other operational tasks.

Individually, most of these tasks are straightforward. The problem is their volume and the constant interruptions they create.

As a dentist, I wanted a system that could centralize these workflows instead of forcing the clinic to work across disconnected tools. That idea became Prontagenda, a web-based clinic management platform with scheduling, patient records, odontograms, treatment management, financial management, inventory, documents, multi-company support, and role-based access.

But one problem remained: even with a centralized management system, clinic staff still had to manually read every WhatsApp message, understand what the patient wanted, check the schedule, respond, and then perform the corresponding action inside the system.

That was the motivation for Prontagenda AI Agent.

The goal was not to add another chatbot.

The goal was to build an agent that could understand a real patient request, determine which workflow was required, safely use Prontagenda's existing business rules, complete authorized actions, and recognize when a human should take over.

Pre-existing foundation and hackathon work

The core Prontagenda management platform existed before the hackathon.

During the hackathon submission period, I built the new agentic layer: the Google ADK agent, least-privilege WhatsApp tools and PHP APIs, signed conversation context, protected Cloud Run gateway, human escalation workflow, container deployment, and integration with Gemini 3.5 Flash-Lite through Vertex AI.

The existing platform provides the domain data and deterministic business rules. The autonomous agent architecture and its secure integration with Prontagenda are the work created for this hackathon.

What it does

Prontagenda AI Agent connects natural-language WhatsApp conversations with real clinic scheduling workflows.

For example, a patient can simply write that they would like an appointment after 5 PM.

The agent can:

  • understand that the message is an appointment request;
  • present the clinic's available professionals;
  • understand which professional the patient selects;
  • check that professional's real working hours;
  • interpret preferences such as a specific day, time, period, or earliest availability;
  • query actual schedule availability;
  • offer only valid appointment times returned by the backend;
  • understand follow-up choices and changes of preference;
  • collect the patient's name when necessary;
  • prepare an appointment proposal;
  • request explicit final confirmation;
  • create the appointment in Prontagenda only after confirmation.

The result is not just a generated answer. After the backend validates the request and completes the transaction, the appointment actually appears in the clinic schedule.

At the same time, autonomy has deliberate limits.

Requests involving clinical judgment, administrative access, unavailable schedules, technical failures, or situations outside the agent's authorized scope are not completed autonomously.

The agent uses an authorized escalation tool to send the conversation to the clinic's human support queue. This allows Prontagenda to combine useful automation with human oversight instead of attempting to automate every possible situation.

From clinic management software to an agentic system

One of the most important design decisions was to avoid giving Gemini or the Python agent direct access to the application database.

The patient communicates through WhatsApp, but WhatsApp does not communicate directly with Gemini.

The external communication flow is:

Patient ↔ WhatsApp ↔ Evolution API ↔ Prontagenda PHP Router

The PHP router authenticates the Cloud Run gateway with a Bearer token. It also sends a signed HMAC context that binds the company, conversation, and sender.

The model cannot choose or replace the company, patient identity, or sender's phone number.

Inside Google Cloud:

  • Cloud Run hosts the Google ADK agent.
  • The ADK agent uses Gemini 3.5 Flash-Lite through Vertex AI for reasoning and function-call decisions.
  • The ADK runtime invokes only explicitly authorized HTTP tools.
  • Secret Manager injects the gateway token into Cloud Run at runtime.
  • Artifact Registry stores the deployed container image.
  • The Cloud Run service uses a dedicated least-privilege service account instead of a Gemini API key or service-account key file.

The authorized tools call protected Prontagenda PHP APIs over HTTPS using the signed conversation context.

The PHP backend — not Gemini and not the Python tools — validates authorization, applies business rules, checks availability, manages transactions, and accesses MySQL.

The execution flow is:

  1. Gemini interprets the request and selects an appropriate action.
  2. Google ADK invokes an explicitly authorized tool.
  3. The tool calls a protected Prontagenda PHP API.
  4. PHP validates the signed context, authorization, business rules, and current database state.
  5. PHP executes or rejects the requested operation.
  6. The result returns through the agent and the WhatsApp communication flow.

If a request requires human judgment, the authorized escalation tool calls the PHP escalation endpoint and transfers the conversation to the clinic's support queue.

This separation keeps reasoning flexible while ensuring that authorization and data changes remain deterministic and controlled.

How I built it

The existing Prontagenda platform is primarily built with:

  • PHP;
  • MySQL/MariaDB;
  • JavaScript;
  • AJAX;
  • JSON APIs;
  • Evolution API for WhatsApp integration.

For the new agentic layer, I used:

  • Gemini 3.5 Flash-Lite;
  • Vertex AI;
  • Google Agent Development Kit;
  • Google Cloud Run;
  • Google Cloud Build;
  • Artifact Registry;
  • Secret Manager;
  • FastAPI;
  • Python;
  • protected Prontagenda PHP AI APIs;
  • signed HMAC conversation contexts;
  • a dedicated Google Cloud service account.

The Google ADK agent is packaged as a Docker container and deployed as a Cloud Run service in the São Paulo region.

The Gemini model is accessed through Vertex AI using the Cloud Run service identity. No Gemini API key or downloadable service-account JSON key is stored in the application.

The Cloud Run gateway exposes only a health endpoint and an authenticated WhatsApp response endpoint. Requests to the agent endpoint require a Bearer token stored in Secret Manager.

The patient's conversation context is short-lived and signed by the PHP backend. It is injected only during the corresponding request and is not stored as part of the agent session.

The agent's tools never receive unrestricted database credentials. They communicate with narrow PHP endpoints created for specific operations such as:

  • confirming the sender's identity;
  • retrieving the sender's own appointments;
  • listing professionals;
  • retrieving professional working hours;
  • searching real availability;
  • preparing and confirming a new appointment;
  • replacing a pending proposal;
  • escalating the conversation to the human team.

The Cloud Run deployment has been validated with a public health check and a protected functional endpoint. Calls without the required gateway token are rejected.

The deployment uses scale-to-zero and a maximum instance limit to control costs during the hackathon.

Challenges

The hardest part of the project was not making Gemini generate conversational responses.

The harder problem was deciding how much authority an AI agent should have inside a real healthcare management system.

A scheduling conversation may look simple, but it quickly becomes a multi-step workflow.

The agent needs to understand:

  • whether the patient wants a new appointment or information about an existing one;
  • which professional is requested;
  • the professional's configured working hours;
  • actual schedule availability;
  • dates, times, periods, exclusions, and alternative preferences;
  • whether enough information exists to continue;
  • whether the patient has selected one of the offered options;
  • whether explicit confirmation has been provided;
  • whether the operation remains within the agent's authorized scope;
  • when a human should take over.

Another challenge was ensuring that conversational flexibility could not bypass deterministic application rules.

A language model can interpret what a patient means, but it must not invent available times, select a patient identity, or directly modify sensitive application data.

That led me to separate reasoning from execution.

Gemini interprets the request and proposes the next action. Google ADK coordinates the agent and invokes an authorized tool. The PHP backend validates and executes the actual operation.

I also had to handle ambiguity carefully.

A response such as “the first one,” “day 31,” “around 3 PM,” or “any day except Monday” can only be interpreted correctly when the previous options and conversation context are preserved.

The agent therefore combines natural-language interpretation with deterministic results returned by the scheduling backend.

Another important challenge was designing the transition between autonomous and human workflows.

Instead of treating escalation as a failure, I designed it as a normal and explicit part of the architecture. When the agent reaches a situation that requires human judgment, it deliberately transfers the conversation to the support queue.

What I learned

The biggest lesson from building Prontagenda AI Agent is that an effective agent is not defined by how much it talks.

It is defined by what it can safely accomplish.

Connecting a language model to a real application changes the design problem completely.

Prompt quality is important, but so are:

  • authentication;
  • identity boundaries;
  • short-lived signed context;
  • least-privilege tools;
  • deterministic business rules;
  • explicit confirmation;
  • transaction safety;
  • error handling;
  • observability;
  • human escalation.

I also learned that the most useful workflows are often not the most spectacular ones.

Checking a real schedule, finding a suitable time, understanding a patient's preference, collecting the required information, and creating an appointment can remove several repetitive steps from a clinic's daily routine.

When those steps happen dozens of times per day, their operational impact becomes significant.

The project also reinforced the importance of keeping AI reasoning separate from direct data access.

Giving the agent narrow, controlled tools instead of unrestricted database access made the architecture safer, easier to audit, and easier to evolve.

Another important lesson was that human oversight should not be added as an afterthought. It should be designed as a first-class agent capability.

A reliable agent needs to know not only how to act, but also when not to act.

Why it matters

Healthcare professionals should spend their time caring for patients, not repeatedly moving information between conversations and management systems.

Prontagenda AI Agent demonstrates how an existing healthcare platform can evolve from traditional software into an agentic system that understands requests, selects appropriate actions, executes controlled workflows, and knows when a human should take over.

The objective is not to remove people from the workflow.

It is to remove unnecessary repetitive work from people while keeping authorization, business rules, and sensitive data under the application's control.

Prontagenda started as a way to organize the clinic.

With the new agentic layer, it is becoming a system that can actively help operate it.

Built With

Share this project:

Updates