Forem: Israel Junior

Construindo um Agentic usando o google ADK

Israel Junior — Mon, 22 Sep 2025 19:51:41 +0000

Resumo

Este artigo apresenta um agente construído com o Google ADK (Agent Development Kit) que consulta cotações de ações via YFinance. O agente expõe a ferramenta fetch_stock_info para responder perguntas sobre preço atual, mínima/máxima do dia e recomendação, usando o modelo Gemini. Abaixo estão a arquitetura, o passo a passo de configuração e execução, além de ideias de evolução.

Por que este projeto

Acessar cotações de forma conversacional com contexto.
Integrar modelos Gemini a uma fonte de dados prática (Yahoo Finance via YFinance).
Demonstrar como publicar ferramentas Python em um agente com o Google ADK.

Arquitetura

Agente: query_yfinance_agent (modelo gemini-2.0-flash), definido em query-yfinance/agent.py.
Ferramenta: fetch_stock_info(ticker_symbol: str), que usa yfinance para buscar:
- displayName (ou shortName)
- currentPrice
- dayLow
- dayHigh
- recommendationKey
Orquestração: Google ADK aciona o modelo e decide quando chamar a ferramenta com base no prompt do usuário.
Configuração: variáveis em query-yfinance/.env (carregadas automaticamente pelo ADK).

Código-chave

Arquivo query-yfinance/agent.py:

Ferramenta de consulta:
- Recebe ticker_symbol (ex.: PETR4.SA, AAPL).
- Usa yfinance.Ticker(...).info e retorna um dicionário com campos úteis.
Agente ADK:
- Define name, model, description e instruction.
- Registra a ferramenta em tools=[fetch_stock_info].

Pré-requisitos

Python >= 3.12.
Chave de API do Google Generative AI (para a API pública): variável GOOGLE_API_KEY.
Opcional: Vertex AI (com GOOGLE_GENAI_USE_VERTEXAI=TRUE + credenciais GCP).

Instalação

Com uv (recomendado):

Instale o uv: https://docs.astral.sh/uv/
No diretório do projeto, rode uv sync.
Ative o ambiente: source .venv/bin/activate.

Com pip:

Crie e ative o venv: python3.12 -m venv .venv && source .venv/bin/activate
Atualize o pip: pip install -U pip
Instale o projeto: pip install -e .

As dependências principais estão em pyproject.toml: google-adk e yfinance.

Configuração

Copie o exemplo de variáveis: cp query-yfinance/.env-sample query-yfinance/.env
Edite query-yfinance/.env:
- GOOGLE_API_KEY=... (quando não usa Vertex)
- GOOGLE_GENAI_USE_VERTEXAI=FALSE (ou TRUE + gcloud auth application-default login + exporte GOOGLE_CLOUD_PROJECT e GOOGLE_CLOUD_REGION)

Observação: o ADK lê o .env da pasta do agente; mantenha-o em query-yfinance/.

Execução (CLI)

Ative o venv.
Rode adk run query-yfinance.
Exemplos de perguntas:
- “Qual o preço atual de PETR4.SA?”
- “Mostre a mínima e a máxima do dia para AAPL.”

Exemplos de tickers:

Brasil (B3): PETR4.SA, VALE3.SA (note o sufixo .SA).
EUA: AAPL, GOOGL, MSFT.

Fluxo em tempo de execução

Você conversa com o agente no terminal.
O modelo Gemini interpreta a intenção e decide chamar fetch_stock_info com o ticker.
A ferramenta usa YFinance e retorna os campos.
O agente compõe uma resposta natural com os dados retornados.

Tratamento de erros e limitações

Ticker inválido: YFinance pode retornar dados incompletos; o agente ainda responde com o nome/ticker fornecido.
Campos ausentes: nem todos os ativos possuem currentPrice/recommendationKey; o código já lida com dict vazio.
Rede/limites: YFinance depende do Yahoo Finance e pode falhar temporariamente; tente novamente.
Precisão e atraso: dados são de terceiros e podem ter latência; valide antes de decisões financeiras.

Estrutura do repositório

query-yfinance/agent.py: agente e ferramenta fetch_stock_info.
query-yfinance/.env-sample: exemplo de variáveis.
README.md: guia rápido.
pyproject.toml: metadados e dependências.

Conclusão

Com poucas linhas de código e o Google ADK, integramos um modelo Gemini a uma fonte de dados financeira prática (YFinance), criando um agente conversacional que responde consultas de mercado. A abordagem é extensível: novas ferramentas podem ser adicionadas para enriquecer análises, histórico e formatação de relatórios.

Source

Sample Code google adk yfinance

BaseModel vs DataClass no Python

Israel Junior — Mon, 22 Sep 2025 13:37:03 +0000

Em Python, tanto pydantic.BaseModel quanto dataclasses.dataclass são usados para definir estruturas de dados com atributos tipados, mas eles têm propósitos e características distintas. A seguir, explico as vantagens de usar pydantic.BaseModel em vez de dataclasses.dataclass na declaração da sua classe Request:

Vantagens de usar `pydantic.BaseModel`:

Validação automática de dados:
- O BaseModel do Pydantic realiza validação automática dos dados com base nos tipos definidos (por exemplo, str para text). Se você passar um valor inválido (como um inteiro para um campo str), o Pydantic lançará uma exceção (ValidationError) com detalhes claros.
- Exemplo:
```
 from pydantic import BaseModel

 class Request(BaseModel):
     text: str

 # Válido
 req = Request(text="Olá")
 print(req)  # Request(text='Olá')

 # Inválido
 req = Request(text=123)  # Levanta ValidationError
```

