Runtime de Tarefas: Bibliotecas Disponíveis

O código Python de um Agent de Tarefa é executado em um ambiente controlado, com um conjunto fixo de bibliotecas, módulos e funções. Esta página é a referência oficial do que está disponível nesse ambiente.

Contrato do runtime

Somente o que consta nesta página é garantido no runtime. Bibliotecas não listadas aqui não devem ser assumidas como disponíveis, mesmo que algum código existente aparente utilizá-las — elas podem deixar de funcionar a qualquer momento. Veja como solicitar novas bibliotecas.

Como seu código é executado

Antes de olhar as bibliotecas, é importante entender a convenção de execução:

• O código deve definir uma função principal com o mesmo nome da identificação no sistema (slug) do Agent. É essa função que a plataforma chama ao executar a tarefa.
• Os parâmetros definidos na configuração do Agent são passados como argumentos nomeados para essa função.
• O retorno deve ser um dict. Se a função retornar outro tipo, o valor é embrulhado automaticamente em {"result": <valor>}.
• A execução tem tempo limite: tarefas síncronas devem concluir em poucos segundos (veja Tipo de Execução); processamentos longos devem usar execução assíncrona.

def processar_pedidos(data_inicio, data_fim):
    pedidos = requests.get(
        "https://api.exemplo.com/pedidos",
        params={"inicio": data_inicio, "fim": data_fim},
    ).json()

    return {"total": len(pedidos)}

info

No exemplo acima, requests é usado diretamente, sem import — é uma variável global injetada pelo runtime, como descrito a seguir.

Variáveis globais injetadas

As bibliotecas abaixo já estão disponíveis como variáveis globais no seu código. Use-as diretamente, sem declarar import.

Biblioteca padrão (stdlib)

Global	Equivale a	Uso típico
json	módulo json	Serialização JSON
re	módulo re	Expressões regulares
time	módulo time	Pausas e timestamps
datetime	classe datetime.datetime	Datas e horas
timedelta	classe datetime.timedelta	Aritmética de datas
timezone	classe datetime.timezone	Fusos horários
base64	módulo base64	Codificação Base64
b64encode	base64.b64encode	Alias de compatibilidade — prefira base64.b64encode
hashlib	módulo hashlib	Hashes (SHA, MD5)
hmac	módulo hmac	Assinaturas HMAC
io	módulo io	Buffers em memória (io.BytesIO)
zipfile	módulo zipfile	Leitura/escrita de ZIP
deepcopy	copy.deepcopy	Cópia profunda de estruturas
urlencode	urllib.parse.urlencode	Query strings
ElementTree	xml.etree.ElementTree	Parsing de XML
asyncio	módulo asyncio	Execução assíncrona

def exemplo_stdlib():
    agora = datetime.now(timezone.utc)
    ontem = agora - timedelta(days=1)
    assinatura = hmac.new(b"chave", b"payload", hashlib.sha256).hexdigest()

    return {"desde": ontem.isoformat(), "assinatura": assinatura}

Atenção

datetime, timedelta e timezone são as classes, não os módulos. Use datetime.now(...) diretamente (e não datetime.datetime.now(...)).

Bibliotecas de terceiros

Global	Biblioteca	Uso típico
requests	requests	Chamadas HTTP síncronas
httpx	httpx	Chamadas HTTP síncronas e assíncronas
paramiko	paramiko	SFTP e SSH
sendgrid	sendgrid	Envio de e-mails via SendGrid
docbr	validate-docbr	Validação de CPF/CNPJ
jwt	PyJWT	Geração e validação de tokens JWT
img2pdf	img2pdf	Conversão de imagens em PDF
pypdf	pypdf	Leitura e manipulação de PDF

def valida_documento(cpf):
    validador = docbr.CPF()

    return {"valido": validador.validate(cpf)}

Pydantic e typing

Para validação de dados e anotações de tipo, também estão injetados:

• Pydantic: BaseModel, Field, ValidationError, EmailStr, field_validator, model_validator
• Typing: Any, Union, Tuple, Set, Optional, Dict, Type, List

class Pedido(BaseModel):
    id: int
    email: EmailStr
    itens: List[str] = Field(default_factory=list)

def valida_pedido(payload):
    try:
        pedido = Pedido(**payload)
    except ValidationError as e:
        return {"valido": False, "erros": e.errors()}

    return {"valido": True, "pedido": pedido.model_dump()}

Módulos importáveis via import

Além dos globais injetados, os módulos abaixo podem ser importados explicitamente com a instrução import:

• csv
• hmac
• hashlib

import csv

def gera_relatorio(linhas):
    buffer = io.StringIO()
    writer = csv.writer(buffer)
    writer.writerows(linhas)

    return {"csv": buffer.getvalue()}

Funções built-in disponíveis

O runtime expõe um conjunto controlado de built-ins do Python:

• Tipos e conversões: str, int, float, bool, list, dict, tuple, set, type
• Iteração: range, enumerate, zip, map, filter, any, all, next, iter, sorted, reversed
• Matemática e formatação: abs, min, max, sum, round, pow, divmod, format, ord, chr, len
• Introspecção: isinstance, hasattr, getattr, setattr
• Exceções: Exception, ValueError, TypeError, KeyError, IndexError, AttributeError
• Definição de classes (class ...:) é suportada

Built-ins que NÃO estão disponíveis

Alguns built-ins comuns do Python não existem no runtime de tarefas e geram NameError se utilizados:

• print — para expor informações, inclua-as no dict de retorno da função.
• open — não há acesso a arquivos locais; trabalhe com dados em memória (io.BytesIO, io.StringIO).
• eval / exec — execução dinâmica de código não é suportada.

O que NÃO está garantido

warning

Esta página é o contrato do runtime de tarefas: apenas as bibliotecas, módulos e funções listados aqui são suportados. Código que dependa de qualquer outra biblioteca não tem garantia de funcionamento e pode quebrar sem aviso em atualizações da plataforma.

Precisa de uma biblioteca que não está na lista (por exemplo, processamento avançado de arquivos)? Solicite ao time da plataforma Tech4AI. Novas bibliotecas passam por avaliação prévia (segurança, licença e manutenção) antes de serem adicionadas ao runtime — e, uma vez incorporadas, passam a constar nesta página.

Escopo desta página

Esta referência cobre apenas Agents de Tarefas. O ambiente de execução das actions de Agents Conversacionais é diferente — consulte a documentação do Actions SDK v2.