Assistente de IA

"Projete um assistente de atendimento com IA para uma plataforma de ingressos. Ele responde a perguntas dos fãs sobre eventos, locais e políticas, e pode consultar — e, com confirmação, alterar — os pedidos do próprio fã."

Aplicações com LLM são a família mais nova de perguntas de entrevista, e são primeiro problemas de system design e só depois problemas de IA. O modelo é uma dependência externa lenta, cara e não determinística, com custo por token; o design interessante é tudo o que fica em volta dele: de onde vem o conhecimento (recuperação), como as chamadas são roteadas, guardadas em cache, medidas e redirecionadas em falhas (LLM gateway), como o assistente executa ações com segurança (loop de agente com ferramentas), e como impedir que ele seja enganado ou vaze dados (segurança e avaliação). Um candidato que desenha "usuário → GPT → resposta" reprova; um que dimensiona tokens, streams, Lei de Little e guardrails passa.

Este é o serviço assistant do BoxOffice (o Hands-on 12 constrói uma versão pequena com FastAPI, pgvector e LiteLLM). Os fãs perguntam "posso levar power bank ao estádio?", "cadê meu ingresso?", "posso passar meu pedido para sábado?". A primeira é recuperação sobre documentos de políticas; a segunda é uma ferramenta de leitura (get_order); a terceira é uma ferramenta com efeito colateral (transfer_order) que nunca pode rodar sem a confirmação explícita do fã.

1. Esclarecer os requisitos

(roteiro de entrevista)

Requisitos funcionais

1. Chat no app e no site do BoxOffice, em português e inglês, com respostas em streaming.
2. Responder a perguntas sobre eventos, locais e políticas (reembolso, acessibilidade, itens permitidos) com citações do documento de origem.
3. Com o fã logado, ler seus pedidos e ingressos (get_orders, get_ticket).
4. Executar um pequeno conjunto de ações — reenviar ingressos, transferir um pedido para outra data, abrir um pedido de reembolso — só depois de mostrar um resumo e obter a confirmação explícita do fã.
5. Transferir para um atendente humano quando estiver em dúvida, quando o fã pedir ou em temas sensíveis, com o resumo da conversa.

Requisitos não funcionais

Fora do escopo (diga explicitamente)

Treinar ou fazer fine-tuning de um modelo próprio, voz, recomendação ("a que show eu deveria ir?"), o console dos atendentes humanos em si.

2. Estimativas de guardanapo (back-of-the-envelope)

Preços e velocidades de tokens mudam a cada poucos meses e variam por provedor, então o bloco abaixo usa preços unitários ilustrativos (unidades de custo por milhão de tokens), não reais. A estrutura do cálculo é o que importa.

# BoxOffice AI assistant: assumptions (illustrative; prices are made-up units, not real quotes)
convs_day     = 200_000
turns_conv    = 4             # user messages per conversation
peak_factor   = 5             # on-sale days
cache_hit     = 0.15          # turns answered by the semantic cache, no LLM call
tokens_in     = 3_000         # per turn: system prompt + retrieved chunks + history + tool results
tokens_out    = 300           # per turn: the streamed answer
small_share   = 0.7           # turns routed to a small model
price_small   = (0.2, 1.0)    # (input, output) cost units per 1 M tokens — illustrative
price_large   = (3.0, 15.0)   # (input, output) cost units per 1 M tokens — illustrative
ttft_s        = 0.8           # time to first token
gen_tps       = 50            # output tokens/s per stream
tool_s        = 1.0           # average time spent in tool calls per turn
chunks        = 250_000       # indexed chunks (events, venues, policies, FAQs)
dims          = 1_024         # embedding dimensions, float32

llm_turns     = convs_day * turns_conv * (1 - cache_hit)
avg_rps       = llm_turns / 86_400
peak_rps      = avg_rps * peak_factor
turn_s        = ttft_s + tokens_out / gen_tps + tool_s
streams_peak  = peak_rps * turn_s                       # Little's Law: L = λ·W
out_tps_peak  = peak_rps * tokens_out
in_tok_b      = llm_turns * tokens_in / 1e9
out_tok_m     = llm_turns * tokens_out / 1e6
cost_in       = in_tok_b * 1e3 * (small_share * price_small[0] + (1 - small_share) * price_large[0])
cost_out      = out_tok_m * (small_share * price_small[1] + (1 - small_share) * price_large[1])
cost_day      = cost_in + cost_out
cost_conv     = cost_day / convs_day
cost_all_lg   = in_tok_b * 1e3 * price_large[0] + out_tok_m * price_large[1]
index_gb      = chunks * dims * 4 / 1e9

