Deployment de API

Faça o deploy do seu workflow como um endpoint REST que qualquer aplicação pode chamar diretamente. Suporta os modos de execução síncrono, com streaming e assíncrono.

Fazendo o deploy de um workflow

Abra seu workflow e clique em Deploy. A aba General abre primeiro e mostra o estado atual do deployment:

A aba General contém:

• Live Workflow — um minimapa somente leitura do snapshot do workflow atualmente em deploy
• Versions — uma tabela com todos os deployments que você publicou, mostrando o número da versão, quem fez o deploy e quando
• Deploy / Update / Undeploy — botões de ação no canto inferior direito

Clique em Deploy para publicar seu workflow pela primeira vez, ou em Update para enviar um novo snapshot depois de fazer alterações. O ponto verde ao lado de uma versão indica que ela é a versão live atual.

Depois do deploy, seu workflow fica disponível em:

POST https://agent-studio.seeyu.ai/api/v2/workflows/{workflow-id}/execute

Acompanhando as mudanças

Quando você modifica o workflow no builder depois do deploy, um selo Update deployment aparece na parte inferior da janela como lembrete de que sua versão live está desatualizada:

Você pode clicar no botão Update direto na barra de ferramentas do builder — não precisa abrir o modal Deploy toda vez.

Controle de versão

Cada vez que você faz um deploy ou uma atualização, uma nova versão é registrada na tabela Versions. Você pode gerenciar versões anteriores pelo menu de contexto (⋮) ao lado de qualquer linha:

Promote to live é útil para rollback — se um novo deployment apresentar problema, promova a versão anterior para restaurar instantaneamente o último estado que funcionava.

Fazendo chamadas de API

Vá para a aba API no modal Deploy para ver código pronto para uso nos três modos de execução:

O seletor de linguagem no topo permite alternar entre cURL, Python, JavaScript e TypeScript. Cada modo — síncrono, com streaming e assíncrono — tem seu próprio bloco de código, que você pode copiar diretamente. O código já vem preenchido com o ID do seu workflow e uma versão mascarada da sua API key.

Na parte inferior da aba, dois botões dão acesso rápido a configurações importantes:

• Edit API Info — define uma descrição e escolhe entre autenticação por API key ou acesso público
• Generate API Key — cria uma nova API key com escopo no seu workspace

Autenticação

Por padrão, os endpoints de API exigem uma API key enviada no header x-api-key. Gere chaves em Settings → Studio Keys ou pelo botão Generate API Key na aba API.

curl -X POST https://agent-studio.seeyu.ai/api/v2/workflows/{workflow-id}/execute \
  -H "Content-Type: application/json" \
  -H "x-api-key: $STUDIO_API_KEY" \
  -d '{ "input": { "message": "Hello" } }'

API Info e acesso público

Clique em Edit API Info para adicionar uma descrição e mudar o modo de acesso:

O campo Description documenta o que a API do workflow faz. Isso é útil para times, ou quando você expõe o workflow a ferramentas e serviços que mostram metadados de API.

Modos de execução

Síncrono

O modo padrão. Envie uma requisição e aguarde a resposta completa:

curl -X POST https://agent-studio.seeyu.ai/api/v2/workflows/{workflow-id}/execute \
  -H "Content-Type: application/json" \
  -H "x-api-key: $STUDIO_API_KEY" \
  -d '{ "input": { "message": "Summarize this article" } }'

import requests, os

response = requests.post(
    "https://agent-studio.seeyu.ai/api/v2/workflows/{workflow-id}/execute",
    headers={
        "Content-Type": "application/json",
        "x-api-key": os.environ["STUDIO_API_KEY"]
    },
    json={"input": {"message": "Summarize this article"}}
)
print(response.json())

const response = await fetch('https://agent-studio.seeyu.ai/api/v2/workflows/{workflow-id}/execute', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.STUDIO_API_KEY!
  },
  body: JSON.stringify({ input: { message: 'Summarize this article' } })
});
console.log(await response.json());

Streaming

