biatoolkit 1.0.3__py3-none-any.whl → 1.1.0__py3-none-any.whl

biatoolkit/__init__.py

@@ -0,0 +1,4 @@
+from .util import BiaUtil
+from .basic_client import BiaClient
+
+__all__ = ["BiaUtil", "BiaClient"]

biatoolkit/basic_client.py

@@ -1,63 +1,141 @@
+"""
+biatoolkit.basic_client
+
+Este módulo contém o BiaClient, um cliente HTTP assíncrono para comunicação
+com servidores MCP (Model Context Protocol).
+
+Responsabilidades:
+- Abrir e gerenciar conexões HTTP streamable com servidores MCP.
+- Inicializar sessões MCP.
+- Encapsular chamadas comuns (listar tools, executar tool).
+
+O objetivo é esconder os detalhes de sessão, streams e inicialização,
+expondo uma API simples para quem consome a biblioteca.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable, Optional, Dict
+
 from mcp import ClientSession
 from mcp.client.streamable_http import streamablehttp_client
 
+from .settings import BiaToolkitSettings
+
+
 class BiaClient:
     """
-    Cliente básico para interação com o MCP (Middleware de Comunicação de Processos).
-    Permite listar ferramentas disponíveis e executar ferramentas específicas via HTTP.
+    Cliente básico para interação com servidores MCP.
+
+    Esta classe encapsula toda a complexidade envolvida em:
+    - Abrir conexões HTTP streamable
+    - Criar e inicializar ClientSession
+    - Executar chamadas MCP
+
+    Exemplos de uso:
+        client = BiaClient("http://localhost:8000")
+        tools = await client.list_tools()
+        result = await client.call_tool("minha_tool", {"x": 1})
     """
 
-    def __init__(self, url: str = "http://0.0.0.0:8000/mcp", headers: dict = None):
+    def __init__(
+        self,
+        url: str = "http://0.0.0.0:8000/mcp",
+        headers: Optional[Dict[str, str]] = None,
+        settings: Optional[BiaToolkitSettings] = None,
+    ):
         """
-        Inicializa o BasicClient.
+        Inicializa o cliente MCP.
 
         Args:
-            url (str): URL base do MCP. Se não terminar com '/mcp', será adicionado automaticamente.
-            headers (dict): Cabeçalhos HTTP opcionais para requisições.
+            url:
+                URL base do servidor MCP.
+                - Se não terminar com '/mcp', o sufixo será adicionado automaticamente.
+            headers:
+                Headers HTTP opcionais enviados em todas as requisições.
+                Normalmente usados para enviar contexto (runtime, autenticação, etc.).
+            settings:
+                Configurações opcionais da biblioteca (timeout, etc.).
+                Se None, carrega defaults e overrides via variáveis de ambiente.
         """
-        sufix = "/mcp"
+        # Carrega configurações globais (timeout, etc.)
+        self.settings = settings or BiaToolkitSettings.from_env()
+
         # Garante que a URL termine com '/mcp'
-        self.url = url if url.endswith(sufix) else f"{url}{sufix}"
+        suffix = "/mcp"
+        self.url = url if url.endswith(suffix) else f"{url}{suffix}"
+
+        # Headers HTTP que serão enviados para o servidor MCP
         self.headers = headers
 
-    async def list_tools(self) -> dict:
+    async def _with_session(self, fn: Callable[[ClientSession], Awaitable[Any]]) -> Any:
         """
-        Lista as ferramentas disponíveis no MCP.
+        Executa uma função dentro de uma sessão MCP já inicializada.
+
+        Este método centraliza todo o boilerplate necessário para:
+        - Abrir a conexão HTTP streamable
+        - Criar a ClientSession
+        - Chamar session.initialize()
+        - Garantir fechamento correto dos recursos
+
+        Ele recebe uma função (callback) que recebe a ClientSession e
+        executa a lógica específica (listar tools, chamar tool, etc.).
+
+        Args:
+            fn: Função assíncrona que recebe uma ClientSession.
 
         Returns:
