Construindo um AI-React-Agent

Por

Você quer um agente de AI que realmente raciocina, consulta bancos de dados e usa ferramentas de forma inteligente, não um chatbot que reformula sua pergunta com um tom ligeiramente diferente. O padrão ReAct com LangGraph e Azure OpenAI é como você constrói isso.

TL;DR: Construa um agente de AI pronto para produção usando o padrão ReAct do LangGraph com Elasticsearch (busca vetorial), Neo4j (recomendações por grafo) e Streamlit (UI), deployado no Azure OpenAI.
Stack: Python, LangGraph, LangChain, Azure OpenAI, Elasticsearch, Neo4j, Streamlit, Poetry
Nível: Avançado
Tempo de leitura: ~20 min

Construí esse tipo de sistema para uma plataforma real de mídia, para alimentar busca inteligente e recomendações em catálogos de conteúdo. A arquitetura aqui segue o mesmo padrão, adaptado como tutorial independente. Não é trivial, mas se seguir cada etapa você terá um agente real, não um brinquedo de demo.

Configurando o Poetry

Porque gerenciar dependências manualmente é um tipo de sofrimento que não aceitamos mais.

poetry init

pyproject.toml

[tool.poetry]
name = "ai-react-agent-azure"
version = "0.1.0"

[tool.poetry.dependencies]
python = "^3.10"
langchain = "^0.3.14"
langchain-openai = "^0.3.0"
langgraph = "^0.2.62"
streamlit = "^1.41.1"
elasticsearch = "^8.17.1"
neo4j = "^5.28.1"
python-dotenv = "^1.0.1"
poetry shell
poetry install

Estado (state.py)

O LangGraph é baseado em máquina de estados. Esse arquivo define o objeto de estado compartilhado que flui entre cada nó do grafo do agente.

from typing import Annotated, TypedDict, Union
from langchain_core.agents import AgentAction, AgentFinish
import operator

class AgentState(TypedDict):
    input: str
    agent_outcome: Union[AgentAction, AgentFinish, None]
    intermediate_steps: Annotated[list[tuple[AgentAction, str]], operator.add]

Ferramentas (tools.py)

A caixa de ferramentas. Porque um agente ReAct sem ferramentas é só um chatbot com opiniões fortes. O agente tem quatro ferramentas: busca vetorial via Elasticsearch, recomendações por grafo social via Neo4j, consultas de promoção e um fallback de chat geral.

Agente ReAct (react.py)

É aqui que a mágica acontece, ou onde você passa 3 horas depurando por que o agente fica chamando a ferramenta errada.

from langchain import hub
from langchain.agents import create_react_agent
from langchain_openai import ChatOpenAI

react_prompt = hub.pull("hwchase17/react")
llm = ChatOpenAI(model="gpt-3.5-turbo-1106")
react_agent_runnable = create_react_agent(llm, tools, react_prompt)

Nós (nodes.py)

from langgraph.prebuilt.tool_executor import ToolExecutor

def run_agent_reasoning_engine(state: AgentState):
    agent_outcome = react_agent_runnable.invoke(state)
    return {"agent_outcome": agent_outcome}

tool_executor = ToolExecutor(tools)

def execute_tools(state: AgentState):
    agent_action = state["agent_outcome"]
    output = tool_executor.invoke(agent_action)
    return {"intermediate_steps": [(agent_action, str(output))]}

Grafo (run.py)

from langgraph.graph import END, StateGraph

def should_continue(state: AgentState) -> str:
    if isinstance(state["agent_outcome"], AgentFinish):
        return END
    return "act"

flow = StateGraph(AgentState)
flow.add_node("agent_reason", run_agent_reasoning_engine)
flow.add_node("act", execute_tools)
flow.set_entry_point("agent_reason")
flow.add_conditional_edges("agent_reason", should_continue)
flow.add_edge("act", "agent_reason")
app = flow.compile()

Configurando Elasticsearch localmente

sudo apt-get install elasticsearch -y
sudo systemctl enable elasticsearch
sudo systemctl start elasticsearch
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic -i

Configurando Neo4j localmente

sudo apt install neo4j -y
sudo neo4j-admin set-initial-password suasenha
sudo systemctl enable neo4j
sudo systemctl start neo4j
# Acesse: http://localhost:7474/browser/

O que você construiu

Um agente de AI completo com padrão de produção: um loop ReAct do LangGraph que orquestra raciocínio do Azure OpenAI, busca vetorial no Elasticsearch e recomendações baseadas em grafo no Neo4j, tudo embrulhado em uma interface Streamlit. A arquitetura lida com seleção de ferramentas, verificação e fallback. Mais importante, roda o mesmo padrão tanto com bancos locais quanto com serviços em nuvem.

Próximos passos

  • Adicione rastreamento LangSmith para observar cada etapa de raciocínio e chamada de ferramenta. Invalvável quando o agente começa a fazer algo inesperado.
  • Expanda a camada de ferramentas com um banco de dados específico do seu domínio e veja o agente se especializar sem mudar a estrutura do grafo.
  • Faça deploy do app Streamlit como um serviço containerizado no Azure Container Apps com identidade gerenciada, para que as chaves de API nunca fiquem em arquivos de ambiente no servidor.

Dúvidas ou feedback? Me encontre no LinkedIn ou GitHub.

Deixe um comentário