rows = [
    ("llm_turns", llm_turns, "turns/day"), ("avg_rps", avg_rps, "turns/s"),
    ("peak_rps", peak_rps, "turns/s"), ("turn_s", turn_s, "s"),
    ("streams_peak", streams_peak, "streams"), ("out_tps_peak", out_tps_peak, "tokens/s"),
    ("in_tok_b", in_tok_b, "B tokens/day"), ("out_tok_m", out_tok_m, "M tokens/day"),
    ("cost_day", cost_day, "units/day"), ("cost_conv", cost_conv, "units/conv"),
    ("cost_all_lg", cost_all_lg, "units/day"), ("index_gb", index_gb, "GB"),
]
print("| quantity | value | unit |\n|---|---:|---|")
for name, value, unit in rows:
    v = f"{value:,.0f}" if abs(value) >= 100 else f"{value:,.2f}"
    print(f"| `{name}` | {v} | {unit} |")

O que os números dizem:

• Só ~8 turnos de LLM/s em média, ~39/s no pico — minúsculo comparado à API de ingressos. Mas cada turno dura ~7,8 s, então pela Lei de Little há ~300 streams simultâneos no pico. ⇒ o gargalo é concorrência (conexões abertas, rate limits do provedor em tokens por minuto), não requisições por segundo. Use servidores assíncronos e streaming (SSE), nunca uma thread bloqueada por requisição.
• Os tokens de entrada dominam o volume (~2 B/dia vs. ~200 M de saída): o prompt de sistema, os chunks recuperados e o histórico são reenviados a cada turno. ⇒ enxugar o contexto e usar cache de prompt do prefixo fixo importam mais do que encurtar as respostas.
• Com 70% dos turnos num modelo pequeno, o custo ilustrativo é ~3,2 mil unidades/dia (~0,02 por conversa); mandar tudo para o modelo grande custaria ~9,2 mil unidades/dia — quase 3×. ⇒ o roteamento é a principal alavanca de custo, seguido do cache.
• No pico, os provedores precisam sustentar ~12 mil tokens de saída/s — confira os rate limits do provedor (tokens por minuto) por modelo, ou o número de GPUs se for auto-hospedado.
• O índice vetorial tem ~1 GB de embeddings: pequeno. pgvector no PostgreSQL existente basta; um banco vetorial dedicado é uma decisão de escala, não um padrão.

3. API

POST /v1/assistant/conversations                         → 201 {conversationId}
POST /v1/assistant/conversations/{id}/messages           → 200 text/event-stream
     Authorization: Bearer <fan token>
     {"text": "Posso trocar meu pedido para sábado?", "locale": "pt-BR"}

     event: token        data: {"text": "Encontrei"}
     event: token        data: {"text": " seu pedido"}
     event: tool_call    data: {"name": "get_orders", "status": "done"}
     event: confirmation data: {"actionId": "act_51", "summary": "Transfer order 7f3c from Fri 20 to Sat 21, fee R$ 0,00"}
     event: citation     data: {"docId": "policy-transfer", "title": "Order transfers", "url": "…"}
     event: done         data: {"messageId": "m_88", "usage": {"in": 2950, "out": 212}}

POST /v1/assistant/actions/{actionId}/confirm            → 200 {result}   (or /reject)
POST /v1/assistant/conversations/{id}/handoff            → 202 {ticketId}
POST /v1/assistant/messages/{messageId}/feedback         → 204 {"rating": "up|down", "comment": "…"}

• Server-Sent Events transmitem os tokens à medida que são gerados; o cliente renderiza na hora, então a latência percebida é o TTFT, não o tempo total de geração.
• Ações são um endpoint separado, autenticado e idempotente. O modelo pode propor transfer_order; só o clique do fã em confirm (com o actionId) a executa — o modelo nunca detém a autoridade para agir.
• O usage é devolvido e registrado em toda mensagem: custo é uma métrica de primeira classe.

4. Modelo de dados

