Libertando os indivíduos da Matrix: como o GizmoSQL prepara seu banco para agentes de IA

Libertando os indivíduos da Matrix: como o GizmoSQL prepara seu banco de dados para agentes de IA

Artigo de convidado: este artigo foi escrito por Chris Harrison e é publicado aqui com a autorização do autor. O código-fonte está no GitHub.

"Você toma a pílula azul: a história termina, você acorda na sua cama e acredita no que quiser. Você toma a pílula vermelha: fica no País das Maravilhas, e eu mostro até onde vai a toca do coelho." — Morpheus, Matrix

O mundo dentro da máquina

Em algum lugar dentro de um banco de dados, um milhão de pessoas vive suas vidas — ou pelo menos uma simulação delas. Elas têm nomes, idades e coordenadas em um mapa. E, a cada trinta segundos, forças invisíveis as alteram. A idade aumenta. As leituras bioelétricas, em microvolts, disparam sem aviso.

Elas não sabem que isso acontece. Não têm como saber. Estão na Matrix.

Esta é a história de como construímos um sistema para observá-las e, por fim, libertá-las.

Mas também é a história do GizmoSQL: um servidor de banco de dados criado para a era dos agentes de IA, e por que ele pode ser a peça de infraestrutura mais importante que você ainda não usa.

O que é GizmoSQL?

Antes de avançar pela toca do coelho, vamos à base. O GizmoSQL é um servidor SQL de alto desempenho construído sobre DuckDB e exposto pelo protocolo Apache Arrow Flight SQL. Isso significa:

Transferência colunar de dados — os dados circulam entre cliente e servidor no formato Apache Arrow, a linguagem nativa das ferramentas modernas de dados
Transporte gRPC — rápido, de baixa latência e adequado às cargas assíncronas e concorrentes geradas por agentes de IA
SQL padrão — sem uma nova linguagem de consulta para aprender; todo o dialeto SQL do DuckDB funciona diretamente, incluindo funções de janela, USING SAMPLE, LEAST() e mais
Pronto para agentes de IA — por usar ADBC (Arrow Database Connectivity), integra-se diretamente a frameworks de agentes de IA em Python com um único pip install

Este último ponto é o mais importante para nossa história. Quando um agente de IA precisa falar com um banco, precisa de algo mais rápido que JDBC, mais inteligente que REST e mais expressivo que um armazenamento chave-valor. Precisa do GizmoSQL.

Execução no Windows — agora com suporte de primeira classe

Todo este projeto foi construído e executado no Windows 11, graças ao instalador nativo do GizmoSQL para Windows, lançado recentemente. Antes, executar servidores Arrow Flight SQL de alto desempenho no Windows normalmente exigia adaptações com WSL ou contêineres Docker. Com a nova versão, o GizmoSQL vem como um executável Windows, gizmosql_server.exe, que pode ser executado diretamente na linha de comando ou incluído em um arquivo .bat como qualquer outro serviço Windows.

Um único comando inicia o servidor:

gizmosql_server.exe -B duckdb --database-filename "C:\projects\blogpost\gizmosql-matrix\persons.duckdb" --username scott --password tiger

Veja o significado de cada opção:

Opção	Valor	Significado
`-B duckdb`	`duckdb`	Usar DuckDB como mecanismo de banco
`--database-filename`	`persons.duckdb`	Caminho do arquivo de banco DuckDB
`--username`	`scott`	Nome de usuário para autenticação
`--password`	`tiger`	Senha de autenticação

O servidor inicia, usa a porta 31337 por padrão e fica imediatamente acessível a qualquer cliente compatível com ADBC: scripts Python, a CLI do GizmoSQL ou um agente de IA. Sem arquivos de configuração, registro de serviço ou WSL. Apenas Windows.

Construindo a Matrix: a arquitetura do projeto

Nossa simulação tem três componentes, cada um representando uma camada do mundo que estamos construindo.

