biatoolkit 2.3.1

Biblioteca para desenvolvedores que utilizam o BiaAgentBuilder

Bia Toolkit (biatoolkit)

Toolkit Python para facilitar o desenvolvimento e teste de MCP Servers (Model Context Protocol) integrados ao Bia Agent Builder (AWS Bedrock AgentCore).

Este repositório entrega dois grandes blocos:

1. SDK para MCP

• BiaClient: cliente para chamar um MCP Server (ListTools / CallTool)
• BiaUtil: utilitário para MCP Server ler headers do runtime e parâmetros/segredos

2. DevTools (biatoolkit.devtools)

• cli_validate: validação estática do bundle (estrutura, Dockerfile, entrypoint etc.)
• cli_smoke: validação runtime (docker build/run + ListTools MCP)

---

Sumário

• Instalação
• Conceitos rápidos
• BiaClient (consumir um MCP Server)
• BiaUtil (usar dentro do MCP Server)
• Headers do Runtime (AgentCore)
• Parâmetros e Segredos (env e SSM)
• Integração Sankhya ERP
  • load_view (recomendado)
  • load_records (recomendado)
  • REST v1 por path (recomendado)
  • Sankhya.Call (compatibilidade / uso genérico)
  • Configurações via env
• Integração Sankhya Fintech
  • SankhyaFintech.call (instância)
  • SankhyaFintech.Call (estático)
  • ToolkitResponse
  • Configurações via env (Fintech)
• Integração Queue Dispatch (busca de produtos)
  • QueueDispatch.search (caminho padrão)
  • QueueDispatch.dispatch + get_result (uso avançado)
  • QueueDispatch.Call (estático)
  • ToolkitResponse retornado
  • Configurações via env (Queue Dispatch)
• Configurações do Toolkit (env)
• DevTools CLI
  • Validação estática: cli_validate
  • Runtime smoke: cli_smoke
• Troubleshooting
• Licença

---

Instalação

pip install mcp biatoolkit

---

Conceitos rápidos

O que é um MCP Server?

Um servidor MCP expõe tools (funções) que podem ser listadas e executadas via protocolo MCP.

Onde roda?

• Local: FastMCP + transport="streamable-http"
• Produção: Bia Agent Builder (AWS Bedrock AgentCore)

---

BiaClient (consumir um MCP Server)

O BiaClient é um cliente assíncrono que abstrai:

• conexão streamable-http
• criação/initialize de sessão MCP
• chamadas list_tools() e call_tool()

Criando um cliente e listando tools

import asyncio
from biatoolkit.basic_client import BiaClient

async def main():
    client = BiaClient("http://127.0.0.1:8000/mcp")
    tools = await client.list_tools()

    # o retorno é o objeto retornado pelo mcp.ClientSession (list_tools)
    # normalmente contém tools com name/description/schema dependendo do server
    for t in tools.tools:
        print(t.name, "-", t.description)

asyncio.run(main())

Executando uma tool (CallTool)

import asyncio
from biatoolkit.basic_client import BiaClient

async def main():
    client = BiaClient("http://127.0.0.1:8000/mcp")
    result = await client.call_tool("minha_tool", {"x": 1})

    # o shape do result depende do MCP server
    print(result)

asyncio.run(main())

Passando headers (simular runtime do AgentCore)

from biatoolkit.basic_client import BiaClient

headers = {
  "X-Amzn-Bedrock-AgentCore-Runtime-Custom-current-host": "https://meu.erp.sankhya.com.br",
  "X-Amzn-Bedrock-AgentCore-Runtime-Custom-user-email": "[e-mail]",
  "X-Amzn-Bedrock-AgentCore-Runtime-Custom-jsessionid": "JSESSIONID-ABC",
  "X-Amzn-Bedrock-AgentCore-Runtime-Custom-organization-id": "123",
  "Content-Type": "application/json",
}

client = BiaClient("http://127.0.0.1:8000/mcp", headers=headers)

Em produção, o runtime AgentCore controla quais headers são repassados.

---

BiaUtil (usar dentro do MCP Server)

O BiaUtil é usado dentro do MCP Server para:

