Astra profundo · Capítulo 26 de 31 · 30 min
Projetar uma integração pequena com a Responses API
Você sai com o contrato de uma integração que transforma o briefing Aurora em uma proposta estruturada.
Este capítulo faz parte do curso gratuito Astra profundo.
O Estúdio Aurora, caso fictício, quer reaproveitar o mesmo procedimento sempre que receber um pedido de oficina. Em vez de começar uma conversa manual para cada briefing, a equipe pode enviar informações a uma integração e receber uma proposta organizada. Você vai desenhar esse contrato com a Responses API: entrada, instrução, formato de saída e critério de aceitação.
Uma API permite que um programa faça uma solicitação a outro sistema por um formato definido. No nosso exercício, o programa recebe tema, público e duração desejada, envia esses dados ao Astra e obtém um rascunho. A aplicação decide onde guardar e mostrar o resultado. Essa separação permite substituir a interface de entrada sem reescrever o procedimento de elaboração da proposta.
Entrada, ferramenta e resposta
O aplicativo executa a ferramenta e devolve seu resultado ao modelo.
Transcrição
0:00O aplicativo envia contexto e pedido para a Responses API. A entrada declara o artefato esperado e os critérios da entrega.
0:07O modelo solicita uma ferramenta. O aplicativo executa a operação e associa o resultado ao identificador da chamada.
0:14O resultado volta para a conversa e compõe a resposta. O aplicativo apresenta o artefato e os dados que o usuário precisa conferir.
Contrato da proposta de oficina
| Parte | Conteúdo do exemplo | Critério de pronto |
|---|---|---|
| Entrada | Tema, público e duração | Campos compreensíveis e separados |
| Instrução | Elaborar proposta conforme briefing | Escolhas permitidas explícitas |
| Saída | Objetivo, sequência, materiais e pendências | Campos utilizáveis pela aplicação |
| Verificação | Comparar resultado ao pedido | Proposta revisada e registrada |
Defina também a saída esperada. A proposta precisa ter título, objetivo, sequência de atividades, materiais e perguntas pendentes. Quando outro programa consumir essa resposta, um formato estruturado facilita localizar os campos. A [documentação de saídas estruturadas](https://developers.openai.com/api/docs/guides/structured-outputs) explica o uso de schemas. O schema organiza a forma; o conteúdo ainda precisa cumprir o briefing.
Aprofunde as decisões desta aula
Como começar uma integração com a Responses API?
A [orientação atual da OpenAI](https://developers.openai.com/api/docs/guides/latest-model) indica gpt-6-astra na Responses API e exige Responses para chamadas de ferramentas com Astra. Comece pela integração mais curta que resolva uma tarefa do Aurora. Um fluxo que produz uma proposta textual já permite avaliar conteúdo e formato antes de conectar agenda, arquivos e publicação. Defina a entrada com significado. Tema pode ser fotografia noturna, público pode ser iniciantes e duração pode ser um encontro. Separe dados fornecidos de escolhas que o modelo pode sugerir. No exemplo, o Astra pode propor a ordem das atividades e os materiais, enquanto o nome do evento e a duração solicitada permanecem como referência fixa.
Como revisar o conteúdo e escolher o esforço de raciocínio?
Resolva um exemplo antes de generalizar. Envie o pedido fictício de uma oficina de fotografia noturna para iniciantes. Confira se a sequência começa por preparação e termina com uma atividade aplicável, se os materiais combinam com o encontro e se a proposta evita pressupor informações que o briefing deixou abertas. Essas perguntas viram critérios de aceitação da integração. Comece em medium para o rascunho da oficina e guarde a primeira saída. Depois compare o mesmo pedido com outro esforço, mantendo materiais e critérios. A escolha deve mostrar se o raciocínio adicional melhora a proposta. Registre identificador do pedido, versão da instrução, entrada e estado da execução. Esses dados permitem reproduzir uma proposta aprovada e atualizar o procedimento. Assinatura do aplicativo e cobrança da API são superfícies distintas. Entregue o contrato, um briefing e uma saída revisada. A equipe do Aurora terá um comportamento concreto para implementar e critérios para avaliar cada proposta.
Com o SDK Python da OpenAI instalado e credenciais configuradas no ambiente, esta chamada produz um rascunho textual. A [referência de Responses](https://developers.openai.com/api/docs/guides/migrate-to-responses) documenta o formato. O kit baixável oferece uma alternativa com a biblioteca padrão do Python.
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-6-astra",
reasoning={"effort": "medium"},
instructions="Prepare uma proposta de oficina para o Aurora.",
input="Tema: fotografia noturna. Público: iniciantes. Duração: um encontro."
)
print(response.output_text)Faça agora: desenhe a integração
A prática de 30 minutos pode ser concluída com exemplos locais antes de uma chamada de API.
Passo 1: Escreva o contrato
Defina campos de entrada e os elementos obrigatórios da proposta.
Deu certo quando: Outra pessoa consegue preparar um pedido.
Passo 2: Resolva um briefing
Use fotografia noturna para iniciantes e produza uma saída de referência.
Deu certo quando: A proposta atende ao tema e ao público.
Passo 3: Defina a chamada
Consulte a documentação vigente para o cliente usado e escolha modelo, esforço e formato.
Deu certo quando: Os parâmetros correspondem à API atual.
Passo 4: Registre a aceitação
Compare a resposta com a referência e documente os critérios de qualidade.
Deu certo quando: A integração tem um resultado verificável.
No fim você tem: Contrato de integração, exemplo de briefing e proposta estruturada revisada.
A integração começa por um contrato de entrada e saída. Responses organiza o fluxo de trabalho com Astra. Um exemplo revisado orienta implementação e avaliação.
Seu caderno neste capítulo
Abrir o caderno completoSelecione um trecho do capítulo para destacar ou anotar. Nos vídeos e áudios, use Anotar este momento. No teclado, selecione com Shift e as setas e use Alt+Shift+D para destacar ou Alt+Shift+N para anotar.
Salvo neste navegador. Entre na sua conta para levar o caderno a outros aparelhos.
Entre na sua conta para compartilhar o que aprendeu e convidar alguém para estudar com você.
Conexões deste capítulo
Veja o que estudar antes e para onde seguir depois, explore os conceitos e compare abordagens em outros cursos. Sugestões marcadas como “sugerido pelo grafo” vêm dos assuntos em comum, não do índice do curso.
Estude antes
- CursoEscrever bem com IAsugerido pelo grafoAs primeiras aulas do Astra pedem um briefing com referências e dirigem cada iteração por texto. O curso de escrita ensina a decidir o que pedir, dar contexto e conferir a saída, que é a base dessas aulas. Ordem decidida quando o Astra ganhou uma página por aula (Etapa 4, wave 3), para que as 31 aulas mostrem o que estudar antes.
- CursoNode.js: JavaScript no Servidorsugerido pelo grafo4 capítulos de “Astra profundo” usam conceitos apresentados em “Node.js: JavaScript no Servidor”.
Conceitos deste capítulo
O mesmo assunto em outros cursos
- Software e IA para executivosEscolher o formato da integração olhando quem vai consumirExaminar conexões de Escolher o formato da integração olhando quem vai consumir
- SEO e GEO para Personal BrandsIA Generativa para Produção e MonitoramentoExaminar conexões de IA Generativa para Produção e Monitoramento
- Escrever bem com IATrocar de ferramenta sem perder o métodoExaminar conexões de Trocar de ferramenta sem perder o método
- Saúde Mental para Autistas em IAQual assistente aguenta ser prótese de função executivaExaminar conexões de Qual assistente aguenta ser prótese de função executiva
Leve uma ideia para a prática
Escolha uma atividade no painel e volte a este curso quando quiser.
Atividades e evolução ficam reunidas no painel da sua conta.