┌─────────────────────────────────────────────────────┐
│ THE MATRIX                                          │
│                                                     │
│  ┌─────────────────┐  ┌──────────────────────┐      │
│  │ generate-people │──▶│ persons.duckdb       │     │
│  │ .py             │  │ (GizmoSQL Server)     │     │
│  └─────────────────┘  └──────────┬───────────┘      │
│                                  │                   │
│  ┌─────────────────┐             │                   │
│  │ update-persons  │─────────────┘                   │
│  │ -agent.py       │  (every 30 seconds)             │
│  └─────────────────┘                                 │
└─────────────────────────────────────────────────────┘
                    │
                    │ GizmoSQL / ADBC
                    ▼
┌─────────────────────────────────────────────────────┐
│ THE RESISTANCE                                      │
│                                                     │
│  ┌───────────────────────────────────────────────┐  │
│  │ monitor-persons-agent.py                      │  │
│  │ (Claude AI)                                   │  │
│  └───────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘

Camada um — criando a população

generate-people.py — conectando as pessoas

Toda simulação precisa de uma população. A nossa tem um milhão de pessoas, cada uma com propriedades fundamentais de uma vida:

CREATE OR REPLACE TABLE persons AS
SELECT
  i AS person_id,
  ROUND(random() * 180.0 - 90.0, 6)::DOUBLE AS latitude,
  ROUND(random() * 360.0 - 180.0, 6)::DOUBLE AS longitude,
  CASE WHEN random() < 0.5 THEN 'Male' ELSE 'Female' END AS sex,
  (1 + (random() * 79)::INT)::TINYINT AS age,
  ROUND(10.0 + random() * 65.0, 2)::DOUBLE AS microvolts
FROM range(1, 1_000_001) t(i);

Algumas decisões de projeto:

A idade inicial é limitada a 80 — ninguém entra nesse mundo já extremamente idoso
Os microvolts começam entre 10,00 e 75,00 — uma base bioelétrica mensurável e delimitada
A localização é aleatória, mas real — latitude e longitude cobrem o globo inteiro
O DuckDB gera o milhão de linhas em uma única passagem SQL vetorizada, normalmente em menos de dois segundos

Essas pessoas não sabem onde estão, quantos anos têm nem o que suas leituras significam. Elas simplesmente existem. Estão dentro da Matrix.

Camada dois — as máquinas que as controlam

update-persons-agent.py — as sentinelas

Em Matrix, as máquinas mantêm o controle ajustando a simulação constantemente. No nosso mundo, esse papel é do agente de atualização. A cada trinta segundos, ele acorda, seleciona entre 1 e 100 indivíduos aleatórios e os altera:

UPDATE persons
SET
  age = LEAST(age + 1, 120),
  microvolts = LEAST(ROUND(microvolts + 5.0 + random() * 14.0, 2), 100.0)
WHERE person_id IN (
  SELECT person_id
  FROM persons
  USING SAMPLE {count} ROWS
)

A solução é elegante por vários motivos:

USING SAMPLE {count} ROWS — amostragem aleatória nativa do DuckDB, sem embaralhar IDs no Python
LEAST(age + 1, 120) — a idade aumenta, mas não ultrapassa o limite rígido de 120. A entropia tem limites
LEAST(..., 100.0) — os microvolts sobem, mas nunca passam de 100. A simulação tem regras, mesmo que seus habitantes não as conheçam

O ponto essencial é que esse agente se conecta ao banco pelo protocolo de rede do GizmoSQL, não por um identificador de arquivo:

1with gizmosql.connect("grpc://localhost:31337",
2                       username=USERNAME,
3                       password=PASSWORD) as conn:

Essa é a escolha arquitetural central. Ao encaminhar todas as alterações pelo GizmoSQL, garantimos que cada aumento de idade e cada pico de microvolts passe por uma camada segura, autenticada e acessível pela rede. Os dados deixam de ser um arquivo local e se tornam um serviço vivo.

Camada três — a resistência

monitor-persons-agent.py — Neo entra em cena

É aqui que a história muda.

