AIVAX
PT
English Português
Copiar página
Ver como Markdown Editar fonte em inglês

Esta página foi traduzida automaticamente do inglês e pode estar desatualizada. Leia o original

Trabalhadores de IA

Os trabalhadores do AI Gateway são hooks HTTP que permitem que um serviço externo controle a execução do gateway em tempo de execução. Um trabalhador pode permitir um evento, interrompê-lo, reescrever o contexto, adicionar instruções ou ferramentas, ou substituir o resultado de uma ferramenta do lado do servidor.

Use trabalhadores quando uma regra deve ser decidida fora do prompt. Casos comuns incluem verificações de assinatura, enriquecimento de CRM, política específica de locatário, registro de auditoria, bloqueio dinâmico de ferramentas e substituir o resultado de uma ferramenta visível ao modelo por dados de um sistema interno.

Os trabalhadores executam no caminho crítico da inferência. Cada evento de trabalhador adiciona uma requisição HTTP antes que o gateway possa continuar, portanto o endpoint deve responder rápida e previsivelmente.

Formato da solicitação #

Quando um evento de trabalhador configurado dispara, o AIVAX envia uma requisição POST para a URL do trabalhador do gateway.

JSON 
{
    "gatewayId": "your-gateway-id",
    "moment": "2025-12-29T17:04:39",
    "event": {
        "name": "message.received",
        "data": {
            "messages": [
                {
                    "role": "system",
                    "content": "User local date is Monday, December 29, 2025 (timezone is America/Sao_Paulo)"
                },
                {
                    "role": "user",
                    "content": "Good morning"
                }
            ],
            "origin": "ChatCompletionsApi",
            "externalUserId": "customer-123",
            "metadata": {}
        }
    }
}

A forma exata de event.data depende do evento. Sempre valide gatewayId quando um endpoint serve mais de um gateway.

Autenticação #

Quando a conta possui uma chave de hook, o AIVAX envia X-Request-Nonce. O nonce é um hash BCrypt derivado da chave de hook da conta. Valide este cabeçalho antes de confiar no corpo, especialmente quando o trabalhador libera dados privados, altera o contexto ou autoriza o uso de ferramentas.

Trate externalUserId, metadata, mensagens e argumentos de ferramentas como entrada não confiável.

Comportamento da resposta #

Após enviar a requisição, o AIVAX trata a resposta do trabalhador da seguinte forma:

RespostaComportamento
Content-Type: application/json+worker-actionExecute a ação descrita no corpo JSON.
2xx sem application/json+worker-actionContinue normalmente.
Resposta não OK sem application/json+worker-actionInterrompa o evento.

Se a requisição do trabalhador falhar com uma exceção de requisição HTTP, o AIVAX registra a falha e interrompe o evento.

Escolha intencionalmente o comportamento fail-open ou fail-closed. Retorne 2xx quando o enriquecimento for opcional. Retorne uma resposta não OK quando a autorização, conformidade ou política de negócio não puder falhar aberta.

message.received #

O evento message.received dispara após o gateway preparar o contexto da mensagem recebida e antes da chamada ao modelo.

JSON 
{
    "name": "message.received",
    "data": {
        "messages": [],
        "origin": "ChatCompletionsApi",
        "externalUserId": "customer-123",
        "metadata": {}
    }
}

Para modificar o contexto, retorne Content-Type: application/json+worker-action com type: "message.received.response":

JSON 
{
    "type": "message.received.response",
    "data": {
        "rewrites": [
            {
                "type": "add-system",
                "message": "Answer in formal English."
            }
        ]
    }
}

Ações de reescrita disponíveis:

AçãoDescriçãoParâmetros
clearRemove elementos do contexto.argument: messages, meta, system, tools, skills, all ou omitido.
add-messageAdiciona uma mensagem à conversa.message: objeto de mensagem compatível com OpenAI.
remove-messageRemove uma mensagem por índice.index: índice da mensagem (baseado em zero).
add-systemAdiciona uma instrução de sistema.message: texto da instrução.
add-toolAdiciona uma definição de ferramenta compatível com OpenAI.tool: objeto JSON da ferramenta.
add-protocol-toolAdiciona uma função de protocolo.tool: definição da função de protocolo.
add-mcp-sourceAdiciona as ferramentas descobertas de uma fonte MCP ao contexto.source: objeto de fonte MCP com url, headers, name e/ou cacheDuration.

Substituir o contexto do usuário #

JSON 
{
    "type": "message.received.response",
    "data": {
        "rewrites": [
            {
                "type": "clear"
            },
            {
                "type": "add-message",
                "message": {
                    "role": "user",
                    "content": "The original message was removed by an external policy check. Tell the user they need an active subscription to continue."
                }
            }
        ]
    }
}