Transmita a resposta token por token conforme ela é gerada. Adicione "stream": true ao corpo da requisição e especifique quais campos de saída dos blocos devem ser transmitidos usando selectedOutputs.

Use o dropdown Select outputs na aba API para escolher quais campos transmitir:

O dropdown agrupa as saídas disponíveis por bloco. A escolha mais comum é content de um bloco Agent, que transmite o texto gerado. Você pode selecionar campos de vários blocos simultaneamente.

Os valores de selectedOutputs no corpo da requisição seguem o formato blockName.field (por exemplo, agent_1.content).

curl -X POST https://agent-studio.seeyu.ai/api/v2/workflows/{workflow-id}/execute \
  -H "Content-Type: application/json" \
  -H "x-api-key: $STUDIO_API_KEY" \
  -d '{
    "input": { "prompt": "Write a long essay" },
    "stream": true,
    "selectedOutputs": ["agent_1.content"]
  }'

import requests, os

response = requests.post(
    "https://agent-studio.seeyu.ai/api/v2/workflows/{workflow-id}/execute",
    headers={
        "Content-Type": "application/json",
        "x-api-key": os.environ["STUDIO_API_KEY"]
    },
    json={
        "input": {"prompt": "Write a long essay"},
        "stream": True,
        "selectedOutputs": ["agent_1.content"]
    },
    stream=True
)
for line in response.iter_lines():
    if line:
        print(line.decode())

const response = await fetch('https://agent-studio.seeyu.ai/api/v2/workflows/{workflow-id}/execute', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.STUDIO_API_KEY!
  },
  body: JSON.stringify({
    input: { prompt: 'Write a long essay' },
    stream: true,
    selectedOutputs: ['agent_1.content']
  })
});

const reader = response.body!.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(decoder.decode(value));
}

Transmitindo o thinking e as chamadas de ferramentas do agente

Por padrão, uma execução com streaming carrega apenas o texto da resposta. Para receber também o raciocínio do bloco Agent e o ciclo de vida das suas chamadas de ferramentas, defina includeThinking / includeToolCalls:

curl -N -X POST https://agent-studio.seeyu.ai/api/v2/workflows/{workflow-id}/execute \
  -H "Content-Type: application/json" \
  -H "x-api-key: $STUDIO_API_KEY" \
  -H "X-Studio-Stream-Protocol: agent-events-v1" \
  -d '{
    "input": { "prompt": "Research this topic" },
    "stream": true,
    "selectedOutputs": ["agent_1.content"],
    "includeThinking": true,
    "includeToolCalls": true
  }'

O header X-Studio-Stream-Protocol é obrigatório sempre que uma das flags for definida — ele declara que seu cliente entende o framing de eventos de Agent. Definir uma flag sem ele retorna 400 em vez de ignorá-la em silêncio. O header também muda o texto da resposta para entrega ao vivo, token por token, que o chunk_reset pode retratar.

Ambas as flags vêm como false por padrão e o header é opcional por si só, então integrações existentes continuam recebendo exatamente os mesmos frames de hoje. Os frames de ferramenta carregam apenas o nome e o status; argumentos e resultados chegam no envelope final terminal. Nem todos os modelos expõem thinking. Veja Eventos de stream do Agent para os formatos dos frames, um cliente de referência e o suporte por provider.

Saídas muito grandes

As respostas de execução de workflow são limitadas pelos limites de requisição e resposta da plataforma. Quando uma saída interna, um campo de log, um campo transmitido ou um payload de status assíncrono contém um valor grande demais para ser embutido, o Studio pode substituir esse valor aninhado por uma referência versionada:

{
  "__simLargeValueRef": true,
  "version": 1,
  "id": "lv_abc123DEF456",
  "kind": "array",
  "size": 12582912,
  "key": "execution/workspace-id/workflow-id/exec_xyz/large-value-lv_abc123DEF456.json",
  "executionId": "exec_xyz",
  "preview": { "length": 25000 }
}

A chave __simLargeValueRef é histórica: ela antecede o nome atual do produto e é mantida como está porque renomeá-la quebraria todo cliente que já faz correspondência com ela. Uma renomeação com janela de compatibilidade é acompanhada separadamente.