-            dict: Dicionário contendo as ferramentas disponíveis.
-        """
-        # Cria um cliente HTTP streamable para comunicação assíncrona
-        async with streamablehttp_client(self.url, self.headers, timeout=120, terminate_on_close=False) as (
-            read_stream,
-            write_stream,
-            _,
-        ):
-            # Cria uma sessão de cliente MCP usando os streams
+            O valor retornado pela função fn.
+        """
+        async with streamablehttp_client(
+            self.url,
+            self.headers,
+            # Timeout configurável via settings
+            timeout=self.settings.client_timeout_seconds,
+            # Mantém o servidor ativo mesmo após fechar streams
+            terminate_on_close=False,
+        ) as (read_stream, write_stream, _):
+
+            # Cria a sessão MCP usando os streams
             async with ClientSession(read_stream, write_stream) as session:
-                await session.initialize()  # Inicializa a sessão
-                tool_result = await session.list_tools()  # Solicita a lista de ferramentas
-        return tool_result
-    
+                # Inicialização obrigatória do protocolo MCP
+                await session.initialize()
+
+                # Executa a lógica específica passada pelo caller
+                return await fn(session)
+
+    async def list_tools(self) -> dict:
+        """
+        Lista todas as ferramentas (tools) disponíveis no servidor MCP.
+
+        Returns:
+            dict: Estrutura contendo as tools expostas pelo servidor.
+        """
+
+        async def _call(session: ClientSession) -> Any:
+            return await session.list_tools()
+
+        return await self._with_session(_call)
+
     async def call_tool(self, tool_name: str, params: dict = None) -> dict:
         """
-        Executa uma ferramenta específica disponível no MCP.
+        Executa uma ferramenta específica disponível no servidor MCP.
 
         Args:
-            tool_name (str): Nome da ferramenta a ser executada.
-            params (dict, opcional): Parâmetros para a execução da ferramenta.
+            tool_name:
+                Nome da tool a ser executada (exatamente como exposta pelo servidor).
+            params:
+                Parâmetros da tool, enviados como dicionário.
+                Pode ser None se a tool não exigir parâmetros.
 
         Returns:
-            dict: Resultado da execução da ferramenta.
-        """
-        # Cria um cliente HTTP streamable para comunicação assíncrona
-        async with streamablehttp_client(self.url, self.headers, timeout=120, terminate_on_close=False) as (
-            read_stream,
-            write_stream,
-            _,
-        ):
-            # Cria uma sessão de cliente MCP usando os streams
-            async with ClientSession(read_stream, write_stream) as session:
-                await session.initialize()  # Inicializa a sessão
-                result = await session.call_tool(tool_name, params)  # Executa a ferramenta
-        return result
+            dict: Resultado da execução da tool.
+        """
+
+        async def _call(session: ClientSession) -> Any:
+            return await session.call_tool(tool_name, params)
+
+        return await self._with_session(_call)
+
+
+__all__ = ["BiaClient"]

biatoolkit/schema/__init__.py

@@ -0,0 +1 @@
+# biatoolkit/schema/__init__.py

biatoolkit/settings.py

@@ -0,0 +1,106 @@
+"""
+biatoolkit.settings
+
+Este módulo centraliza todas as configurações globais da Bia Toolkit.
+
+Objetivos:
+- Evitar valores hardcoded espalhados pelo código.
+- Permitir override simples via variáveis de ambiente.
+- Facilitar testes, manutenção e futuras extensões.
+
+Exemplos de override via environment:
+    BIATOOLKIT_HEADER_PREFIX=x-amzn-bedrock-agentcore-runtime-custom
+    BIATOOLKIT_AWS_REGION=us-east-1
+    BIATOOLKIT_CLIENT_TIMEOUT_SECONDS=60
+"""
+
+from dataclasses import dataclass
+import os
+
+
+@dataclass(frozen=True)
+class BiaToolkitSettings:
+    """
+    Objeto imutável (frozen) que representa as configurações da biblioteca.
+
+    Por que usar dataclass + frozen?
+    - Facilita leitura e manutenção.
+    - Garante que as configurações não sejam alteradas em runtime,
+      evitando efeitos colaterais difíceis de rastrear.
+    """
+
+    # ------------------------------------------------------------------
+    # Server / Headers
+    # ------------------------------------------------------------------
+
+    # Prefixo base dos headers customizados aceitos pelo runtime do AgentCore.
+    # Exemplo final:
+    #   x-amzn-bedrock-agentcore-runtime-custom-user-email
+    header_prefix: str = "x-amzn-bedrock-agentcore-runtime-custom"
+
+    # ------------------------------------------------------------------
+    # AWS
+    # ------------------------------------------------------------------
+
+    # Região AWS usada para acessar serviços como SSM Parameter Store.
+    # Default alinhado com o ambiente do Bia Agent Builder.
+    aws_region: str = "sa-east-1"
+
+    # ------------------------------------------------------------------
+    # Client (MCP HTTP Client)
+    # ------------------------------------------------------------------
+
+    # Timeout padrão (em segundos) para chamadas HTTP ao servidor MCP.
+    # Evita requests presos indefinidamente em ambientes instáveis.
+    client_timeout_seconds: int = 120
+
+    # ------------------------------------------------------------------
+    # Factory methods
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def from_env() -> "BiaToolkitSettings":
+        """
+        Cria uma instância de BiaToolkitSettings a partir de variáveis de ambiente.
+
+        Comportamento:
+        - Cada configuração pode ser sobrescrita individualmente via env.
+        - Caso a variável não exista ou seja inválida, usa o valor default.
+
+        Variáveis suportadas:
+        - BIATOOLKIT_HEADER_PREFIX
+        - BIATOOLKIT_AWS_REGION
+        - BIATOOLKIT_CLIENT_TIMEOUT_SECONDS
+
+        Returns:
+            BiaToolkitSettings: instância configurada.
+        """
+
+        # Header prefix (string simples)
+        header_prefix = os.getenv(
+            "BIATOOLKIT_HEADER_PREFIX",
+            "x-amzn-bedrock-agentcore-runtime-custom",
+        )
+
+        # Região AWS
+        aws_region = os.getenv(
+            "BIATOOLKIT_AWS_REGION",
+            "sa-east-1",
+        )
+
+        # Timeout do client (conversão segura para int)
+        timeout_str = os.getenv(
+            "BIATOOLKIT_CLIENT_TIMEOUT_SECONDS",
+            "120",
+        )
+        try:
+            timeout = int(timeout_str)
+        except ValueError:
+            # Se o valor não for um inteiro válido, cai no default
+            timeout = 120
+
+        return BiaToolkitSettings(
+            header_prefix=header_prefix,
+            aws_region=aws_region,
+            client_timeout_seconds=timeout,
+        )

biatoolkit/util.py

@@ -1,79 +1,228 @@
+"""
+biatoolkit.util
+
+Este módulo contém a classe BiaUtil, uma "fachada" (facade) com utilidades comuns
+para MCP Servers no ecossistema Bia Agent Builder.
+
+Responsabilidades principais:
+- Ler e interpretar headers padronizados enviados no runtime (AWS Bedrock AgentCore).
+- Buscar parâmetros de configuração/segredos primeiro no ambiente (.env/variáveis),
+  e como fallback no AWS SSM Parameter Store (cofre de segredos no ambiente produtivo).
+"""
+
+from typing import Optional
+import os
+
+import boto3
 from mcp.server.fastmcp import FastMCP
+
+from .settings import BiaToolkitSettings
 from .schema.header import Header
 
-import boto3
-import os
 
-class BiaUtil():
+class BiaUtil:
+    """
+    Classe utilitária para uso dentro de um MCP Server.
+
+    Exemplos de uso:
+        util = BiaUtil(mcp)
+        header = util.get_header()
+        token = util.get_parameter("MEU_TOKEN")
 