• ler headers do runtime do AgentCore
• recuperar parâmetros/segredos de forma segura (env -> SSM fallback)

Exemplo (ler header)

from mcp.server.fastmcp import FastMCP
from biatoolkit.util import BiaUtil

mcp = FastMCP(host="0.0.0.0", stateless_http=True)

@mcp.tool()
def whoami() -> str:
    util = BiaUtil(mcp)
    h = util.get_header()
    return f"user_email={h.user_email} org={h.organization_id} host={h.current_host}"

if __name__ == "__main__":
    mcp.run(transport="streamable-http")

---

Headers do Runtime (AgentCore)

O BiaUtil.get_header() retorna um objeto Header com os campos:

Campo	Tipo	Origem
current_host	str|None	header ...-current-host
user_email	str|None	header ...-user-email
jwt_token	str|None	header ...-jwt-token
jsessionid	str|None	header ...-jsessionid
organization_id	int	header ...-organization-id (fallback 0)
codparc	int	header ...-codparc (fallback 0)
iam_user_id	int	header ...-iam-user-id (fallback 0)
gateway_token	str|None	header ...-gateway-token

Header prefix

O toolkit trabalha com um prefixo base (default):

• x-amzn-bedrock-agentcore-runtime-custom

Exemplo de header efetivo (case-insensitive em HTTP):

• X-Amzn-Bedrock-AgentCore-Runtime-Custom-user-email

---

Parâmetros e Segredos (env e SSM)

O BiaUtil.get_parameter("NOME") resolve na ordem:

1. Variável de ambiente
2. AWS SSM Parameter Store (fallback)

Como o SSM é resolvido

Para buscar no SSM, o toolkit usa um prefixo vindo do header:

• {HEADER_PREFIX}-prefix

Exemplo (nome efetivo do header):

• X-Amzn-Bedrock-AgentCore-Runtime-Custom-prefix: /bia/agentbuilder/segredos

Então o toolkit busca no SSM:

• Name = "{prefix}/{parameter_name}" com WithDecryption=True

Se o header ...-prefix não existir, o toolkit não consulta SSM e retorna None.

---

Integração Sankhya ERP

A integração Sankhya ERP vive em biatoolkit.sankhya.erp e tem como foco:

• permitir chamadas legadas (/mge/service.sbr) e REST (/api/v1/..., /v1/...)
• usar JSESSIONID do header do runtime (quando disponível) ou valor explícito
• suportar retries/timeouts via variáveis de ambiente

Origem da URL final:

• base_url: vem de base_url explícito ou de current_host no header do runtime.
• endpoint/path: vem de quem chama (service_path ou url).
• o toolkit monta a URL final, querystring e autenticação.

load_view (recomendado)

load_view é um helper para:

• CRUDServiceProvider.loadView

Ele monta o payload e querystring automaticamente.

from mcp.server.fastmcp import FastMCP
from biatoolkit.sankhya.erp import Sankhya

mcp = FastMCP(host="0.0.0.0", stateless_http=True)

@mcp.tool()
def recomendacoes() -> dict:
    sk = Sankhya(mcp=mcp)

    # base_url pode ser omitido se o header current_host existir no runtime
    return sk.load_view(
        view_name="BIA_VW_MB_RULES",
        where_sql="CODPROD_A = 123",
        fields="*",
    )

Parâmetros principais:

• view_name (obrigatório)
• where_sql (obrigatório)
• fields (opcional, default "*")
• jsessionid (opcional; se None tenta extrair do header do runtime)
• base_url (opcional; se None tenta usar current_host do header)
• url (opcional override total)
• extra_headers (opcional)

load_records (recomendado)

load_records é um helper para:

• DatasetSP.loadRecords

Permite consultar registros de uma entidade Sankhya (Parceiro, Produto, Cidade, etc.) com filtro via expression e binds tipados, sem precisar montar manualmente o requestBody.

from mcp.server.fastmcp import FastMCP
from biatoolkit.sankhya.erp import Sankhya

mcp = FastMCP(host="0.0.0.0", stateless_http=True)