Remover uma mensagem #

JSON 
{
    "type": "message.received.response",
    "data": {
        "rewrites": [
            {
                "type": "remove-message",
                "index": 0
            }
        ]
    }
}

Adicionar uma fonte MCP temporária #

JSON 
{
    "type": "message.received.response",
    "data": {
        "rewrites": [
            {
                "type": "add-mcp-source",
                "source": {
                    "name": "Internal CRM",
                    "url": "https://crm.example.com/mcp",
                    "headers": {
                        "Authorization": "Bearer <INTERNAL_CRM_TOKEN>"
                    },
                    "cacheDuration": 600
                }
            }
        ]
    }
}

Use add-mcp-source quando a lista de ferramentas precisar depender da mensagem, usuário, canal ou de uma política externa. O AIVAX lista as ferramentas do servidor MCP, converte cada esquema em uma função chamável pelo modelo e disponibiliza essas ferramentas apenas para aquela inferência. Para fontes permanentes, configure o MCP diretamente no AI Gateway.

tool.called #

O evento tool.called dispara antes que o AIVAX execute uma ferramenta interna do lado do servidor.

JSON 
{
    "name": "tool.called",
    "data": {
        "toolName": "check_order",
        "toolArguments": {
            "order_id": "A123"
        },
        "origin": "ChatCompletionsApi",
        "externalUserId": "customer-123",
        "metadata": {}
    }
}

Retorne uma resposta não OK para bloquear a chamada da ferramenta. Retorne 2xx para permitir que o AIVAX execute a ferramenta normalmente.

Para substituir o resultado da ferramenta, retorne Content-Type: application/json+worker-action com type: "tool.called.response":

JSON 
{
    "type": "tool.called.response",
    "data": {
        "result": "Order A123 is paid and scheduled for delivery tomorrow.",
        "messages": []
    }
}

Campos de data:

CampoDescrição
resultConteúdo textual injetado como resultado da ferramenta.
messagesMensagens adicionais opcionais no formato OpenAI anexadas ao contexto da conversa.

Quando tool.called.response é retornado, o AIVAX usa o resultado fornecido pelo trabalhador em vez de executar o manipulador padrão da ferramenta.

Exemplo: bloqueando usuários não autorizados #

O exemplo abaixo mostra um Cloudflare Worker que bloqueia uma chamada ao gateway quando o usuário externo não tem permissão.

JavaScript 
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const body = await request.json();

    if (body.gatewayId !== env.CHECKING_GATEWAY_ID) {
      return new Response();
    }

    if (body.event?.name !== "message.received") {
      return new Response();
    }

    const externalUserId = body.event.data.externalUserId;
    const allowedUsers = new Set((env.ALLOWED_USERS || "").split(","));

    if (!allowedUsers.has(externalUserId)) {
      return new Response("User is not authorized", { status: 403 });
    }

    return new Response();
  }
};

Exemplo: substituindo uma ferramenta por um sistema interno #

Use tool.called quando o modelo deve ver um resultado de ferramenta, mas os dados reais devem vir do seu sistema.

JavaScript 
export default {
  async fetch(request, env) {
    const body = await request.json();

    if (body.event?.name !== "tool.called") {
      return new Response();
    }

    const { toolName, toolArguments, externalUserId } = body.event.data;

    if (toolName !== "check_order") {
      return new Response();
    }

    const orderId = toolArguments?.order_id;
    const orderResponse = await fetch(`${env.INTERNAL_API}/orders/${orderId}`, {
      headers: {
        "Authorization": `Bearer ${env.INTERNAL_API_TOKEN}`
      }
    });

    if (!orderResponse.ok) {
      return new Response(JSON.stringify({
        type: "tool.called.response",
        data: {
          result: `The order ${orderId} could not be retrieved for user ${externalUserId}. Ask the user to confirm the order number.`
        }
      }), {
        headers: {
          "Content-Type": "application/json+worker-action"
        }
      });
    }

    const order = await orderResponse.json();

    return new Response(JSON.stringify({
      type: "tool.called.response",
      data: {
        result: `Order ${order.id}: status ${order.status}, estimated delivery ${order.eta}.`
      }
    }), {
      headers: {
        "Content-Type": "application/json+worker-action"
      }
    });
  }
};

Esse padrão evita expor a API interna diretamente ao modelo. O trabalhador continua responsável por autenticar a requisição, validar o usuário, chamar o sistema interno e decidir quanta informação pode ser retornada ao contexto do modelo.

Para saber como os trabalhadores se encaixam na execução do gateway, veja Pipelines.

Digite para pesquisar na documentação.