+    Observações:
+    - Esta classe depende do contexto de requisição do FastMCP (mcp.get_context()).
+    - Em produção (AgentCore), apenas alguns headers são repassados pelo runtime.
+    """
+
+    # Prefixo base dos headers customizados aceitos no runtime do AgentCore.
+    # Exemplo de header final: "x-amzn-bedrock-agentcore-runtime-custom-user-email"
     HEADER_PREFIX = "x-amzn-bedrock-agentcore-runtime-custom"
 
-    def __init__(self, mcp: FastMCP):
+    def __init__(self, mcp: FastMCP, settings: Optional[BiaToolkitSettings] = None):
         """
-        Inicializa o utilitário BiaUtil com uma instância do FastMCP.
+        Inicializa o utilitário.
 
         Args:
-            mcp (FastMCP): Instância do servidor FastMCP para obter contexto da requisição.
+            mcp: Instância do FastMCP, usada para acessar o contexto da requisição.
+            settings: Configurações opcionais (region, timeout, header_prefix).
+                      Se None, carrega defaults e overrides via variáveis de ambiente.
         """
         self.mcp = mcp
 
+        # Settings podem vir explicitamente (testes/uso avançado) ou via environment.
+        self.settings = settings or BiaToolkitSettings.from_env()
+
+        # Permite sobrescrever o prefixo dos headers via settings.
+        # Mantém compatibilidade: self.HEADER_PREFIX é usado na composição das chaves.
+        self.HEADER_PREFIX = self.settings.header_prefix
+
+    def _headers(self) -> dict:
+        """
+        Obtém o dicionário de headers da requisição atual via contexto do MCP.
+
+        Returns:
+            dict: Headers presentes na requisição (ou {} se ausentes).
+        """
+        ctx = self.mcp.get_context()
+        # Estrutura esperada no FastMCP: ctx.request_context.request.headers
+        return ctx.request_context.request.headers or {}
+
+    def _h(self, suffix: str):
+        """
+        Lê um header customizado do runtime, dado o sufixo.
+
+        Exemplo:
+            suffix="user-email" -> lê "x-amzn-bedrock-agentcore-runtime-custom-user-email"
+
+        Args:
+            suffix: Parte final do nome do header.
+
+        Returns:
+            O valor do header (str) ou None.
+        """
+        return self._headers().get(f"{self.HEADER_PREFIX}-{suffix}", None)
+
+    def _to_int(self, value, default: int = 0) -> int:
+        """
+        Converte um valor para int de forma segura.
+
+        Por quê:
+        - Headers podem vir como None, string vazia ou valores inválidos ("abc").
+        - Este método evita exceptions e padroniza o fallback para 'default'.
+
+        Args:
+            value: valor a converter.
+            default: valor retornado caso não seja possível converter.
+
+        Returns:
+            int: valor convertido ou default.
+        """
+        try:
+            if value is None:
+                return default
+            if isinstance(value, str) and value.strip() == "":
+                return default
+            return int(value)
+        except (TypeError, ValueError):
+            return default
+
     def __get_from_ssm(self, parameter_name: str) -> str:
         """
         Busca o valor de um parâmetro no AWS SSM Parameter Store.
 