@mcp.tool()
def listar_parceiros_ativos() -> dict:
    sk = Sankhya(mcp=mcp)

    out = sk.load_records(
        entity_name="Parceiro",
        fields=["CODPARC", "NOMEPARC", "RAZAOSOCIAL", "ATIVO"],
        where="this.ATIVO = 'S' AND this.CODPARC > 0",
        application="Parceiro",
        resource_id="br.com.sankhya.Parceiro",
        crud_listener="br.com.sankhya.modelcore.crudlisteners.ParceiroCrudListener",
    )

    if not out.success:
        return {"erro": out.error}

    # com as_dicts=True (default), cada linha vem como dict {field: value}
    return {"parceiros": out.data["responseBody"]["result"]}

Parâmetros principais:

• entity_name (obrigatório) — nome da entidade Sankhya (ex: "Parceiro").
• fields (default "*") — lista de campos (list[str]) ou string.
• where (default "") — cláusula SQL para criteria.expression.
• parameters (default []) — binds dos critérios de filtro (ex: [{"type":"S","value":"X"}]).
• crud_listener (opcional) — classe específica da entidade/tela. Quando omitido, o Sankhya pode exigir conforme a entidade.
• application / resource_id (opcionais) — query params para carregar personalizações/permissões da tela.
• data_set_id (default "00V") — pode ser fixo ou aleatório.
• client_event_list (default []) — eventos client-side (UI). Em MCP/headless normalmente fica vazio.
• as_dicts (default True) — transforma responseBody.result de lista de listas em lista de dicts, fazendo zip com fields. Facilita filtros e acesso por nome. Use False para receber o JSON cru do Sankhya.
• jsessionid / base_url / url / extra_headers (opcionais).

Formato do retorno (com as_dicts=True):

{
  "responseBody": {
    "total": "150",
    "result": [
      {"CODPARC": "3", "NOMEPARC": "...", "RAZAOSOCIAL": "...", "ATIVO": "S"},
      {"CODPARC": "10", "NOMEPARC": "...", "RAZAOSOCIAL": "...", "ATIVO": "S"}
    ]
  }
}

REST v1 por path (recomendado)

Para REST v1, o consumidor deve informar apenas o path do serviço.

from biatoolkit.sankhya.erp import Sankhya

out = Sankhya.Call(
  mcp=mcp,
  method="GET",
  service_path="/api/v1/financeiros/receitas",
  query="pagina=1&tamanho=20",
  # base_url pode ser omitido: toolkit resolve via header.current_host
)

Comportamento padrão para REST v1:

• se outputType não estiver na query, o toolkit inclui outputType=json.
• sessão padrão: mgeSession truncado na query + Cookie: JSESSIONID=<completo>.
• se base_url não for passado, tenta resolver via current_host do runtime.

Sankhya.Call (compatibilidade / uso genérico)

Existe um método estático Sankhya.Call(...) para compatibilidade com scaffolds legados e uso genérico.

from biatoolkit.sankhya.erp import Sankhya

out = Sankhya.Call(
  method="GET",
  service_path="/api/v1/financeiros/receitas",
  query="pagina=1&tamanho=20",
)

Parâmetros principais:

• jsessionID (opcional; se None tenta extrair do header do runtime quando mcp for informado)
• payload (opcional; body da requisição em dict)
• mcp (opcional; usado para resolver dados do runtime, como jsessionID)
• url (opcional; URL completa ou relativa)
• service_path (opcional; path do serviço, ex: /api/v1/financeiros/receitas)
• base_url (opcional; base da URL quando url não for informado)
• query (opcional; querystring, ex: serviceName=...&outputType=json)
• method (opcional, default "POST"; aceita "POST" ou "GET")
• extra_headers (opcional; headers adicionais)
• include_output_type_json (opcional; força inclusão de outputType=json)

Se estiver rodando dentro de MCP Server, você pode omitir jsessionID e passar mcp=... para extrair do header.

---

Configurações via env (Sankhya ERP)

O toolkit lê as seguintes variáveis (com defaults no código):

