Arquivos (FileManager)

O FileManager gerencia upload e download de arquivos para o storage da plataforma. Use quando a action precisa armazenar arquivos gerados ou disponibilizar arquivos ao usuário.

Inicialização

from actions_sdk.core.types.action_context import ActionContext
from actions_sdk.features.files import FileManager

ctx: ActionContext

fm = FileManager(ctx)

Funciona com ActionContext e TaskContext. Extrai ctx.file_storage automaticamente.

---

Métodos

upload_file()

Realiza o upload de um arquivo para o storage. Deve fornecer file_url ou file_bytes.

from uuid import UUID

fm = FileManager(ctx)

# Upload por URL (o storage baixa e re-hospeda)
file_id: UUID = fm.upload_file(file_url="https://exemplo.com/documento.pdf")

# Upload por bytes
conteudo = "Conteúdo do arquivo".encode("utf-8")
file_id: UUID = fm.upload_file(
    file_bytes=conteudo,
    filename="relatorio.txt",
)

Parâmetros:

Parâmetro	Tipo	Descrição
file_url	str | None	URL do arquivo a baixar e reenviar
file_bytes	bytes | None	Bytes brutos do arquivo
filename	str | None	Nome do arquivo (usado pelo storage)

Retorna: UUID — ID do arquivo no storage.

Exceções:

• RuntimeError — se ctx.file_storage não foi injetado
• ValueError — se nem file_url nem file_bytes forem fornecidos
• FileStorageError — se o upload falhar

---

get_file_url(file_id)

Retorna uma URL temporária para acesso ao arquivo.

from uuid import UUID

url = fm.get_file_url(UUID("550e8400-e29b-41d4-a716-446655440000"))

Parâmetros: file_id (UUID) — ID do arquivo.

Retorna: str — URL de acesso ao arquivo.

Exceções:

• RuntimeError — se ctx.file_storage não foi injetado
• FileStorageError — se o arquivo não for encontrado ou download falhar

---

download_file(file_id)

Alias de get_file_url(). Mantido para conveniência de nomenclatura.

url = fm.download_file(file_id)

---

FileStorageError

from actions_sdk.core.interfaces.file_storage import FileStorageError

try:
    file_id = fm.upload_file(file_bytes=conteudo, filename="arquivo.txt")
except FileStorageError as erro:
    return ResponseToAgent(
        status=ResponseStatus.ERROR,
        instruction=f"Falha no upload: {erro}",
    )

---

Enviar arquivo ao usuário

Use ResponseToUser.files para enviar arquivos ao usuário junto com uma mensagem:

from actions_sdk.core.types.responses import ResponseToUser, FileContent

file_id = fm.upload_file(file_bytes=conteudo, filename="relatorio.pdf")
url = fm.get_file_url(file_id)

return ResponseToUser(
    message="Seu relatório está pronto!",
    files=[
        FileContent(
            fileId=str(file_id),
            fileName="relatorio.pdf",
            url=url,
        )
    ],
)

---

Exemplo completo

Baseado na action file_upload do agente de homologação:

import traceback

from actions_sdk.core.types.action_context import ActionContext
from actions_sdk.core.types.responses import ResponseStatus, ResponseToAgent
from actions_sdk.features.conversational.state import StateManager
from actions_sdk.features.files import FileManager
from actions_sdk.features.tracing import ActionSpan

ctx: ActionContext

CHAVE_PROGRESSO = "action.files.progresso"
ENCODING = "utf-8"


def fazer_upload(nome_arquivo: str, conteudo: str):
    span = ActionSpan(ctx)
    state = StateManager(ctx)

    conteudo_bytes = conteudo.encode(ENCODING)
    span.event("action.files.inicio", {"nome": nome_arquivo, "bytes": len(conteudo_bytes)})

    try:
        fm = FileManager(ctx)
        file_id = fm.upload_file(
            file_bytes=conteudo_bytes,
            filename=nome_arquivo,
        )
        state.update(CHAVE_PROGRESSO, "SUCESSO ✓")

        span.event("action.files.sucesso", {"file_id": str(file_id)})

        return ResponseToAgent(
            status=ResponseStatus.SUCCESS,
            instruction=(
                f"FileManager.upload_file() concluído.\n"
                f"Arquivo: '{nome_arquivo}' ({len(conteudo_bytes)} bytes)\n"
                f"ID no storage: {file_id}"
            ),
            state_updates=state.get_full_state(),
        )

    except Exception as erro:
        state.update(CHAVE_PROGRESSO, "ERRO ✗")
        span.event("action.files.erro", {"erro": str(erro)})
        return ResponseToAgent(
            status=ResponseStatus.ERROR,
            instruction=f"Falha no upload: {traceback.format_exc()}",
            state_updates=state.get_full_state(),
        )