+        Como funciona:
+        - O runtime envia um header "...-prefix" que define a "pasta" (path) base dos segredos.
+        - O nome final do parâmetro no SSM fica: "{prefix}/{parameter_name}"
+        - WithDecryption=True permite ler SecureString.
+
+        Importante:
+        - Se não houver prefix no header, retorna None (não tenta chamar AWS).
+          Isso evita chamadas inválidas como "None/MEU_PARAM".
+
         Args:
-            parameter_name (str): Nome do parâmetro a ser buscado.
+            parameter_name: Nome do parâmetro a ser buscado.
 
         Returns:
-            str: Valor do parâmetro, ou None se não encontrado.
+            str | None: Valor do parâmetro, ou None se não encontrado/sem prefix.
         """
-        ctx = self.mcp.get_context()  # Obtém o contexto da requisição atual
-        headers = ctx.request_context.request.headers  # Acessa os headers da requisição
-        prefix = headers.get(f"{self.HEADER_PREFIX}-prefix", None)  # Prefixo customizado do header
-        client = boto3.client('ssm', region_name="sa-east-1")  # Cria cliente SSM na região especificada
+        # Obtém headers do contexto do MCP
+        headers = self._headers()
+
+        # Prefixo customizado do header que aponta para a "pasta" de segredos
+        prefix = headers.get(f"{self.HEADER_PREFIX}-prefix", None)
+
+        # Sem prefix não é possível montar o path no SSM; evita chamadas inválidas.
+        if not prefix:
+            return None
+
+        # Cria cliente SSM na região configurada (default: sa-east-1)
+        client = boto3.client("ssm", region_name=self.settings.aws_region)
+
         try:
             response = client.get_parameter(
                 Name=f"{prefix}/{parameter_name}",
-                WithDecryption=True
+                WithDecryption=True,
             )
         except client.exceptions.ParameterNotFound:
-            return None  # Retorna None se o parâmetro não for encontrado
-        return response.get('Parameter').get('Value')  # Retorna o valor do parâmetro
+            # Retorna None se o parâmetro não existir no SSM
+            return None
+
+        # Estrutura da resposta: {"Parameter": {"Value": "..."}}
+        return response.get("Parameter", {}).get("Value")
 
     def get_header(self) -> Header:
         """