Variável	Default	Descrição
SANKHYA_TIMEOUT_CONNECT	3.05	timeout de conexão
SANKHYA_TIMEOUT_READ	12.0	timeout de leitura
SANKHYA_RETRIES_TOTAL	3	tentativas em falha
SANKHYA_RETRY_BACKOFF	0.5	backoff entre tentativas
SANKHYA_VERIFY_SSL	1	valida SSL (1/true/yes/on)

---

Integração Sankhya Fintech

O SankhyaFintech (em biatoolkit.sankhya.fintech) é o cliente do gateway financeiro da Sankhya — Pix, Pagamentos e Boleto. O handshake de autenticação de 3 passos é executado automaticamente antes de cada chamada; o MCP Tool não precisa gerenciar tokens.

Resolução da base_url (ordem de prioridade):

Prioridade	Fonte
1	Parâmetro base_url no construtor ou em Call()
2	Env var SANKHYA_FINTECH_BASE_URL
3	SSM {BIATOOLKIT_SSM_PREFIX}/SANKHYA_FINTECH_BASE_URL
4	Fallback: http://fintechapi-dev.sankhya.com.br

Em produção (AgentCore), configure o parâmetro SSM e nenhum código precisa ser alterado. Para testes locais, passe base_url diretamente no construtor.

SankhyaFintech.call (instância)

Uso recomendado dentro de um MCP Server, quando o codparc vem do header do runtime:

from mcp.server.fastmcp import FastMCP
from biatoolkit.sankhya.fintech import SankhyaFintech

mcp = FastMCP(host="0.0.0.0", stateless_http=True)

@mcp.tool()
def criar_cobranca_pix(valor: float) -> dict:
    """Cria uma cobrança Pix para o parceiro autenticado"""
    fintech = SankhyaFintech(mcp)  # base_url resolvida via SSM em produção
    resp = fintech.call(
        service_path="/api/v1/pix/cobrancas",
        nome="ACME COMERCIO LTDA",   # NOMEPARC do parceiro
        payload={"valor": valor},
    )
    return resp.data if resp.success else {"erro": resp.error}

if __name__ == "__main__":
    mcp.run(transport="streamable-http")

Uso com base_url explícito (testes locais ou ambientes sem SSM):

fintech = SankhyaFintech(mcp, base_url="http://fintechapi-prd.sankhya.com.br")

Exemplo com pagamento (BOLETO), passando headers obrigatórios da API:

import uuid

resp = fintech.call(
    service_path="/api/v1/payments",
    nome="ACME COMERCIO LTDA",
    method="POST",
    payload={
        "items": [{
            "accountId": "conta-001",
            "value": 150.00,
            "paymentDate": "2026-06-01",
            "paymentCode": "34191790010104351004791020150008682430000015000",
            "type": "BOLETO",
            "externalId": "PAG-001",
            "beneficiaryName": "Fornecedor XYZ",
            "beneficiaryDocument": "00000000000190",
        }]
    },
    extra_headers={
        "Idempotency-Key": str(uuid.uuid4()),
        "X-External-User-Id": "647",
        "X-External-User-Name": "ACME COMERCIO LTDA",
    },
    raise_for_http_error=False,   # retorna ToolkitResponse mesmo em erro
)

SankhyaFintech.Call (estático)

Atalho para chamadas avulsas sem precisar instanciar:

from biatoolkit.sankhya.fintech import SankhyaFintech

resp = SankhyaFintech.Call(
    service_path="/api/v1/pix/cobrancas",
    nome="ACME COMERCIO LTDA",
    codparc=647,
    base_url="http://fintechapi-prd.sankhya.com.br",  # opcional
    payload={"valor": 100.0},
)

Parâmetros do construtor SankhyaFintech()

Parâmetro	Obrigatório	Descrição
mcp	❌	Instância FastMCP (necessária para resolver codparc do header do runtime)
base_url	❌	URL base do gateway. Se omitido, resolve via env → SSM → default DEV
toolkit_settings	❌	Configurações do toolkit (region, SSM prefix etc.)
fintech_settings	❌	Configurações completas do Fintech. Se passado, base_url é ignorado
default_headers	❌	Headers aplicados em todas as requisições

Parâmetros do call() / Call()

