Chat Agent API

Uma API inteligente de chat construída com FastAPI e Strands Agents, capaz de realizar cálculos matemáticos e responder a perguntas gerais utilizando modelo de linguagem (LLM) local via Ollama. Foi também implementada uma web UI integrada, com tratamento de resposta da API, para melhor visualização de seu funcionamento.

Sumário

• Introdução
• Requisitos
• Instruções de Execução
• Documentação
• Licença

Introdução

A API é capaz de:

• Responder perguntas gerais usando conhecimento do modelo de linguagem.
• Realizar cálculos matemáticos complexos através de tools especializadas.
• Decidir automaticamente quando usar cálculos vs. conhecimento geral.
• Executar localmente sem dependência de serviços cloud.

Requisitos

Esta seção detalha os requisitos de software, modelo de linguagem e hardware necessários para executar a Chat Agent API.

Software Necessário

Componente	Versão	Link
Python	3.10+	Download Python
Ollama	Latest	Download Ollama

Modelo de Linguagem

O projeto utiliza um modelo de linguagem local via Ollama:

Modelo	Tamanho	Download
Llama 3.1 8B	~4.9GB	ollama pull llama3.1:8b

Hardware Recomendado

Para uma performance ideal, especialmente durante o carregamento do modelo:

• RAM: Mínimo 8GB, recomendado 16GB.
• GPU: Opcional, mas recomendada para melhor performance.
• Armazenamento: 10GB livres.

Instruções de Execução

Siga os passos abaixo para configurar e executar a Chat Agent API.

1. Clone do Repositório

Use o Git para clonar o projeto:

# Vá até o local onde deseja clonar o repositório e execute:
git clone https://github.com/GabrielCande/ChatAgentAPI

2. Instalação do Ollama

Baixe e execute o instalador em ollama.ai/download.

Abra o prompt de comando (CMD) e realize o download do modelo llama3.1:8b:

# Utilize o comando pull
ollama pull llama3.1:8b

# Ou utilize o comando run que também irá realizar o download
ollama run llama3.1:8b

3. Configuração do Ambiente

No CMD navegue até a raiz do diretório onde foi clonado o repositório:

# (apenas um exemplo de path)
cd C:\Gabriel\Github\ChatAgentAPI

Em seguida inicialize o ambiente:

# Cria o ambiente
python -m venv venv

# Ativa o ambiente
venv\Scripts\activate

Após a incialização do ambiente instale as bibliotecas necessárias:

# Dentro do ambiente ativo execute:
pip install -r requirements.txt

Por fim, crie um arquivo denominado ".env" na raiz do diretório do repositório clonado, manualmente ou pelo código seguinte no terminal:

# (apenas um exemplo de path)
cd C:\Gabriel\Github\ChatAgentAPI

# Cria arquivo .env
type nul > .env

Coloque neste arquivo a seguinte configuração:

OLLAMA_BASE_URL=http://localhost:11434
LLM_MODEL=llama3.1:8b

4. Início do Ollama

Abra um novo CMD para realizar a inicialização da execução do modelo llama3.1:8b instalado:

ollama serve

OBS.:

1. Esse CMD deverá continuar aberto, não o feche;

2. Caso o comando não funcione certifique-se de que o Ollama não está aberto ou em execução.

5. Execução da API

Volte para o CMD onde você está no ambiente criado dentro da raiz do diretório do repositório e execute os comandos:

# Em "(venv) C:\seu path\ChatAgentAPI>" execute:
# Para acessar a pasta src
cd src

# Para inicializar a API
python main.py

6. Realizando Testes

1. Para testar o funcionamento da API basta acessar, através de seu browser, a web UI integrada:

# URL da web UI:
http://localhost:8000/webui/

---

2. Caso queira verificar a raw response gerada é possível de se fazer via a documentação interativa automática da API, gerada pelo FastAPI usando Swagger UI:

# URL da documentação interativa:
http://localhost:8000/docs

Para testar utilizando essa interface basta seguir os passos:

• Clique na seção em verde "POST /chat Chat Endpoint" para expandi-la
• Em seguida clique no botão "Try it out" (primeiro botão a direita)
• Depois de precionar o botão você verá algo do tipo:

{
  "message": "string"
}

• Altere o conteúdo de "string" para a mensagem que deseja enviar, exemplo:

{
  "message": "Olá, tudo bem?"
}

• Então precione o botão em azul "Execute"
• Após o carregamento a resposta será gerada e mostrada um pouco mais abaixo, você verá algo do tipo:

Response body
{
  "response": "Tudo bem! Estou aqui para ajudar. Como posso ajudar você hoje?\n"
}

---

3. Caso deseje, é possível testar diretamente via terminal, basta abrir um novo terminal (além dos 2 necessários para rodar a API) e digitar o seguinte comando:

# Basta trocar o campo SUA MENSAGEM AQUI pela mensagem desejada:
curl -X POST http://localhost:8000/chat -H "Content-Type: application/json" -d "{\"message\": \"SUA MENSAGEM AQUI\"}"

OBS.: É possível verificar através do terminal que está rodando a "main.py" todas as respostas das requisições realizadas em tempo real, indepenedente do local e método que utilizou para realiza-las (webUI, fastAPI docs ou terminal).

Documentação

Links para as documentações:

Recurso	Documentação
Strands Agents	Documentação Oficial
FastAPI	FastAPI Docs
Ollama	Ollama Docs
Llama 3.1	Model Card
Uvicorn	Uvicorn Docs

Estrutura do projeto:

ChatAgentAPI/
├── 📁 src/
│   ├── main.py               # Aplicação FastAPI principal
│   ├── agent.py              # Agente de IA
│   ├── 📁 tools/
│   │    └── mathTool.py      # Tool especializada em cálculos
│   └── 📁 webUI/
│        ├── index.html       # Página HTML da interface web
│        ├── 📁 css/
│        │    └── styles.css  # Estilo css
│        └── 📁 js/
│             └── app.js      # JavaScript da interface web
├── requirements.txt          # Dependências do projeto
├── .env                      # Arquivo que deve ser criado, onde ficaram as variáveis de ambiente
├── .gitignore
└── README.md

Licença

Este projeto é open-source e está disponível sob a licença MIT.