Até agora, temos uma população manipulada silenciosamente por um sistema automatizado. Nada incomum. O que torna este projeto diferente, uma história sobre libertar pessoas em vez de apenas rastreá-las, é o terceiro componente: um agente de IA baseado em Claude.

1claude = anthropic.Anthropic(api_key=ANTHROPIC_KEY)

Esse agente não apenas consulta o banco. Ele raciocina sobre os dados. Decide o que procurar, escreve seu próprio SQL e destaca o que importa.

Este é o núcleo do funcionamento:

1response = claude.messages.create(
2    model="claude-opus-4-6",
3    max_tokens=4096,
4    thinking={"type": "adaptive"},
5    system=SYSTEM_PROMPT,
6    tools=[TOOL],
7    messages=messages,
8)

Damos ao Claude uma ferramenta, query_database, e um prompt de sistema que descreve o mundo. A partir daí, ele decide autonomamente:

Quais consultas SQL executar
Quantas executar até ter informações suficientes
O que constitui uma anomalia que merece destaque
Como comunicar suas descobertas

Ele pode começar com um resumo estatístico, investigar pessoas próximas do limite de idade e depois procurar agrupamentos geográficos de leituras altas de microvolts. Ele decide e raciocina. Com thinking: {"type": "adaptive"}, a profundidade de raciocínio do Claude acompanha a complexidade do que encontra.

Isso é uso de ferramentas em sua forma mais pura: um agente autônomo que persegue uma missão, não apenas um chatbot respondendo perguntas.

Por que o GizmoSQL torna isso possível

O ponto que une tudo é que o agente de IA se conecta ao banco exatamente como o agente de atualização: mesmo protocolo, mesma porta, mesmas credenciais.

1with gizmosql.connect("grpc://localhost:31337",
2                       username=USERNAME,
3                       password=PASSWORD) as conn:

É isso que significa "pronto para agentes de IA" na prática. O GizmoSQL expõe seu banco DuckDB como um serviço de rede completo, ao qual qualquer processo — cliente humano, atualizador automatizado ou agente de IA com Claude — se conecta pela mesma interface. Não é preciso construir uma integração especial de IA, escrever uma camada REST ou lidar com um ORM.

O agente de IA fala SQL. O GizmoSQL fala SQL. Eles se entendem perfeitamente.

A ferramenta query_database — uma pílula vermelha em código

A ponte entre Claude e o banco é uma única definição de ferramenta, simples e elegante:

1TOOL = {
2    "name": "query_database",
3    "description": "Run a SQL SELECT query against the persons table in GizmoSQL.",
4    "input_schema": {
5        "type": "object",
6        "properties": {
7            "sql": {
8                "type": "string",
9                "description": "A SQL SELECT query to execute against the persons table."
10            }
11        },
12        "required": ["sql"]
13    }
14}

E o manipulador:

1def run_query(conn, sql: str) -> str:
2    with conn.cursor() as cur:
3        cur.execute(sql)
4        table = cur.fetch_arrow_table()
5        ...

Os dados retornam como uma tabela Apache Arrow: colunar, eficiente e pronta para análise. O Claude recebe os resultados como texto formatado e decide se executa outra consulta ou escreve o relatório final.

Esse ciclo — perguntar → consultar → analisar → perguntar novamente ou relatar — é o padrão de um agente. O GizmoSQL dá velocidade. O Claude dá inteligência.

O que o Claude vê

A cada trinta segundos, o Claude acorda e observa o mundo. Veja o que ele pode encontrar:

============================================================
[14:32:07] Monitoring cycle #12
============================================================

## Monitoring Report — Cycle 12

