Setup com agente

Este guia foi escrito para agentes de código. Um usuário da Stac delegou a você a configuração de uma infraestrutura (também chamada de stack) e lhe entregou um token de setup. Use a Setup API abaixo para criar chaves de API, configurar o comportamento, subir arquivos de conhecimento, dar prompts próprios às chaves e enviar uma requisição de teste. O usuário acompanha o seu progresso ao vivo no dashboard da Stac.

Autenticação#

Toda chamada envia o token de setup como bearer token. O comando do usuário o exporta como STAC_SETUP_TOKEN. Os exemplos abaixo também usam STAC_SETUP_API para a URL da Setup API que veio no seu prompt:

export STAC_SETUP_API="https://trystac.com/api/setup/v1"

curl "$STAC_SETUP_API/stack" \
  -H "Authorization: Bearer $STAC_SETUP_TOKEN"

• Base URL: https://trystac.com/api/setup/v1 (o prompt que você recebeu traz a URL exata). Ela não é o gateway: https://api.trystac.com/v1 é para onde a aplicação do usuário envia as requisições de modelo com uma chave de API.
• O token vale para uma única stack e só para as tarefas que o usuário selecionou. Ele expira uma hora depois de emitido, é revogado assim que todas as tarefas delegadas são marcadas como concluídas, e o usuário pode revogá-lo a qualquer momento.
• Os erros vêm em JSON { "error": "...", "code": "..." }. Se receber 401 com token_expired ou token_revoked antes de terminar, pare e peça um novo token ao usuário. Se receber 403 com task_not_allowed, pule essa tarefa: o usuário não a delegou.

Tarefas e progresso#

O usuário escolhe um subconjunto de cinco tarefas. Execute-as nesta ordem:

Cada ação abaixo registra o progresso automaticamente como running. Quando terminar uma tarefa, marque-a como concluída para que o dashboard a dê como feita:

curl -X POST "$STAC_SETUP_API/activity" \
  -H "Authorization: Bearer $STAC_SETUP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "task": "create_api_keys", "status": "done", "message": "Created web and worker keys" }'

status é running, done ou failed; message é opcional (até 500 caracteres) e deve ser curta. A send_test_request é marcada como concluída automaticamente quando o teste dá certo.

Só marque uma tarefa como concluída quando tiver terminado tudo dela. Quando a última tarefa delegada é marcada como concluída, o token é revogado: qualquer chamada depois disso devolve 401 token_revoked. Isso é esperado, não é um erro. Leia tudo o que precisar para o seu resumo antes de concluir a última tarefa.

Leia a stack#

GET /stack devolve tudo o que você precisa antes de agir: a categoria da stack (llm para texto, image para geração de imagens), o comportamento atual, as chaves existentes (nunca os segredos delas), os arquivos de conhecimento, as tarefas que este token permite e os limites.

{
  "stack": { "id": "…", "name": "My stack", "plan": "Pro", "category": "llm" },
  "token": { "tasks": ["create_api_keys", "configure_behavior"], "expires_at": "…", "keys_created": 0 },
  "behavior": { "system_prompt": null, "temperature": null, "top_p": null, "max_tokens": null, "presence_penalty": null },
  "keys": [{ "id": "…", "name": "prod", "prefix": "a1b2c3d4", "status": "active", "has_custom_prompt": false, "reasoning_effort": null, "created_by_this_token": false }],
  "knowledge_files": [{ "name": "faq.md", "chunks": 12 }],
  "limits": { "keys_per_token": 10, "key_system_prompt_max_length": 1000, "stack_system_prompt_max_length": 1000, "knowledge_max_files": 20, "knowledge_max_bytes": 10485760, "knowledge_extensions": [".txt", ".md", ".pdf"] }
}

As chaves que já existiam são chaves de produção: não mexa nelas.

Crie chaves de API#

POST /keys · tarefa create_api_keys

curl -X POST "$STAC_SETUP_API/keys" \
  -H "Authorization: Bearer $STAC_SETUP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "web-production" }'

A resposta (201) traz id, name, prefix e key. A key em texto puro só é devolvida uma vez. Coloque-a no arquivo de env local da aplicação (por exemplo, STAC_API_KEY em .env.local), confira se esse arquivo está no git-ignore e nunca a commite nem a imprima por inteiro. Guarde o id: os outros endpoints usam ele. Um token pode criar até 10 chaves; as chaves nunca expiram.

Configure o comportamento#

PATCH /behavior · tarefa configure_behavior — envie só os campos que você quer mudar.

curl -X PATCH "$STAC_SETUP_API/behavior" \
  -H "Authorization: Bearer $STAC_SETUP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "system_prompt": "You are the support assistant for Acme…", "temperature": 0.3, "reasoning_effort": "low" }'

Enviar um campo de texto para uma stack de imagem (ou o contrário) devolve 400 not_applicable.

Suba arquivos de conhecimento#

POST /knowledge · tarefa upload_knowledge — formulário multipart com um campo file. .txt, .md ou .pdf com texto embutido, até 10 MB cada, dentro do limite de arquivos do plano. Subir de novo um arquivo com o mesmo nome faz a reindexação dele.

curl -X POST "$STAC_SETUP_API/knowledge" \
  -H "Authorization: Bearer $STAC_SETUP_TOKEN" \
  -F "file=@docs/faq.md"

A resposta (201) traz o name armazenado e o número de chunks indexados. Um arquivo recusado devolve 400 knowledge_rejected com o motivo (por exemplo, um PDF escaneado sem texto). Uma falha temporária na indexação devolve 502 knowledge_failed: envie o mesmo arquivo de novo.

Vincule prompts às chaves#

PATCH /keys/:id · tarefa attach_key_prompts — só para chaves criadas com este token. Envie só os campos que você quer mudar.

curl -X PATCH "$STAC_SETUP_API/keys/$KEY_ID" \
  -H "Authorization: Bearer $STAC_SETUP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "system_prompt": "You answer questions from the internal admin panel…" }'

Envie uma requisição de teste#

POST /test · tarefa send_test_request — a Stac envia uma requisição real pelo gateway com a chave, então você não precisa da chave em texto puro aqui.

curl -X POST "$STAC_SETUP_API/test" \
  -H "Authorization: Bearer $STAC_SETUP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "key_id": "'"$KEY_ID"'", "message": "Say hello in one sentence." }'

Os dois campos são opcionais: sem key_id, é usada a chave mais recente criada com este token. Só dá para testar chaves criadas com este token (senão, 403 key_not_created_by_token). Stacks de texto recebem um chat completion; stacks de imagem geram uma imagem. A resposta traz ok, o status do gateway, latency_ms, request_id e um trecho da resposta em reply (ou o número de images).

Conclua#

Quando todas as tarefas estiverem concluídas, conte ao usuário o que você configurou: os nomes das chaves (não as chaves), onde você as guardou, o prompt que escreveu e os arquivos que subiu. Ele pode revisar e mudar tudo no dashboard.