O campo version faz parte do contrato externo da API. Trate a referência como um marcador opaco para um valor que não pôde ser embutido na resposta com segurança. id, key e executionId não são URLs de download; key aponta para um armazenamento no servidor com escopo na execução. Use selectedOutputs para pedir um campo aninhado menor, reduza os dados passados entre blocos ou retorne os dados de um bloco Response quando o seu workflow assumir intencionalmente o corpo da resposta HTTP. As saídas de arquivo priorizam metadados; peça .base64 apenas quando você precisar do conteúdo do arquivo embutido. Blocos Function em JavaScript podem ler arquivos grandes ou referências de valor explicitamente com os helpers studio.files e studio.values, respeitando os limites de memória.

Assíncrono

Para workflows longos, o modo assíncrono retorna um ID de execução imediatamente, então você não precisa manter a conexão aberta. Defina "async": true no corpo da requisição v2. A API retorna HTTP 202 com um ID de execução e uma URL de status v2. Consulte esse recurso de execução até que ela termine.

Para interromper uma requisição assíncrona individual antes do que a política do workspace determina, defina executionTimeoutSeconds como um inteiro de 1 a 604800 (sete dias) no corpo da requisição v2. O limite efetivo é o menor entre esse valor da requisição e o timeout de execução de workflow configurado na conta. Esse campo é rejeitado a menos que async seja true; o timeout do seu cliente HTTP continua sendo algo separado.

curl -X POST https://agent-studio.seeyu.ai/api/v2/workflows/{workflow-id}/execute \
  -H "Content-Type: application/json" \
  -H "x-api-key: $STUDIO_API_KEY" \
  -d '{ "input": { "task": "Process this large dataset" }, "async": true, "executionTimeoutSeconds": 3600 }'

{
  "data": {
    "runId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
    "statusUrl": "https://agent-studio.seeyu.ai/api/v2/workflows/{workflow-id}/runs/c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74"
  }
}

curl "https://agent-studio.seeyu.ai/api/v2/workflows/{workflow-id}/runs/{runId}?includeOutput=true" \
  -H "x-api-key: $STUDIO_API_KEY"

{
  "data": {
    "runId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
    "workflowId": "{workflow-id}",
    "status": "running",
    "startedAt": "2025-09-10T12:00:01.000Z",
    "endedAt": null,
    "durationMs": null,
    "output": null
  }
}

{
  "data": {
    "runId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
    "workflowId": "{workflow-id}",
    "status": "completed",
    "startedAt": "2025-09-10T12:00:01.000Z",
    "endedAt": "2025-09-10T12:00:05.000Z",
    "durationMs": 4000,
    "output": { "result": "..." }
  }
}

Valores de status de execução

Consulte a statusUrl da resposta inicial até que o status seja completed ou failed.

Limites de tempo de execução

Se uma execução exceder seu limite de tempo, ela é automaticamente marcada como failed. Uma requisição assíncrona à API pode usar executionTimeoutSeconds para encurtar a política da conta, mas nunca para estendê-la.

Retenção de execuções

Execuções concluídas e falhas são lidas dos logs de execução e seguem a política de retenção de logs de execução do workspace.

Limites de capacidade

Se a fila de execução estiver cheia, a API retorna 503:

{
  "error": "Service temporarily at capacity",
  "retryAfterSeconds": 10
}

Gerenciamento de API keys

Gere e gerencie API keys em Settings → Studio Keys:

• Crie novas chaves para aplicações ou ambientes diferentes
• Revogue chaves que não são mais necessárias
• As chaves têm escopo no seu workspace

Limites de requisições

As chamadas de API estão sujeitas a limites de requisições conforme o seu plano. Os detalhes dos limites são retornados nos headers da resposta (X-RateLimit-*) e no corpo da resposta. Use o modo assíncrono para cargas de alto volume ou de longa duração.

Para informações detalhadas sobre limites de requisições e sobre a API de logs/webhooks, veja API externa.