Com dataclass, não há validação automática. Você pode atribuir qualquer tipo de dado a um atributo, mesmo que ele não corresponda à anotação de tipo, a menos que implemente validações manualmente.

Conversão automática de tipos:
- O Pydantic tenta converter automaticamente valores para o tipo esperado, quando possível. Por exemplo, se text espera uma str, mas você passa um número como "123", o Pydantic pode convertê-lo para string.
- Exemplo:
```
 req = Request(text=123)  # Converte 123 para "123" automaticamente
```

Em dataclass, não há conversão automática; você precisa implementar isso manualmente.

Suporte a tipos complexos e personalizados:

O Pydantic suporta tipos complexos como List, Dict, Optional, Union, e até mesmo outros modelos aninhados, com validação automática para todos os níveis.
Exemplo:

 from pydantic import BaseModel
 from typing import List

 class Item(BaseModel):
     name: str

 class Request(BaseModel):
     text: str
     items: List[Item]

 req = Request(text="teste", items=[{"name": "item1"}, {"name": "item2"}])

Com dataclass, você teria que implementar validações manuais para garantir que os dados aninhados sejam corretos.

Serialização e desserialização:
- O Pydantic facilita a conversão de objetos para formatos como JSON e dicionários (usando model_dump() ou model_dump_json()) e também a desserialização de JSON/dicionários para objetos.
- Exemplo:
```
 req = Request(text="teste")
 print(req.model_dump())  # {'text': 'teste'}
 print(req.model_dump_json())  # '{"text":"teste"}'
```

Com dataclass, você precisa usar bibliotecas adicionais (como dataclasses.asdict) ou implementar métodos manuais para serialização/desserialização.

Integração com APIs e frameworks web:
- O Pydantic é amplamente usado em frameworks como FastAPI porque ele se integra perfeitamente com validação de entrada/saída de APIs, parsing de JSON e geração automática de esquemas OpenAPI.
- Exemplo com FastAPI:
```
 from fastapi import FastAPI
 from pydantic import BaseModel

 app = FastAPI()

 class Request(BaseModel):
     text: str

 @app.post("/request")
 async def create_request(req: Request):
     return req
```

Com dataclass, você precisaria de lógica adicional para validar e parsear os dados de entrada.

Configuração flexível e personalização:

O Pydantic permite configurações avançadas, como validações personalizadas usando decoradores (@field_validator) ou configurações globais via ConfigDict.
Exemplo:

 from pydantic import BaseModel, field_validator

 class Request(BaseModel):
     text: str

     @field_validator("text")
     def text_must_not_be_empty(cls, v):
         if not v.strip():
             raise ValueError("Text cannot be empty")
         return v

Em dataclass, você precisa implementar validações manualmente, geralmente no método __post_init__, o que pode ser menos elegante.

Suporte a esquemas JSON:
- O Pydantic gera automaticamente esquemas JSON (JSON Schema) para seus modelos, o que é útil para documentação e validação de APIs.
- Exemplo:
```
 print(Request.model_json_schema())
```

Com dataclass, você precisaria de bibliotecas adicionais ou implementações manuais para gerar esquemas JSON.

Tratamento de dados opcionais e padrão:

O Pydantic lida bem com valores opcionais, valores padrão e campos obrigatórios, com validação automática.
Exemplo:

 from pydantic import BaseModel
 from typing import Optional

 class Request(BaseModel):
     text: str
     optional_field: Optional[str] = None

Em dataclass, você pode definir valores padrão, mas não há validação automática para garantir conformidade com tipos opcionais.

Quando usar `dataclass` em vez de `BaseModel`?

Casos simples sem validação: Se você precisa apenas de uma estrutura de dados leve, sem validação ou serialização automática, dataclass é mais simples e tem menos sobrecarga.
Performance: dataclass é geralmente mais leve em termos de desempenho, pois não realiza validações automáticas.
Projetos sem dependências externas: dataclass é parte da biblioteca padrão do Python (a partir do Python 3.7), enquanto o Pydantic é uma dependência externa.

Conclusão

A principal vantagem de usar pydantic.BaseModel em vez de dataclasses.dataclass na sua classe Request é a validação automática, conversão de tipos, serialização/desserialização e integração com APIs. Se você está lidando com entrada de dados (como em APIs REST, parsing de JSON ou formulários), o Pydantic é uma escolha superior porque reduz a necessidade de código boilerplate para validação e parsing. No entanto, se você precisa apenas de uma estrutura de dados simples e não quer dependências externas, dataclass pode ser suficiente.

Forem: Israel Junior

Construindo um Agentic usando o google ADK

Resumo

Por que este projeto

Arquitetura

Código-chave

Pré-requisitos

Instalação

Configuração

Execução (CLI)

Fluxo em tempo de execução

Tratamento de erros e limitações

Estrutura do repositório

Conclusão

Source

BaseModel vs DataClass no Python

Vantagens de usar pydantic.BaseModel:

Quando usar dataclass em vez de BaseModel?

Conclusão

Vantagens de usar `pydantic.BaseModel`:

Quando usar `dataclass` em vez de `BaseModel`?