Parâmetro	Obrigatório	Descrição
service_path	✅	Path da API fintech, ex: /api/v1/pix/cobrancas
nome	✅	NOMEPARC do parceiro (obrigatório para o credenciamento)
codparc	❌	CODPARC do Sankhya. Se omitido, lê do header do runtime
method	❌	Método HTTP (default POST)
payload	❌	Body JSON
query	❌	Querystring adicional, ex: pagina=1&tamanho=20
extra_headers	❌	Headers adicionais (ex: Idempotency-Key)
integrator_token	❌	Chave do integrador. Se omitido, resolve automaticamente: env var SANKHYA_FINTECH_INTEGRATOR_TOKEN → cache em memória (5 min) → SSM via BIATOOLKIT_SSM_PREFIX
raise_for_http_error	❌	Se True (padrão), lança FintechHTTPError em 4xx/5xx

ToolkitResponse

Todos os métodos retornam um ToolkitResponse:

resp = fintech.call(...)

resp.success      # bool — True se HTTP 2xx
resp.data         # dict — body da resposta em caso de sucesso
resp.error        # str  — mensagem de erro em caso de falha
resp.status_code  # int  — código HTTP retornado pela API
resp.request_id   # str  — x-request-id para correlação de logs

Configurações via env (Fintech)

Variável	Default	Descrição
SANKHYA_FINTECH_BASE_URL	http://fintechapi-dev.sankhya.com.br	URL base do gateway. Alternativa ao SSM para ambientes locais
SANKHYA_FINTECH_INTEGRATOR_TOKEN	—	Chave do integrador. Se definida, tem prioridade sobre o SSM
SANKHYA_FINTECH_TIMEOUT_CONNECT	3.05	timeout de conexão (s)
SANKHYA_FINTECH_TIMEOUT_READ	12.0	timeout de leitura (s)
SANKHYA_FINTECH_RETRIES_TOTAL	3	tentativas em falha
SANKHYA_FINTECH_RETRY_BACKOFF	0.5	backoff entre tentativas
SANKHYA_FINTECH_VERIFY_SSL	1	valida SSL (1/true/yes/on)

---

Integração Queue Dispatch (busca de produtos)

O QueueDispatch (em biatoolkit.google.queue_dispatch) é o cliente do Queue Dispatch API — busca e normalização de produtos via Google Shopping. Ele gerencia automaticamente a autenticação OAuth2 e o polling assíncrono. O MCP Tool só precisa informar a query.

Pré-requisito de deploy — armazenar no SSM como SecureString:

{BIATOOLKIT_SSM_PREFIX}/QUEUE_DISPATCH_CLIENT_ID
{BIATOOLKIT_SSM_PREFIX}/QUEUE_DISPATCH_CLIENT_SECRET

Localmente, definir as mesmas variáveis como env vars no .env. Nenhuma outra configuração é necessária em produção.

QueueDispatch.search (caminho padrão)

Fluxo completo em uma única chamada: OAuth2 → dispatch → polling → resultado.

from mcp.server.fastmcp import FastMCP
from biatoolkit.google.queue_dispatch import QueueDispatch

mcp = FastMCP(host="0.0.0.0", stateless_http=True)

@mcp.tool()
def buscar_produto(query: str, result_count: int = 5) -> dict:
    """Busca produto no Google Shopping e retorna preços e referências normalizadas"""
    qd = QueueDispatch(mcp)
    resp = qd.search(query=query, result_count=result_count)
    return resp.data if resp.success else {"erro": resp.error}

Com localização (contextualiza a busca por região):

resp = qd.search(
    query="iphone 17 pro",
    result_count=5,
    location="Uberlandia, MG",
)
if resp.success:
    print(resp.data["normalized_query"])       # "iPhone 17 Pro"
    print(resp.data["price_range"]["min"])     # 6000.0
    print(resp.data["price_range"]["max"])     # 11499.0
    for produto in resp.data["filtered_results"]:
        print(produto["title"], produto["price"], produto["source"])

QueueDispatch.dispatch + get_result (uso avançado)

Para casos onde você precisa disparar a busca e consultar o resultado em momentos diferentes (ex: duas tool calls separadas no agente):

