Criando tarefas via API

Dentro do seu App da Workstation você pode criar tarefas e revisar as saídas delas para garantir que os resultados estão corretos.

Criando tarefas via API

Criar uma tarefa é parecido com chamar um Canvas: em vez de passar um canvas_id, você passa o seu application_id. Vá até a página do seu App da Workstation e siga estes passos:

Abrir as configurações do app

Na barra do topo, clique no botão … ao lado do botão Compartilhar e selecione Configurações.

Pegue os dados do app

Abra a aba API. Ali estão o ID do seu App e tudo o que você precisa para criar tarefas via API. Escolha a linguagem de sua preferência e use um dos snippets de código para começar a integrar.

Por padrão, todas as tarefas são criadas como completions assíncronas. Você recebe uma resposta com o status success, e a tarefa criada fica com o status running. Há duas formas de consumir o resultado de uma tarefa:

Fazer polling durante a execução
Usar uma URL de webhook

Polling de tasks durante a execução

Você pode fazer polling de uma tarefa até que ela saia do status running. Quando a execução termina, a tarefa passa para validating (o resultado está pronto e aguardando revisão) ou para failed. Ela só fica completed depois que alguém a aprova no App. Para obter o status de uma tarefa depois de criá-la, envie uma requisição para o endpoint /task da API.

let task = await tela.completions.create<{ document: TelaFile }, { fileSummary: string }>({
    applicationId: process.env.TELA_APPLICATION_ID,
    variables: {
        document: tela.createFile('https://example.com/document.pdf')
    },
})

let isTaskCompleted = false

while (!isTaskCompleted) {
    await new Promise((resolve) => setTimeout(resolve, 2000))
    const response = await fetch(`https://api.tela.com/task/${task.id}`, {
        headers: { Authorization: `Bearer ${process.env.TELA_API_KEY}` },
    })
    task = await response.json()
    isTaskCompleted = ['validating', 'completed', 'failed', 'cancelled'].includes(task.status)
}

let task = await tela.completions.create({
    applicationId: process.env.TELA_APPLICATION_ID,
    variables: {
        document: tela.createFile('https://example.com/document.pdf')
    },
})

let isTaskCompleted = false

while (!isTaskCompleted) {
    await new Promise((resolve) => setTimeout(resolve, 2000))
    const response = await fetch(`https://api.tela.com/task/${task.id}`, {
        headers: { Authorization: `Bearer ${process.env.TELA_API_KEY}` },
    })
    task = await response.json()
    isTaskCompleted = ['validating', 'completed', 'failed', 'cancelled'].includes(task.status)
}

task = tela.completions.create(
    application_id=os.getenv('TELA_APPLICATION_ID'),
    variables={
        "document": tela.create_file("https://example.com/document.pdf")
    }
)

task_id = task.id
is_task_completed = False

while not is_task_completed:
    time.sleep(2)
    response = requests.get(
        f'https://api.tela.com/task/{task_id}',
        headers={'Authorization': f'Bearer {os.getenv("TELA_API_KEY")}'},
    )
    task = response.json()
    is_task_completed = task['status'] in ['validating', 'completed', 'failed', 'cancelled']

Utilizando uma webhook URL

Você pode passar uma webhook_url na sua chamada de API. Assim, o endpoint informado recebe uma requisição POST quando a execução da tarefa termina.

Estrutura da Resposta do Webhook

Quando uma tarefa é concluída, o seu endpoint de webhook recebe uma requisição POST com a seguinte estrutura:

{
  "id": "b83b1558-de5b-4e45-b517-7bececbdd154",
  "status": "succeeded",
  "input_content": {
    "variables": {
      "document": {
        "file_url": "https://example.com/document.pdf"
      }
    },
    "messages": []
  },
  "output_content": {
    "role": "assistant",
    "structured_content": false,
    "content": {
      "fileSummary": "Este documento contém relatórios financeiros trimestrais mostrando um aumento de 15% na receita em comparação com o último trimestre, com destaques em melhorias de eficiência operacional e expansão de mercado na região APAC."
    }
  },
  "raw_input": {
    "application_id": "95cec438-6080-44fe-8275-28b16bd40178",
    "variables": {
      "document": {
        "file_url": "https://example.com/document.pdf"
      }
    },
    "webhook_url": "https://example.com/webhook"
  },
  "raw_output": {
    "fileSummary": "Este documento contém relatórios financeiros trimestrais mostrando um aumento de 15% na receita em comparação com o último trimestre, com destaques em melhorias de eficiência operacional e expansão de mercado na região APAC."
  },
  "compatibility_date": "2024-10-14",
  "prompt_version_id": "76065caa-c519-441a-8fe2-cc43e29664ab",
  "prompt_application_id": "95cec438-6080-44fe-8275-28b16bd40178",
  "workspace_id": "3f55cfd9-4427-4887-a181-d9ad39967802",
  "created_at": "2024-10-14T19:00:53.664Z",
  "updated_at": "2024-10-14T19:01:15.892Z"
}