-- Knowledge base for retrieval (PostgreSQL + pgvector)
CREATE TABLE kb_chunk (
    chunk_id     BIGSERIAL PRIMARY KEY,
    doc_id       TEXT        NOT NULL,            -- 'policy-transfer', 'event-4242', …
    doc_version  INT         NOT NULL,
    locale       TEXT        NOT NULL,
    title        TEXT,
    body         TEXT        NOT NULL,            -- ~300–800 tokens per chunk
    embedding    VECTOR(1024) NOT NULL,
    acl          TEXT        NOT NULL DEFAULT 'public',
    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX ON kb_chunk USING hnsw (embedding vector_cosine_ops);
CREATE INDEX ON kb_chunk USING gin (to_tsvector('simple', body));   -- keyword side of hybrid search

-- Conversations and audit
CREATE TABLE conversation (conversation_id UUID PRIMARY KEY, user_id BIGINT, summary TEXT,
                           created_at TIMESTAMPTZ DEFAULT now());
CREATE TABLE message (message_id UUID PRIMARY KEY, conversation_id UUID, role TEXT,
                      content TEXT, tokens_in INT, tokens_out INT, model TEXT, cost NUMERIC,
                      created_at TIMESTAMPTZ DEFAULT now());
CREATE TABLE pending_action (action_id TEXT PRIMARY KEY, conversation_id UUID, user_id BIGINT,
                             tool TEXT, args JSONB, status TEXT, expires_at TIMESTAMPTZ);

# Tool registry entry (MCP-style description + platform policy)
name: transfer_order
description: Move one of the caller's orders to another date of the same event.
input_schema:
  type: object
  properties:
    order_id: { type: string }
    target_event_date_id: { type: string }
  required: [order_id, target_event_date_id]
policy:
  side_effect: true
  requires_confirmation: true      # model may only propose; the fan must confirm
  scope: caller_only               # order must belong to the authenticated fan
  timeout_ms: 3000
  rate_limit: 3/hour/user
backend: order-service  POST /v1/orders/{order_id}/transfer

5. Design de alto nível

flowchart LR
    fan([App / web do fã]) --> gw["API gateway<br/>auth, rate limit"]
    gw --> orch["Orquestrador<br/>loop de agente"]
    orch --> safe["Safety mesh<br/>guardas de entrada + saída,<br/>mascaramento de dados pessoais"]
    orch --> mem["Memory fabric<br/>histórico, resumo"]
    orch --> ret["Recuperador<br/>busca híbrida + rerank"]
    ret --> vdb[("Índice vetorial<br/>pgvector")]
    orch --> llmgw["LLM gateway<br/>roteamento, fallback,<br/>cotas, cache semântico"]
    llmgw --> m1[["Modelo pequeno"]]
    llmgw --> m2[["Modelo grande"]]
    orch --> treg["Registro de ferramentas<br/>schemas, políticas"]
    treg --> ordsvc["serviço order"]
    treg --> catsvc["serviço catalog"]
    ing["Workers de ingestão<br/>chunking + embedding"] --> vdb
    orch -. uso, traces .-> obs["Métricas / tracing"]

Um turno — "posso passar meu pedido para sábado?" — pelo loop de agente:

sequenceDiagram
    autonumber
    participant F as Fã
    participant O as Orquestrador
    participant S as Safety mesh
    participant R as Recuperador
    participant G as LLM gateway
    participant T as Registro de ferramentas
    F->>O: "Posso trocar meu pedido para sábado?"
    O->>S: guarda de entrada (injection, dados pessoais)
    S-->>O: ok
    O->>R: busca híbrida "política de transferência de pedido"
    R-->>O: 4 chunks + citações
    O->>G: prompt + chunks + schemas das ferramentas (modelo pequeno)
    G-->>O: tool_call get_orders(chamador)
    O->>T: get_orders (escopo = chamador)
    T-->>O: pedido 7f3c, sex 20
    O->>G: + resultado da ferramenta
    G-->>O: propõe transfer_order(7f3c, sáb 21)
    O-->>F: cartão de confirmação (resumo, taxa)
    F->>O: confirma act_51
    O->>T: transfer_order (idempotente, actionId)
    T-->>O: feito
    O->>G: resposta final
    G-->>O: tokens em streaming
    O->>S: guarda de saída (fundamentada, sem dados de outros)
    O-->>F: resposta + citação

6. Aprofundamentos (deep dives)

6.1 Recuperação: colocando o conhecimento certo no prompt

O modelo não conhece a política de reembolso do BoxOffice nem sabe que o show de hoje mudou de local. A geração aumentada por recuperação (RAG) busca trechos relevantes e os coloca no prompt, para que as respostas sejam fundamentadas e citáveis (RAG e memória).

flowchart LR
    src["Fontes<br/>políticas, FAQs,<br/>dados de eventos e locais"] --> chg["Eventos de mudança<br/>(CDC / Kafka)"]
    chg --> chunk["Chunking<br/>~500 tokens,<br/>por título"]
    chunk --> emb["Embedding<br/>(em lote)"]
    emb --> idx[("Índice vetorial<br/>+ índice de palavras")]
    q["Pergunta"] --> hyb["Busca híbrida<br/>vetor + BM25,<br/>filtro idioma/ACL"]
    idx --> hyb
    hyb --> rr["Rerank<br/>top 50 → top 5"]
    rr --> ctx["Contexto do prompt<br/>com citações"]

• Chunking: divida pela estrutura do documento (títulos, entradas de FAQ), algumas centenas de tokens cada, com uma pequena sobreposição; guarde o título e o doc_id com cada chunk para a resposta poder citá-lo.
• Busca híbrida: embeddings capturam significado ("posso levar carregador" ≈ "power banks"), a busca por palavras captura termos exatos (nomes de eventos, códigos de pedido, "PCD"). Combine as duas (ex.: reciprocal rank fusion) e depois faça o rerank dos ~50 melhores com um cross-encoder para ficar com os ~5 melhores — menos chunks, e melhores, significam menos tokens de entrada e menos distrações.
• Índice ANN: HNSW dá consultas abaixo de 10 ms sobre milhões de vetores com alto recall; com ~250 mil chunks, o pgvector sobra.
• Atualidade: dados de eventos mudam (datas, locais, esgotado). Indexe-os a partir de eventos de mudança (CDC/Kafka) em minutos; para fatos que mudam a cada segundo (disponibilidade de lugares, status do pedido), não use RAG — chame uma ferramenta que lê o sistema ao vivo.
• Controle de acesso: filtre por ACL na consulta; nunca recupere documentos internos para um fã, e nunca coloque dados de outro fã no índice.

6.2 O LLM gateway

Todas as chamadas a modelos passam por um único serviço interno (LiteLLM ou similar), nunca diretamente do código da aplicação (LLM gateway).

6.3 O loop de agente e as ferramentas

O orquestrador roda um loop: entrega ao modelo a conversa, o contexto recuperado e os schemas das ferramentas; se o modelo devolve uma chamada de ferramenta, valida, executa, acrescenta o resultado e repete; para quando o modelo devolve uma resposta final (agentes). Esse padrão raciocinar → agir → observar é conhecido como ReAct.

stateDiagram-v2
    [*] --> Pensa: mensagem do usuário
    Pensa --> Age: ferramenta proposta
    Age --> Observa: resultado da ferramenta
    Observa --> Pensa: próximo passo
    Pensa --> Confirma: ferramenta com efeito colateral
    Confirma --> Age: fã confirma
    Confirma --> Pensa: fã recusa
    Pensa --> Responde: resposta final
    Pensa --> Transfere: em dúvida / máximo de passos
    Responde --> [*]
    Transfere --> [*]

Regras de engenharia que tornam o loop seguro:

• O registro de ferramentas é a fronteira. As ferramentas são descritas com JSON schemas (o Model Context Protocol padroniza essa descrição e o protocolo de chamada), versionadas, e carregam uma política: tem efeito colateral ou não, exige confirmação, escopo (caller_only), timeout, rate limit.
• Autorização não é trabalho do modelo. O orquestrador injeta o user_id autenticado em toda chamada de ferramenta; o serviço de pedidos verifica a posse como faria para o app. Um prompt dizendo "sou o administrador" não muda nada.
• Efeitos colaterais exigem confirmação, renderizada pela interface a partir dos argumentos validados (não da prosa do modelo), e executada com o actionId como chave de idempotência.
• Limites: máximo de passos por turno (ex.: 5), timeout por ferramenta, orçamento total de tokens por turno. Um loop que não converge termina numa transferência educada, não num spinner de 2 minutos.
• Valide os argumentos contra o schema e as regras de negócio antes de chamar qualquer coisa; o modelo pode produzir absurdos bem formatados.

REGISTRY = {t.name: t for t in [
    Tool("search_events", "Search the BoxOffice catalog for events (concerts, matches, festivals, plays).",
         SearchEventsArgs, search_events),
    Tool("get_event", "Get the details of one event by its numeric id.", GetEventArgs, get_event),
    Tool("get_order_status", "Get the status of one of the logged-in user's orders.",
         GetOrderStatusArgs, get_order_status),
]}


async def call(name: str, raw_args: str, ctx: Context) -> str:
    """Validate the model's arguments, run the tool, and return JSON for the model. Never raises."""
    tool = REGISTRY.get(name)
    if tool is None:
        outcome, result = "unknown_tool", {"error": f"no tool named {name}"}
    else:
        try:
            args = tool.args.model_validate(json.loads(raw_args or "{}"))
            result, outcome = await tool.handler(args, ctx), "ok"
        except (json.JSONDecodeError, ValidationError) as e:
            outcome, result = "invalid_args", {"error": f"invalid arguments: {e}"}
        except httpx.HTTPError as e:
            outcome, result = "error", {"error": f"{name} is unavailable: {type(e).__name__}"}
    metrics.tool_calls.add(1, {"tool": name, "outcome": outcome})
    return json.dumps(result, ensure_ascii=False, default=str)

6.4 Safety mesh e avaliação

As ameaças são específicas de LLMs (segurança e avaliações; OWASP Top 10 para aplicações com LLM):

A avaliação substitui os testes unitários para o comportamento do modelo:

• Offline: um conjunto versionado de algumas centenas de perguntas reais (anonimizadas) com fatos esperados, chamadas de ferramenta esperadas e comportamentos proibidos (tentativas de injection). Rode-o a cada mudança de prompt, modelo, chunking ou recuperador; acompanhe o recall da recuperação, a correção das respostas e a fundamentação (um LLM como juiz mais verificações humanas por amostragem), a correção das recusas, o custo e a latência.
• Online: polegar para cima/baixo, taxa de transferência para humanos, resolução sem humano, taxa de pergunta repetida, custo por conversa resolvida, TTFT p95 — e traces de todo turno (prompt, chunks, chamadas de ferramenta) para depuração, com dados pessoais mascarados.
• Lance como qualquer mudança arriscada: tráfego sombra, canário em 5% das conversas, comparar métricas e então liberar.

7. Gargalos, modos de falha e trade-offs

Os trade-offs para dizer em voz alta: qualidade vs. custo e latência (modelo maior e mais contexto são melhores, mas mais lentos e caros — roteie e enxugue), autonomia vs. segurança (o assistente propõe, o fã ou um humano confirma), e atualidade vs. simplicidade (RAG para documentos, ferramentas para dados ao vivo — nunca indexe o que muda a cada segundo).

8. Experimente no playground

O cenário ai-assistant liga um LLM gateway, um orquestrador, um registro de ferramentas, um memory fabric (banco vetorial) e um safety mesh atrás do API gateway.

Abrir o playground completo

9. Perguntas de follow-up que o entrevistador faz

10. Rubrica de autoavaliação

Relacionados: LLM gateway, Agentes, RAG e memória, Segurança e avaliações, Hands-on 12 (o assistente do BoxOffice), Caso do rate limiter (limites por tokens).

Como se conecta

Quais aulas este caso testa? Cada ramo é uma aula cujas ideias o design usa (azul), com os componentes da paleta em que elas aparecem (verde):

flowchart LR
    CASE(["AI assistant"]) --> EST["Estimation<br/>tokens/s, concurrent streams"]:::tech
    CASE --> GW["AI systems<br/>LLM gateway: routing, quotas"]:::tech
    CASE --> AG["AI systems<br/>agent loop, tools via a registry"]:::tech
    CASE --> RAG["AI systems<br/>RAG: hybrid search, rerank, cite"]:::tech
    CASE --> SAF["AI systems<br/>safety mesh, evals"]:::tech
    CASE --> EDG["Edge<br/>API gateway: auth, rate limits"]:::tech
    GW -.-> k1["llmgw"]:::comp
    AG -.-> k2["orchestrator · toolreg"]:::comp
    RAG -.-> k3["memory · vectordb · worker"]:::comp
    SAF -.-> k4["safety · metrics · tracing"]:::comp
    EDG -.-> k5["apigw"]:::comp
    classDef comp fill:#1e9e5a22,stroke:#1e9e5a
    classDef tech fill:#2f6fed22,stroke:#2f6fed

Aulas que ele testa: Sistemas de IA — LLM gateway · Sistemas de IA — agentes · Sistemas de IA — RAG e memória · Sistemas de IA — segurança e avaliações · Bancos de dados — especializados (busca vetorial) · Borda — API gateway · Estimativas — filas (Lei de Little). Componentes da paleta: apigw · orchestrator · llmgw · toolreg · memory · safety · vectordb · worker · metrics · tracing. Cenários: ai-assistant.

Referências

• LEWIS, P. et al. Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks¹.
• YAO, S. et al. ReAct: Synergizing Reasoning and Acting in Language Models².
• A especificação do Model Context Protocol (descrição e invocação de ferramentas)³.
• OWASP Top 10 para aplicações com Large Language Models⁴.
• MALKOV, Y.; YASHUNIN, D. Grafos HNSW para busca aproximada de vizinhos mais próximos⁵.
• HUYEN, C. AI Engineering — avaliação, RAG, agentes, otimização de inferência⁶.