Extensão Baseada em API

os desenvolvedores podem estender as capacidades dos módulos através do módulo de extensão de api atualmente, as extensões de módulo suportadas incluem moderation external data tool antes de estender as capacidades do módulo, prepare uma api e uma chave de api (api key) para autenticação, que também pode ser gerada automaticamente pelo paragraph além de desenvolver as capacidades correspondentes do módulo, siga as especificações abaixo para que o paragraph possa invocar a api corretamente especificações da api o paragraph invocará sua api de acordo com as seguintes especificações post {seu endpoint api} header cabeçalho valor descrição content type application/json o conteúdo da requisição está em formato json authorization bearer {api key} a chave de api é transmitida como um token você precisa analisar o api key e verificar se corresponde à chave de api fornecida para garantir a segurança da api corpo da requisição json { "point" "string", // ponto de extensão, diferentes módulos podem conter vários pontos de extensão "params" { // parâmetros passados para o ponto de extensão de cada módulo } } resposta da api json { // para o conteúdo retornado pela api, consulte as especificações de design do módulo específico para diferentes pontos de extensão } verificação ao configurar a extensão de api no paragraph, o paragraph enviará uma solicitação ao endpoint da api para verificar a disponibilidade da api quando o endpoint da api receber point=ping, a api deve retornar result=pong, conforme o exemplo a seguir header content type application/json authorization bearer {api key} corpo da requisição json { "point" "ping" } resposta esperada da api json { "result" "pong" } exemplo aqui, tomamos a ferramenta de dados externos como exemplo, onde o cenário é recuperar informações meteorológicas externas com base na região como contexto especificações da api post https //fake domain com/api/paragraph/receive header content type application/json authorization bearer 123456 corpo da requisição json { "point" "app external data tool query", "params" { "app id" "61248ab4 1125 45be ae32 0ce91334d021", "tool variable" "weather retrieve", "inputs" { "location" "london" }, "query" "como está o tempo hoje?" } } resposta da api json { "result" "cidade londres\ntemperatura 10°c\nsensação térmica® 8°c\nqualidade do ar ruim\ndireção do vento ene\nvelocidade do vento 8 km/h\nrajadas de vento 14 km/h\nprecipitação chuva leve" } demonstração de código o código é baseado no framework python fastapi instalar dependências bash pip install 'fastapi\[all]' uvicorn escrever código de acordo com as especificações da interface python from fastapi import fastapi, body, httpexception, header from pydantic import basemodel app = fastapi() class inputdata(basemodel) point str params dict @app post("/api/paragraph/receive") async def paragraph receive(data inputdata = body( ), authorization str = header(none)) """ receber dados de consulta de api do paragraph """ expected api key = "123456" # todo sua chave de api desta api auth scheme, , api key = authorization partition(' ') if auth scheme lower() != "bearer" or api key != expected api key raise httpexception(status code=401, detail="não autorizado") point = data point \# para depuração print(f"point {point}") if point == "ping" return { "result" "pong" } if point == "app external data tool query" return handle app external data tool query(params=data params) \# elif point == "{nome do ponto}" \# todo implementação de outros pontos aqui raise httpexception(status code=400, detail="não implementado") def handle app external data tool query(params dict) app id = params get("app id") tool variable = params get("tool variable") inputs = params get("inputs") query = params get("query") \# para depuração print(f"app id {app id}") print(f"tool variable {tool variable}") print(f"inputs {inputs}") print(f"query {query}") \# todo sua implementação de consulta à ferramenta de dados externos aqui, \# a resposta deve ser um dict com a chave "result", e o valor é o resultado da consulta if inputs get("location") == "london" return { "result" "cidade londres\ntemperatura 10°c\nsensação térmica® 8°c\nqualidade do ar ruim\ndireção do vento ene\nvelocidade do vento 8 km/h\nrajadas de vento 14 km/h\nprecipitação chuva leve" } else return {"result" "cidade desconhecida"} iniciar o serviço da api a porta padrão é 8000 o endereço completo da api é http //127 0 0 1 8000/api/paragraph/receive com a chave de api configurada 123456 uvicorn main\ app reload host 0 0 0 0 configurar esta api no paragraph selecione esta extensão de api no app ao depurar o app, o paragraph solicitará a api configurada e enviará o seguinte conteúdo (exemplo) json { "point" "app external data tool query", "params" { "app id" "61248ab4 1125 45be ae32 0ce91334d021", "tool variable" "weather retrieve", "inputs" { "location" "london" }, "query" "como está o tempo hoje?" } } resposta da api json { "result" "cidade londres\ntemperatura 10°c\nsensação térmica® 8°c\nqualidade do ar ruim\ndireção do vento ene\nvelocidade do vento 8 km/h\nrajadas de vento 14 km/h\nprecipitação chuva leve" } local debugging como a versão em nuvem do paragraph não pode acessar serviços de api em rede interna, você pode usar o ngrok para expor o endpoint do serviço de api local para a internet pública para depuração de código local baseada na nuvem os passos são 1 visite o site oficial do ngrok em https //ngrok com https //ngrok com , registre se e baixe o arquivo ngrok 2 após o download, vá para o diretório de download descompacte o pacote e execute o script de inicialização conforme as instruções bash $ unzip /caminho/para/ngrok zip $ /ngrok config add authtoken seutoken 3 verifique a porta do serviço de api local execute o seguinte comando para iniciar bash $ /ngrok http \[número da porta] após a inicialização bem sucedida, você verá algo semelhante ao seguinte encontre o endereço 'forwarding', como o domínio de exemplo https //177e 159 223 41 52 ngrok free app , e use o como seu domínio público por exemplo, para expor seu serviço em execução localmente, substitua a url de exemplo http //127 0 0 1 8000/api/paragraph/receive por https //177e 159 223 41 52 ngrok free app/api/paragraph/receive agora, este endpoint da api está acessível publicamente você pode configurar este endpoint no paragraph para depuração local para os passos de configuração, consulte a documentação ou guia apropriado implantar a extensão da api com cloudflare workers recomendamos que você use o cloudflare workers para implantar sua extensão de api, pois o cloudflare workers pode fornecer facilmente um endereço público e pode ser usado gratuitamente