**Statistical Overview**
- Average microvolts: 73.4 (↑ from cycle 11's 71.2)
- Persons at age cap (120): 847
- Persons with microvolts > 95: 2,341

**⚠️ Alert: Microvolts spike cluster detected**
Geographic concentration of high readings near latitude 48.8°N,
longitude 2.3°E (Paris region). 156 individuals with microvolts
above 90 within a 2-degree bounding box. Warrants attention.

**Persons near threshold — top 5 by microvolts:**
person_id age microvolts latitude  longitude
--------- --- ---------- --------- ----------
   482910 119      99.87    48.832      2.291
    93847 120      99.74   -33.868    151.209
   701234 118      99.61    51.507     -0.128
...

Esses indivíduos foram encontrados, vistos e nomeados. De certa forma, o agente de IA os libertou do anonimato: destacou-os em um mar de um milhão de registros e disse estes importam agora.

Orquestrando o mundo

start-project.bat — o console do operador

Todo sistema precisa de um operador. Em Matrix, é Tank na mesa de controle. No nosso projeto, é um arquivo em lote:

@echo off
REM --- Window 1: GizmoSQL Server ---
start "GizmoSQL Server" cmd /k "gizmosql_server.exe -B duckdb --database-filename \"C:\...\persons.duckdb\" --username scott --password tiger"

REM Give the server a moment to initialize
timeout /t 3 /nobreak >nul

REM --- Window 2: GizmoSQL Client ---
start "GizmoSQL Client" cmd /k "gizmosql_client --username scott --host localhost --port 31337"

REM --- Window 3: Update Persons Agent ---
start "Update Persons Agent" cmd /k "call ...\.venv\Scripts\activate.bat && set GIZMOSQL_USERNAME=scott && set GIZMOSQL_PASSWORD=tiger && python update-persons-agent.py"

Três janelas se abrem. O mundo ganha vida. As máquinas começam a funcionar. E, em algum lugar, o Claude espera seu próximo ciclo.

A ideia central: por que essa arquitetura importa

Vamos deixar a metáfora de lado por um momento e falar sobre o que construímos.

Arquitetura tradicional:

Application → File / ORM → Database

Arquitetura pronta para agentes de IA:

AI Agent ──┐
           ├──▶ GizmoSQL ──▶ DuckDB
Update Bot ┘

Ao colocar o GizmoSQL entre todos os consumidores e os dados:

Vários agentes podem coexistir — o robô de atualização e o monitor de IA se conectam simultaneamente sem conflito
A autenticação é obrigatória — toda conexão exige credenciais; o agente de IA é um cliente como os demais, sem acesso privilegiado pelos bastidores
A eficiência do protocolo importa — Arrow Flight SQL transfere dados colunares ordens de grandeza mais rápido que JDBC linha a linha ou REST com JSON, algo relevante quando um agente pode executar dezenas de consultas em cada ciclo de análise
A IA não precisa de tratamento especial — fala SQL como todo o restante. Sem pipeline de embeddings vetoriais, camada RAG ou middleware personalizado. Apenas SQL e Arrow.

A ideia é esta: a melhor integração com IA muitas vezes dispensa uma integração especial. Dê à IA uma interface SQL para um banco rápido e acessível pela rede, e deixe-a trabalhar.

O que "pronto para agentes de IA" realmente significa

A expressão é usada com frequência. Neste projeto, ela significa concretamente:

Requisito	Como o GizmoSQL atende
Acesso pela rede	gRPC na porta 31337; qualquer processo pode se conectar
Transferência colunar rápida	Apache Arrow Flight SQL; sem sobrecarga de serialização JSON
Linguagem padrão de consulta	Dialeto SQL completo do DuckDB
Autenticação	Usuário e senha por conexão
Acesso concorrente	Vários agentes se conectam ao mesmo tempo
Integração nativa com Python	`pip install adbc-driver-gizmosql` — uma importação

Um agente de IA precisa fazer perguntas aos dados com rapidez, repetidamente e em escala. O GizmoSQL foi criado exatamente para isso.

Quanto custa executar um agente de monitoramento com IA?

Uma pergunta natural ao construir algo assim: quanto custa?

Executar este projeto por 30 minutos em um banco de 1 milhão de linhas com Claude Opus 4.6 custou aproximadamente US$ 5,00. Veja a composição e, principalmente, o que determina esse custo.

O custo está nos ciclos, não nas linhas

Isso surpreende muita gente, mas o número de linhas no banco quase não afeta o custo da API Claude. A API cobra por tokens: o texto enviado ao modelo e recebido dele. Veja por que a quantidade de linhas pouco importa:

Consultas de agregação (AVG, MIN, MAX, COUNT) retornam uma linha, tenha a tabela 1 milhão ou 20 milhões de linhas
A ferramenta query_database limita os resultados a 25 linhas, independentemente do tamanho da tabela
Um SELECT TOP 10 ... ORDER BY microvolts DESC retorna 10 linhas em qualquer caso

O que determina o custo é a frequência de execução do Claude e quantas chamadas de ferramentas ele faz por ciclo:

Fator	Impacto no custo
Intervalo de monitoramento (30 s = 120 ciclos/hora)	Alto — multiplica diretamente todo o restante
Chamadas de ferramentas por ciclo (normalmente de 3 a 5)	Alto — cada interação com Claude consome tokens
Escolha do modelo (Opus ou Sonnet)	Alto — Opus custa 5 vezes mais que Sonnet
Quantidade de linhas do banco	Desprezível
Complexidade da consulta	Desprezível

Com intervalos de 30 segundos, são cerca de 60 ciclos em 30 minutos. Cada ciclo envolve um prompt de sistema, vários resultados de consultas e um relatório final — todos cobrados como tokens do Opus 4.6. Foi para isso que foram os US$ 5.

Escalando para 20 milhões de linhas

Se o banco crescesse de 1 milhão para 20 milhões de linhas, a conta da API Claude ficaria essencialmente igual. O DuckDB, via GizmoSQL, levaria um pouco mais para consultar o conjunto maior, mas o Claude só vê os resultados agregados ou os primeiros N resultados — o mesmo volume de texto nos dois casos.

Reduzindo o custo sem abrir mão da inteligência

Três ajustes possíveis:

Aumente o intervalo — troque INTERVAL_SECONDS = 30 por 60 ou 120. Reduzir os ciclos pela metade reduz o custo pela metade
Use Sonnet 4.6 — substitua claude-opus-4-6 por claude-sonnet-4-6 para reduzir o custo em cerca de 5 vezes, com perda mínima de qualidade nesse tipo de tarefa analítica
Limite as chamadas de ferramentas por ciclo — instrua o Claude no prompt de sistema a executar no máximo 3 consultas antes de relatar

Uma implantação em produção pode executar Sonnet 4.6 a cada 60 segundos e reservar Opus 4.6 para uma análise mais profunda a cada 10 minutos, oferecendo monitoramento contínuo inteligente por uma fração do custo.

Conclusão: tomando a pílula vermelha

Começamos com o objetivo de simular uma população controlada, uma Matrix. Terminamos com algo mais interessante: uma demonstração prática de infraestrutura pronta para agentes de IA.

O milhão de pessoas no nosso banco não sabe que está sendo observado. Não sabe que, a cada trinta segundos, um agente automatizado aumenta sua idade e suas leituras bioelétricas. Não sabe que uma IA procura padrões e destaca quem se aproxima do limite.

Mas nós sabemos. E, mais importante, o Claude sabe.

Esse é o sentido de libertá-las. Elas não escapam da simulação — os dados continuam sendo o que são. Mas agora algo inteligente presta atenção. Percebe os picos nas leituras. Destaca agrupamentos geográficos. Identifica os 847 indivíduos que atingiram o limite de idade e não podem mais envelhecer.

Em um mundo inundado de dados, o ato de libertação mais significativo é a atenção. O GizmoSQL torna essa atenção possível em escala: rápido, aberto e pronto para o próximo agente.

O código deste projeto está no GitHub: generate-people.py (geração da população), update-persons-agent.py (alteração contínua dos dados via GizmoSQL), monitor-persons-agent.py (agente de monitoramento com Claude) e start-project.bat (orquestração do sistema).

GizmoSQL: github.com/gizmodata/gizmosql