Backend de Agente com FastAPI
Ir para notas que citam estaBackend de agente com FastAPI é a camada HTTP que expõe um grafo de agentes pronto a um frontend de chat, sem precisar rodar o projeto pela IDE.
Enquanto o grafo roda só no terminal, a pergunta fica fixa no código e a resposta aparece misturada aos logs. Colocá-lo atrás de um endereço HTTP separa o agente da interface: qualquer cliente, seja uma página de chat, outro sistema ou uma ferramenta de teste de API, envia a mensagem e recebe a resposta sem conhecer nada do LangGraph por dentro. A interface pode ser trocada à vontade, desde que respeite o contrato da rota.
Dependências e contrato de entrada e saída
Três dependências entram no projeto, adicionadas com o uv: requests, uvicorn (para subir um servidor simples) e fastapi (para declarar os endpoints).
O contrato fica num arquivo de esquemas com duas classes baseadas no BaseModel do Pydantic. A requisição tem dois campos: a consulta do usuário, uma string com descrição declarada via Field, e o identificador da sessão. A resposta devolve a sessão e a saída, que é a resposta final do modelo.
O identificador de sessão é o mesmo usado como thread id nos checkpoints. Enquanto o grafo roda pela IDE ele é um valor fixo ou aleatório. Com o backend, passa a vir do frontend, e é isso que permite a cada conversa retomar o próprio histórico.
Inicialização uma vez só
Carregar a base vetorial e compilar o grafo pode demorar. Fazer isso a cada requisição tornaria cada resposta lenta. A solução é uma função assíncrona decorada com @asynccontextmanager, que faz o carregamento e a compilação uma única vez, na subida da aplicação, e depois cede o controle com yield. Essa função é passada no parâmetro lifespan da instância do FastAPI.
O grafo compilado fica numa variável global, declarada como vazia fora da função e redeclarada como global dentro dela, para que todas as chamadas ao endpoint usem a mesma instância.
A rota e a extração da resposta
É preciso liberar CORS com o CORSMiddleware, abrindo origens, métodos e headers, para que um frontend servido em outra porta consiga chamar a API sem bloqueio do navegador. Liberar tudo resolve o ambiente local, mas é uma configuração de desenvolvimento.
O endpoint principal é um POST, com o modelo de resposta declarado, que recebe a requisição e usa a consulta e o identificador de sessão dela no lugar dos valores fixos dos testes. O caminho da rota segue o que o frontend já espera chamar.
O evento que o grafo devolve é um dicionário cuja chave é o nome do nó que respondeu. Como esse nome muda conforme o caminho que a pergunta percorreu, a resposta final é extraída pegando o primeiro valor do dicionário, sem depender do nome da chave. Por fim, o uvicorn sobe o servidor escutando em todas as interfaces, na porta que o frontend está configurado para chamar.
O backend é o que carrega o agente. O frontend de chat pode ser um projeto já pronto e reaproveitado, bastando rodar o backend em Python e servir os arquivos estáticos da interface em outra porta local. Com os dois de pé, uma saudação cai no agente de saudação e uma dúvida técnica passa pelo classificador, pela busca na base e pelo validador antes de voltar à tela.