Campos principais na resposta do webhook:

status: Pode ser “created”, “running”, “succeeded” ou “failed”
input_content: Contém as variáveis e mensagens enviadas na requisição
output_content: Contém a saída estruturada do seu Canvas, conforme o Formato de Saída definido
raw_output: Os dados de saída brutos, no formato definido pelo Formato de Saída do seu Canvas

const task = await tela.completions.create<{ document: TelaFile }, { fileSummary: string }>({
    applicationId: process.env.TELA_APPLICATION_ID,
    variables: {
        document: tela.createFile('https://example.com/document.pdf')
    },
    webhook_url: "https://example.com/webhook"
})

const task = await tela.completions.create({
    applicationId: process.env.TELA_APPLICATION_ID,
    variables: {
        document: tela.createFile('https://example.com/document.pdf')
    },
    webhook_url: "https://example.com/webhook"
})

task = tela.completions.create(
    application_id=os.getenv('TELA_APPLICATION_ID'),
    variables={
        "document": tela.create_file("https://example.com/document.pdf")
    }
    webhook_url="https://example.com/webhook"
)

curl -XPOST https://api.tela.com/v2/chat/completions \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer $TELA_API_KEY' \
    -d '{
        "application_id": "'$TELA_APPLICATION_ID'",
        "variables": {
            "document": {
                "file_url": "https://example.com/document.pdf"
            }
        },
        "webhook_url": "https://example.com/webhook"
    }'

Listando tarefas

Para listar as tarefas de um App, envie uma requisição GET para o endpoint /task. Ele aceita alguns parâmetros opcionais para filtrar e paginar os resultados:

Parâmetros de paginação

limit: Número de resultados por resposta (padrão: 10, intervalo: 1-100)
offset: Posição inicial dos resultados (padrão: 0)

Parâmetros de filtro

status: Array de status de tarefas (opções: “created”, “running”, “validating”, “completed”, “failed”)
since: Data inicial para filtrar as tarefas (formato: timestamp ou ISO 8601)
until: Data final para filtrar as tarefas (formato: timestamp ou ISO 8601)
approvedBy: Email do usuário que aprovou a tarefa
revisionProcess: Tipo de revisão recebida (opções: “approvedWithRevisions”, “approvedDirectly”)
promptApplicationId: ID do App em que a tarefa foi criada
promptVersionId: ID da versão do Canvas usada para criar a tarefa
ids: Array de IDs das tarefas a listar

Parâmetros de ordenação

orderBy: Campo de ordenação (opções: “name”, “reference”, “approvedAt”, “createdAt”, “updatedAt”, “id”, “status”, “approvedBy”, “createdBy”)
order: Sentido da ordenação (opções: “asc” ou “desc”)

Exemplo de requisição

Este exemplo lista 50 tarefas com o status completed criadas depois de 1º de novembro de 2024, em ordem crescente de nome:

const url = new URL('https://api.tela.com/task')
url.searchParams.append('limit', '50')
url.searchParams.append('promptApplicationId', '{YOUR_APPLICATION_ID}')
url.searchParams.append('status', JSON.stringify(['completed']))
url.searchParams.append('since', '2024-11-01T00:00:00Z')
url.searchParams.append('orderBy', 'name')
url.searchParams.append('order', 'asc')

const response = await fetch(url, {
    method: 'GET',
    headers: {
        'Authorization': `Bearer ${process.env.TELA_API_KEY}`,
        'Content-Type': 'application/json',
    },
});

const tasks = await response.json()

import requests
import os

response = requests.get(
    'https://api.tela.com/task',
    headers={
        'Authorization': f'Bearer {os.getenv("TELA_API_KEY")}',
        'Content-Type': 'application/json',
    },
    params={
        'limit': 50,
        'promptApplicationId': os.getenv('TELA_APPLICATION_ID'),
        'status': '["completed"]',
        'since': '2024-11-01T00:00:00Z',
        'orderBy': 'name',
        'order': 'asc',
    }
)

tasks = response.json()

curl -X GET "https://api.tela.com/task?limit=50&promptApplicationId=$TELA_APPLICATION_ID&status=%5B%22completed%22%5D&since=2024-11-01T00%3A00%3A00Z&orderBy=name&order=asc" \
  -H "Authorization: Bearer $TELA_API_KEY" \
  -H "Content-Type: application/json"

Primeiros passos

Construir

Testar

Operar

Integrar

Criando tarefas via API