-        Retorna os parâmetros padrão contidos no header da requisição.
+        Extrai e retorna um objeto Header com os principais campos do runtime.
 
         Returns:
-            Header: Objeto Header preenchido com os valores dos headers customizados.
+            Header: dataclass/objeto com os campos interpretados do header.
         """
-        ctx = self.mcp.get_context()  # Obtém o contexto da requisição atual
-        headers = ctx.request_context.request.headers  # Acessa os headers da requisição
-        # Preenche o objeto Header com os valores dos headers customizados
         return Header(
-            current_host=headers.get(f"{self.HEADER_PREFIX}-current-host", None),
-            user_email=headers.get(f"{self.HEADER_PREFIX}-user-email", None),
-            jwt_token=headers.get(f"{self.HEADER_PREFIX}-jwt-token", None),
-            jsessionid=headers.get(f"{self.HEADER_PREFIX}-jsessionid", None),
-            organization_id=int(headers.get(f"{self.HEADER_PREFIX}-organization-id", 0)),
-            codparc=int(headers.get(f"{self.HEADER_PREFIX}-codparc", 0)),
-            iam_user_id=int(headers.get(f"{self.HEADER_PREFIX}-iam-user-id", 0)),
-            gateway_token=headers.get(f"{self.HEADER_PREFIX}-gateway-token", None)
+            # Strings (podem ser None)
+            current_host=self._h("current-host"),
+            user_email=self._h("user-email"),
+            jwt_token=self._h("jwt-token"),
+            jsessionid=self._h("jsessionid"),
+
+            # Inteiros (com fallback seguro para 0)
+            organization_id=self._to_int(self._h("organization-id"), 0),
+            codparc=self._to_int(self._h("codparc"), 0),
+            iam_user_id=self._to_int(self._h("iam-user-id"), 0),
+
+            # String (pode ser None)
+            gateway_token=self._h("gateway-token"),
         )
-    
+
     def get_parameter(self, parameter_name: str) -> str:
         """
-        Retorna o valor do parâmetro, buscando primeiro na variável de ambiente
-        e depois no AWS SSM Parameter Store caso não exista na variável de ambiente.
+        Recupera um parâmetro sensível/configurável.
+
+        Ordem de resolução:
+        1) Variáveis de ambiente (ideal para execução local / CI)
+        2) AWS SSM Parameter Store (ideal para produção via cofre)
+
+        Observação:
+        - Implementação evita avaliar SSM antecipadamente.
+          (Não usamos mais os.getenv(name, default_func()) porque chamaria AWS sempre.)
+
+        Args:
+            parameter_name: Nome do parâmetro.
+
+        Returns:
+            str | None: valor encontrado ou None.
+        """
+        value = self._get_from_env(parameter_name)
+        if value is not None:
+            return value
+        return self._get_from_stores(parameter_name)
+
+    def _get_from_env(self, parameter_name: str):
+        """
+        Provider interno: busca em variáveis de ambiente do sistema.
+
+        Args:
+            parameter_name: Nome do parâmetro.
+
+        Returns:
+            str | None
+        """
+        return os.getenv(parameter_name)
+
+    def _get_from_stores(self, parameter_name: str):
+        """
+        Provider interno: busca em fontes externas (hoje apenas SSM).
+
+        Este método existe para facilitar manutenção e evolução:
+        amanhã pode incluir outros provedores (Secrets Manager, Vault, etc.)
+        sem mudar a API pública de get_parameter().
 
         Args:
-            parameter_name (str): Nome do parâmetro a ser buscado.
+            parameter_name: Nome do parâmetro.
 
         Returns:
-            str: Valor do parâmetro, ou None se não encontrado.
+            str | None
         """
-        # Busca o valor na variável de ambiente, se não existir busca no SSM
-        return os.getenv(
-            parameter_name,
-            self.__get_from_ssm(parameter_name)
-        )
+        return self.__get_from_ssm(parameter_name)
+
+
+__all__ = ["BiaUtil"]

{biatoolkit-1.0.3.dist-info → biatoolkit-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: biatoolkit
-Version: 1.0.3
+Version: 1.1.0
 Summary: Biblioteca para desenvolvedores que utilizam o BiaAgentBuilder
 Author: Bia Platform Team
 Author-email: data.platform@sankhya.com.br
@@ -19,45 +19,73 @@ Dynamic: summary
 
 # Bia Toolkit
 
-Biblioteca Python para facilitar o desenvolvimento de servidores MCP integrados ao Bia Agent Builder.
+Biblioteca Python para facilitar o desenvolvimento de servidores MCP integrados ao **Bia Agent Builder**.
 
-## **Principais classes da biblioteca**
+O objetivo da Bia Toolkit é abstrair detalhes técnicos do MCP (Model Context Protocol),
+fornecendo utilitários prontos para:
+- Comunicação com servidores MCP
+- Leitura de contexto do runtime (headers)
+- Recuperação segura de parâmetros e segredos
 
-Nesta seção você encontrará uma breve descrição de cada classe da biblioteca **Bia Toolkit**.
+---
 
-### **BasicClient**
+## Principais classes da biblioteca
 
-A classe `BasicClient` tem o objetivo de criar um cliente HTTP para comunicação com servidores MCP (Model Context Protocol).
+### BiaClient
 
-**Principais métodos**:
+A classe `BiaClient` encapsula um cliente HTTP assíncrono para comunicação com servidores MCP
+(Model Context Protocol).
 
-- **list_tools**: Lista todas as ferramentas disponíveis no servidor MCP.
-- **call_tool**: Executa uma ferramenta específica no servidor MCP.
+Ela esconde toda a complexidade de:
+- Conexão HTTP streamable
+- Inicialização de sessões MCP
+- Execução de tools
 
-### **Util**
+#### Principais métodos
 
-A classe `Util` fornece métodos auxiliares para gerenciar headers de requisições e parâmetros de configuração em servidores MCP.
+- **list_tools()**
+  - Lista todas as ferramentas disponíveis no servidor MCP.
 
-**Principais métodos**:
+- **call_tool(tool_name, params=None)**
+  - Executa uma ferramenta específica disponível no servidor MCP.
 
-- **construtor**: Recebe uma instância de FastMCP para acessar o contexto das requisições. Armazena a referência do MCP para uso nos métodos.
+---
 
-- **__get_from_ssm**: Busca um parâmetro no AWS SSM Parameter Store.
+### BiaUtil
 
-- **get_header**: Extrai e retorna todos os headers customizados da requisição atual. Retorna um objeto Header com os seguintes campos:
-  - current_host: Host do ERP no qual o copilot está em execução.
-  - user_email: Email do usuário autenticado.
-  - jwt_token: Token JWT do usuário -> SankhyaID, SankhyaPass ou Token interno Bia.
-  - jsessionid: ID de autenticação do ERP.
-  - organization_id: ID da organização da Bia.
-  - codparc: Código do parceiro (parceiro Sankhya).
-  - iam_user_id: ID do usuário do BIA IAM.
-  - gateway_token: Token primário do Sankhya API Gateway.
+A classe `BiaUtil` fornece métodos auxiliares para uso **dentro de MCP Servers**,
+permitindo acesso fácil a:
+- Headers padronizados enviados pelo runtime do Bia Agent Builder
+- Parâmetros sensíveis vindos de variáveis de ambiente ou cofre de segredos (AWS SSM)
+
+#### Principais métodos
+
+- **construtor**
+  - Recebe uma instância de `FastMCP` para acessar o contexto da requisição atual.
+
+- **get_header()**
+  - Extrai e retorna os headers customizados do runtime.
+  - Retorna um objeto `Header` com os campos:
+    - `current_host`: Host do ERP no qual o copilot está em execução.
+    - `user_email`: Email do usuário autenticado.
+    - `jwt_token`: Token JWT do usuário.
+    - `jsessionid`: ID de autenticação do ERP.
+    - `organization_id`: ID da organização da Bia.
+    - `codparc`: Código do parceiro Sankhya.
+    - `iam_user_id`: ID do usuário do BIA IAM.
+    - `gateway_token`: Token primário do Sankhya API Gateway.
+
+- **get_parameter(parameter_name)**
+  - Recupera parâmetros sensíveis seguindo a ordem:
+    1. Variáveis de ambiente do sistema
+    2. AWS SSM Parameter Store (fallback)
+
+  **Observações importantes:**
+  - O SSM só é consultado se o parâmetro **não existir** nas variáveis de ambiente.
+  - Em produção, a busca no SSM depende do header  
+    `X-Amzn-Bedrock-AgentCore-Runtime-Custom-prefix`.
+  - Se esse header não estiver presente, o método retorna `None`.
 
-- **get_parameter**: Busca o parâmetro informado em duas fontes distintas:
-  - Primeiro: Variáveis de ambiente do sistema.
-  - Segundo: AWS SSM Parameter Store (se não encontrado nas variáveis de ambiente).
-  - Retorna o valor do parâmetro ou None se não encontrado em nenhuma fonte.
 
 ## **Como utilizar**
 
@@ -97,7 +125,6 @@ def adicionar(id: int, nome: str) -> str:
     novo_item = {"id": id, "nome": nome}
     return json.dumps(novo_item, indent=4, sort_keys=True)
 
-
 if __name__ == "__main__":
     mcp.run(transport="streamable-http")
 ```
@@ -128,32 +155,29 @@ Crie um novo arquivo chamado `local.py` com o seguinte conteúdo:
 
 ```python
 import asyncio
-from biatoolkit.basic_client import BasicClient
+from biatoolkit.basic_client import BiaClient
 
 MCP_SERVER_URL = "http://0.0.0.0:8000/mcp"
-client = BasicClient(MCP_SERVER_URL)
+client = BiaClient(MCP_SERVER_URL)
 
-async def list_tools() -> None:
+async def list_tools():
     tools = await client.list_tools()
     for tool in tools.tools:
         print(f"Tool: {tool.name}, Description: {tool.description}")
 
-
-async def call_tool(tool_name: str, params: dict = None) -> None:
+async def call_tool(tool_name: str, params: dict = None):
     result = await client.call_tool(tool_name, params)
     print(result.content[0].text)
 
-
 async def main():
     await list_tools()
-    
 
 asyncio.run(main())
 ```
 
 #### **Entendendo o código**
 
-- **BasicClient**: É uma classe da biblioteca **Bia Toolkit** que encapsula um cliente HTTP para comunicação com servidores MCP.
+- **BiaClient**: É uma classe da biblioteca **Bia Toolkit** que encapsula um cliente HTTP para comunicação com servidores MCP.
 - **list_tools**: Executa a instrução `client.list_tools()` para recuperar todas as ferramentas disponíveis no servidor MCP.
 - **call_tool**: Executa a instrução `client.call_tool(tool_name, params)` para executar uma ferramenta específica do servidor MCP.
 
@@ -204,7 +228,7 @@ Se seu servidor MCP estiver sendo executado **localmente**, você conseguirá in
 
 ```python
 import asyncio
-from biatoolkit.basic_client import BasicClient
+from biatoolkit.basic_client import BiaClient
 
 MCP_SERVER_URL = "http://0.0.0.0:8000/mcp"
 
@@ -226,7 +250,7 @@ headers = {
     "Content-Type": "application/json"
 }
 
-client = BasicClient(MCP_SERVER_URL, headers=headers)
+client = BiaClient(MCP_SERVER_URL, headers=headers)
 
 async def list_tools() -> None:
     tools = await client.list_tools()
@@ -246,19 +270,13 @@ async def main():
 asyncio.run(main())
 ```
 
-#### **Entendendo o código**
-
-- **headers**: Veja que a variável `headers` é definida com a lista de parâmetros válidos e depois utilizada em `client = BasicClient(MCP_SERVER_URL, headers=headers)`.
-
-⚠️ IMPORTANTE: Ao utilizar os serviços de interação com a Bia (**/agent/stream**, **/agent/message** ou **/agent/invoke**),  os parâmetros já são automaticamente preenchidos e enviados pelos serviços.
-
-### **Recuperando os parâmetros no MCP Server enviados via header**
+...existing code...
 
-Para recuperar os parâmetros no MCP Server que foram enviados por meio do `header` da requisição, basta utilizar a classe `Util` conforme a seguir:
+Para recuperar os parâmetros no MCP Server que foram enviados por meio do `header` da requisição, basta utilizar a classe `BiaUtil` conforme a seguir:
 
 ```python
 from mcp.server.fastmcp import FastMCP
-from biatoolkit.util import Util
+from biatoolkit.util import BiaUtil
 
 mcp = FastMCP(host="0.0.0.0", stateless_http=True)
 
@@ -266,7 +284,7 @@ mcp = FastMCP(host="0.0.0.0", stateless_http=True)
 def processar() -> str:
     """Executa o processamento de algo"""
     
-    util = Util(mcp)
+    util = BiaUtil(mcp)
     header = util.get_header()
 
     # Exemplo de uso dos parâmetros do header. Utilize conforme a necessidade 
@@ -296,11 +314,11 @@ Você pode utilizar parâmetros sensíveis de duas formas:
 - Usando o cofre de segredos do Bia Agent Builder para execução em ambiente produtivo.
   - Você pode adicionar parâmetros sensíveis no cofre de segredos do Bia Agent Builder. Para adicionar, alterar e excluir os parâmetros do cofre, utilize as funcionalidades da Plataforma Bia Agent Builder UI.
 
-Para recuperar um valor sensível no seu MCP Server, utilize o método `get_parameter(parameter_name: str)` da classe `Util`.
+Para recuperar um valor sensível no seu MCP Server, utilize o método `get_parameter(parameter_name: str)` da classe `BiaUtil`.
 
 ```python
 from mcp.server.fastmcp import FastMCP
-from biatoolkit.util import Util
+from biatoolkit.util import BiaUtil
 
 mcp = FastMCP(host="0.0.0.0", stateless_http=True)
 
@@ -308,7 +326,7 @@ mcp = FastMCP(host="0.0.0.0", stateless_http=True)
 def processar() -> str:
     """Executa o processamento de algo"""
     
-    util = Util(mcp)
+    util = BiaUtil(mcp)
     valor = util.get_parameter("meu_parametro")
 
     # Exemplo de uso do parâmetro recuperado. Utilize conforme a necessidade 

biatoolkit-1.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+biatoolkit/__init__.py,sha256=OStl3T8OY7YdGdpKIpwXtTo-IjcQxzDRHzpAoBEM8yU,98
+biatoolkit/basic_client.py,sha256=qp5T85wm6D80i3Owjz9AxUYKmaKHgImxirYCduBi1gk,4760
+biatoolkit/settings.py,sha256=gA07EMEb9k5tt6ySCOYTV4pKHPSiG7nSap2qhHQhmFY,3494
+biatoolkit/util.py,sha256=PgYKRl85K4wmF4WFrabTQ3yiTmgw9S2BxZ-uvwFnP6A,7768
+biatoolkit/schema/__init__.py,sha256=6lvcENhbQnelI2faBGnEs0yG0k4SkwtIrtmn4PtKWvg,32
+biatoolkit/schema/header.py,sha256=COJPlqK1cFvvWzDcCw2ru1jszWPgyyvabkjzDCc8AjM,683
+biatoolkit-1.1.0.dist-info/METADATA,sha256=4_YWz1I9WXRO91QaQkmydpr6DpeZh_bNBkhqsFedQNo,13174
+biatoolkit-1.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+biatoolkit-1.1.0.dist-info/top_level.txt,sha256=DyrMS0X6u1FDA9uT854LxoT3X7gzMAlsFQabE-WuKMc,11
+biatoolkit-1.1.0.dist-info/RECORD,,

biatoolkit-1.0.3.dist-info/RECORD

@@ -1,9 +0,0 @@
-biatoolkit/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-biatoolkit/basic_client.py,sha256=_N2-NcrVWfm-rUuJUksOdR8GONmLYzooMhX1El49A3c,2581
-biatoolkit/util.py,sha256=wP1r29MLVk27iMnMG_Xywa6Yt6H-XfHdlrb4u8Tmg6c,3288
-biatoolkit/schema/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-biatoolkit/schema/header.py,sha256=COJPlqK1cFvvWzDcCw2ru1jszWPgyyvabkjzDCc8AjM,683
-biatoolkit-1.0.3.dist-info/METADATA,sha256=3kUZGId145VtBiInuRnFqwdy9sJMEqbKqAHUAGYB0BA,13181
-biatoolkit-1.0.3.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-biatoolkit-1.0.3.dist-info/top_level.txt,sha256=DyrMS0X6u1FDA9uT854LxoT3X7gzMAlsFQabE-WuKMc,11
-biatoolkit-1.0.3.dist-info/RECORD,,