qd = QueueDispatch(mcp)

# Tool call 1 — dispara
dispatch_resp = qd.dispatch(query="buxa 10mm", result_count=20)
request_id = dispatch_resp.data["request_id"]
# Salva request_id para usar na próxima chamada

# Tool call 2 — consulta (com polling automático)
result_resp = qd.get_result(request_id, poll=True, max_wait=20.0)
if result_resp.success:
    print(result_resp.data["filtered_results"])

# Consulta sem polling (retorna o estado atual, QUEUED ou FOUND)
result_resp = qd.get_result(request_id, poll=False)

# Consulta com envelope completo (não só o final_output_payload)
result_resp = qd.get_result(request_id, poll=True, raw=True)

QueueDispatch.Call (estático)

Atalho para chamadas avulsas sem instanciar:

from biatoolkit.google.queue_dispatch import QueueDispatch

resp = QueueDispatch.Call(query="iphone 17 pro", result_count=5)

ToolkitResponse retornado

search() e get_result() retornam ToolkitResponse. Com raw=False (padrão):

resp.success                            # bool  — True se resultado encontrado
resp.data["normalized_query"]           # str   — query normalizada pela API
resp.data["price_range"]["min"]         # float — menor preço encontrado
resp.data["price_range"]["max"]         # float — maior preço encontrado
resp.data["filtered_results"]           # list  — produtos com title, price, source, confidence
resp.data["confidence"]                 # str   — "high" | "medium" | "low"
resp.error                              # str   — mensagem de erro (quando falha)
resp.status_code                        # int   — 200 (ok) | 408 (timeout polling) | 4xx/5xx
resp.request_id                         # str   — x-request-id para correlação de logs

Cada item em filtered_results:

{
    "position": 1,
    "title": "Apple iPhone 17 Pro",
    "price": 11499.0,
    "source": "Apple",
    "product_link": "https://...",
    "rating": 4.5,
    "reviews": 16000,
    "confidence": "high",        # high = produto exato | medium = produto relacionado
    "comments": [],              # observações da API sobre relevância
}

Comportamentos automáticos:

• Polling: backoff de 2s, 2s, 3s, 3s... até o resultado aparecer ou max_wait ser atingido (default 20s). Retorna status_code=408 ao estourar — o request_id fica no error para retomada manual.
• Renovação de token: em 401, o token é renovado automaticamente e a chamada é retentada uma vez.
• Cache de token: o access_token OAuth2 é cacheado em memória por expires_in - 60s (~59 min). Chamadas subsequentes não pagam overhead de auth.

Configurações via env (Queue Dispatch)

Todas são opcionais — os defaults cobrem produção. Só os secrets precisam ser provisionados no SSM.

Variável	Default	Descrição
QUEUE_DISPATCH_CLIENT_ID	—	OAuth2 client_id. Em prod, usa SSM SecureString
QUEUE_DISPATCH_CLIENT_SECRET	—	OAuth2 client_secret. Em prod, usa SSM SecureString
QUEUE_DISPATCH_POLL_INITIAL	2.0	Delay inicial do polling (s)
QUEUE_DISPATCH_POLL_MAX	3.0	Delay máximo do polling (s)
QUEUE_DISPATCH_POLL_MAX_WAIT	20.0	Timeout total do polling (s)
QUEUE_DISPATCH_TIMEOUT_CONNECT	3.05	Timeout de conexão (s)
QUEUE_DISPATCH_TIMEOUT_READ	15.0	Timeout de leitura (s)
QUEUE_DISPATCH_RETRIES_TOTAL	3	Tentativas em falha transitória (429/5xx)
QUEUE_DISPATCH_RETRY_BACKOFF	0.5	Backoff entre tentativas (s)
QUEUE_DISPATCH_VERIFY_SSL	1	Valida SSL (1/true/yes/on)

---

Configurações do Toolkit (env)

O toolkit expõe BiaToolkitSettings.from_env() com:

Variável	Default	Descrição
BIATOOLKIT_HEADER_PREFIX	x-amzn-bedrock-agentcore-runtime-custom	prefixo base de headers
BIATOOLKIT_AWS_REGION	sa-east-1	região para AWS SSM
BIATOOLKIT_CLIENT_TIMEOUT_SECONDS	120	timeout do cliente MCP
BIATOOLKIT_SSM_PREFIX	—	Prefixo do path no SSM (ex: /biatoolkit). Necessário para que SankhyaFintech resolva o integrator token automaticamente via boto3 quando mcp não estiver disponível

---

DevTools CLI

Os DevTools validam bundles de MCP Server antes do deploy no AgentCore.

Eles ficam em:

• biatoolkit.devtools

Validação estática: cli_validate

Valida estrutura e consistência do bundle (fase 1).

python -m biatoolkit.devtools.cli_validate --path ./meu_bundle

Parâmetros:

Flag	Obrigatório	Descrição
--path	✅	pasta do bundle
--entry-file	❌	arquivo Python que inicia o server (ex: app.py)
--entry-module	❌	módulo para python -m (ex: sales_agent_murilo)
--require-entry	❌	exige informar --entry-file ou --entry-module
--allow-hyphen-module	❌	transforma nome inválido (com hífen) de ERROR para WARN
--verbose	❌	logs detalhados

Runtime smoke: cli_smoke

Executa validação runtime (fase 2):

• docker build
• docker run detached
• valida container vivo por X segundos
• healthcheck HTTP (opcional)
• MCP ListTools (opcional, mas recomendado)

python -m biatoolkit.devtools.cli_smoke \
  --path ./meu_bundle \
  --port 8000 \
  --mcp-path /mcp

Parâmetros:

Flag	Obrigatório	Descrição
--path	✅	pasta do bundle
--port	❌	porta mapeada host:container (default 8000)
--mcp-path	❌	path MCP (default /mcp)
--mcp-url	❌	URL completa do MCP (override; ignora --port/--mcp-path)
--skip-mcp-list-tools	❌	pula o ListTools (debug)
--health-path	❌	path HTTP para healthcheck (ex: /health)
--run-seconds	❌	tempo que o container deve ficar vivo (default 8)
--build-timeout-sec	❌	timeout do build (default 600)
--start-timeout-sec	❌	timeout do start (default 60)
--env KEY=VALUE	❌	injeta env no container (pode repetir)
--tag	❌	tag da imagem docker
--skip-static	❌	pula validação estática
--keep-image	❌	não remove imagem
--keep-container	❌	não remove container
--verbose	❌	logs de progresso
--show-logs	❌	tail de logs no sucesso

Próxima evolução planejada do cli_smoke: CallTool automático (Item 4).

---

Troubleshooting

1) Docker daemon indisponível

• Garanta que Docker está instalado e rodando.
• O smoke test detecta e reporta esse cenário.

2) Container sobe e morre rápido

• Verifique entrypoint no Dockerfile.
• Rode com --keep-container e --show-logs para diagnóstico.

3) MCP ListTools falha (406 / handshake)

• Use o BiaClient (já é o padrão do smoke).
• Confirme o endpoint e o path (--mcp-url / --mcp-path).

4) SSM não retorna segredo

• Confirme se o header ...-prefix existe no runtime.
• Confirme a região AWS (BIATOOLKIT_AWS_REGION).
• Confirme permissão IAM para ssm:GetParameter.

5) SankhyaFintech: ValueError — integrator token não encontrado

• O toolkit tenta resolver o integrator token na ordem: env var SANKHYA_FINTECH_INTEGRATOR_TOKEN → SSM direto via boto3.
• Para o SSM funcionar, defina BIATOOLKIT_SSM_PREFIX (ex: /biatoolkit) no container ou .env local.
• O parâmetro SSM esperado é {BIATOOLKIT_SSM_PREFIX}/SANKHYA_FINTECH_INTEGRATOR_TOKEN (SecureString).
• Confirme permissão IAM para ssm:GetParameter no parâmetro e região corretos (BIATOOLKIT_AWS_REGION, default sa-east-1).

---

Licença

Defina aqui o modelo de licença (ex: MIT / Apache-2.0 / Proprietária).