For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navegação principal
Theme

Sugestões

API de agentes

SDK de agentes

ChatKit

Painel da API
Experimente o ChatGPT

Automações agendadas

Agende tarefas para um agente ou deixe que ele agende suas próximas tarefas.

Use automações agendadas para iniciar sessões de agentes nos horários definidos por uma expressão cron. Você também pode habilitar a ferramenta automations para que seus agentes agendem tarefas enquanto trabalham.

  • Automatize sessões com um agendamento cron

    Use uma expressão cron e um fuso horário para iniciar novas sessões ou continuar uma sessão existente.

  • Permita que os agentes criem automações

    Adicione a ferramenta automations para que um agente possa agendar tarefas de acompanhamento na sessão atual.

  • Monitore as invocações de automações

    Cada invocação registra uma tentativa de enviar uma tarefa a uma sessão. Consulte o status da invocação e o ID da sessão.
Automatize sessões com um agendamento cron
import OpenAI from "openai";

const client = new OpenAI();
const automation = await client.beta.agents.automations.create({
  type: "periodic",
  name: "Daily session",
  expression: "0 10 * * *",
  timezone: "America/New_York",
  target: {
    type: "new_session",
    agent_id: "agt_123",
    environment: { type: "openai_hosted" },
    input: [
      {
        role: "user",
        content: [
          {
            type: "input_text",
            text: "Summarize the current status and next steps.",
          },
        ],
      },
    ],
  },
});
console.log(automation);

Recursos da API

  • Agentes

    /v1/agents

    Defina as instruções e as ferramentas para a tarefa.

  • Automações

    /v1/agents/automations

    Salve o horário de execução e a sessão que receberá a tarefa.

  • Invocações

    /v1/agents/automations/{automation_id}/invocations

    Veja quando a tarefa foi enviada e qual sessão a recebeu.

  • Sessões

    /v1/agents/sessions

    Execute a tarefa com o histórico da conversa e as ferramentas da sessão.

  • Eventos da sessão

    /v1/agents/sessions/{session_id}/events

    Acompanhe o progresso e obtenha o resultado.

Casos de uso

Como funciona

Uma automação é um agendamento salvo para executar tarefas de um agente. A API de Agentes armazena o agendamento e envia cada tarefa à sessão de destino.

  1. Defina a tarefa. Escolha quando ela deve ser executada e se cada execução inicia uma nova sessão ou dá continuidade a uma sessão existente.
  2. Envie a tarefa. Cada execução cria uma invocação, que registra a tentativa de enviar a tarefa à sessão de destino. Se a sessão estiver ocupada, a tarefa aguarda.
  3. Acompanhe o resultado. O agente usa as ferramentas e o contexto da sessão. Acompanhe os eventos da sessão para monitorar o progresso e obter os resultados. O recebimento da tarefa pela sessão não significa que o agente concluiu o trabalho.

Seu aplicativo pode criar, atualizar, pausar ou excluir agendamentos pela API. Com a ferramenta automations habilitada, o agente também pode agendar a próxima verificação na sessão atual.

Escolha a sessão e o agendamento

Escolha o destino de acordo com a necessidade de consultar o histórico da conversa.

Destino Quando usar Configuração obrigatória
new_session Tarefas independentes, como uma análise mensal de gastos. Um agente, um ambiente e mensagens iniciais em target.input.
existing_session Tarefas de acompanhamento que dependem dos resultados anteriores da sessão. Um ID de sessão e o texto do lembrete em target.instructions.

Escolha quando executar a tarefa, independentemente do destino.

Tipo Campos de agendamento Exemplo
periodic expression e timezone Todos os dias às 10h no fuso America/New_York.
once run_at Uma única verificação em um horário futuro especificado como um timestamp Unix em segundos.

Os dois tipos de agendamento funcionam com qualquer um dos destinos. Ao criar uma automação, a API a salva com o status active. A tarefa não é executada imediatamente. A primeira execução de uma automação periódica fica agendada para o próximo horário que corresponda à expressão.

Agende sugestões diárias

Antes de criar a automação, crie um agente com as instruções e ferramentas necessárias para a tarefa, incluindo acesso à agenda, às tarefas e às mensagens do usuário. Consulte Reutilize um agente em várias sessões.

Os SDKs incluem o cabeçalho OpenAI-Beta: agents=v1. Inclua esse cabeçalho ao chamar a API com cURL.

O exemplo a seguir cria uma automação para iniciar uma nova sessão todos os dias às 10h no horário de Nova York.

Agende sugestões diárias
from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.create(
    type="periodic",
    name="Daily suggestions",
    expression="0 10 * * *",
    timezone="America/New_York",
    target={
        "type": "new_session",
        "agent_id": "agt_123",
        "environment": {"type": "openai_hosted"},
        "input": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": (
                            "Review my calendar, tasks, and recent messages for today. "
                            "Suggest the most useful actions I could take today, "
                            "with a short reason for each."
                        ),
                    }
                ],
            }
        ],
    },
)
print(automation.to_json())

Salve o id da automação retornado pela API para consultar ou gerenciar o agendamento depois. Cada invocação inicia uma nova conversa. A configuração de ambiente acima provisiona um sandbox hospedado pela OpenAI para essa sessão.

Você pode informar a configuração do agente diretamente em target.agent em vez de usar um target.agent_id salvo. Informe exatamente um desses campos. Coloque as mensagens iniciais em target.input, e não no nível superior da requisição. Inclua pelo menos uma mensagem com texto não vazio ou uma URL de imagem.

Analise os gastos de cada mês

Você pode usar a mesma abordagem para analisar os gastos mensais. Dê ao agente salvo acesso aos registros financeiros do usuário e agende uma nova sessão para as 9h do primeiro dia de cada mês.

Agende uma análise mensal de gastos
from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.create(
    type="periodic",
    name="Monthly spending review",
    expression="0 9 1 * *",
    timezone="America/New_York",
    target={
        "type": "new_session",
        "agent_id": "agt_123",
        "environment": {"type": "openai_hosted"},
        "input": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": (
                            "Review my spending for the previous month. Flag unused "
                            "subscriptions, price increases, and other potential "
                            "savings for me to review."
                        ),
                    }
                ],
            }
        ],
    },
)
print(automation.to_json())

Defina horários recorrentes

Use uma expressão cron de cinco campos e informe o nome do fuso horário.

Expressão Agendamento
0 10 * * * Todos os dias às 10h
0 */2 * * * A cada duas horas
0 9 1 * * No primeiro dia de cada mês às 9h
0 9 * * MON-FRI De segunda a sexta-feira às 9h

O fuso horário determina como a expressão é interpretada. Use UTC para agendar em UTC ou um fuso horário da IANA, como America/New_York, para agendar no horário local. Não inclua run_at em uma automação periódica.

Um agendamento cron segue a hora local do fuso selecionado. Por exemplo, 0 */3 * * * agenda execuções à meia-noite, às 3h, às 6h e assim por diante, a cada três horas. O intervalo não é contado a partir da criação da automação.

O agendamento define o horário previsto. A API de Agentes acrescenta um pequeno atraso aleatório às execuções recorrentes para distribuir a carga. A tarefa pode esperar mais tempo se a sessão de destino estiver ocupada.

Continue uma sessão existente

Use uma sessão existente quando o agente precisar de resultados anteriores, mensagens ou trabalho salvo. Por exemplo, uma sessão usada para planejar um jantar pode guardar as preferências de restaurantes e os resultados das verificações de disponibilidade anteriores.

O exemplo a seguir verifica a disponibilidade de mesas em restaurantes a cada duas horas nessa sessão.

Verifique a disponibilidade de mesas em restaurantes
from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.create(
    type="periodic",
    name="Check restaurant reservations",
    expression="0 */2 * * *",
    timezone="America/New_York",
    target={
        "type": "existing_session",
        "session_id": "sess_123",
        "instructions": (
            "Check restaurant availability for our dinner plans. "
            "Compare with earlier checks and report newly available tables."
        ),
    },
)
print(automation.to_json())

Cada invocação entrega as instruções salvas à mesma sessão como uma notificação da automação, usando a configuração atual do agente e o estado salvo da sessão. Essa notificação é distinta de uma nova mensagem do usuário.

Se a sessão estiver ocupada, a entrega aguarda até que ela fique disponível. Uma execução agendada não interrompe o turno ativo nem fornece o resultado de uma ferramenta ou uma aprovação que esteja faltando. Seu aplicativo ainda precisa tratar as ações obrigatórias.

Agende uma única verificação

Para uma única tarefa de acompanhamento, use type: "once" com run_at. O valor deve ser um timestamp Unix inteiro em segundos que represente um horário futuro. Não inclua expression nem timezone.

Agende uma verificação para 1º de janeiro de 2027 às 9h UTC.

Agende uma única execução do agente
from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.create(
    type="once",
    name="Check restaurant reply",
    run_at=1798794000,
    target={
        "type": "existing_session",
        "session_id": "sess_123",
        "instructions": (
            "Check whether the restaurant replied about our booking. "
            "Summarize any changes to the dinner plans."
        ),
    },
)
print(automation.to_json())

Depois que um agendamento de execução única é concluído, não há mais execuções agendadas. Você ainda pode invocar a automação manualmente ou criar outra automação para agendar uma nova tarefa de acompanhamento.

Permita que o agente agende tarefas de acompanhamento

Adicione automations às ferramentas do agente para que ele possa agendar tarefas solicitadas pelo usuário. Este exemplo também habilita subagentes para que o agente principal possa delegar cada tarefa agendada e guardar um breve resumo do resultado.

Permita que os agentes agendem tarefas
from openai import OpenAI

client = OpenAI()
session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": (
            "Use automations to schedule tasks requested by the user. "
            "Delegate each scheduled task to a subagent and ask for a concise result. "
            "Keep the goal, schedule, and useful summaries in the main session. "
            "Adjust or stop schedules when the user asks."
        ),
        "multi_agent": {"enabled": True},
        "tools": [{"type": "automations"}],
    },
    environment={"type": "openai_hosted"},
    input=(
        "Every day at 10 AM in America/New_York, review the goals we discuss here "
        "and suggest the next actions I could take."
    ),
)
print(session.id)

Com essa ferramenta, o agente pode criar, listar, consultar, atualizar, pausar, retomar e excluir suas próprias automações. A API de Agentes define a sessão atual como destino. O agente pode criar execuções únicas ou periódicas, mas não pode usar essas ferramentas para iniciar uma nova sessão ou gerenciar as automações de outra sessão.

As ferramentas só podem acessar automações criadas pelo agente na sessão atual. Seu aplicativo pode gerenciar essas automações pela API, junto com as que ele mesmo criou. A API de Agentes registra quem criou a automação em created_by. Não envie esse campo na requisição de criação.

Por padrão, a ferramenta não faz parte da configuração. Seu aplicativo pode agendar tarefas sem habilitá-la. Remover a ferramenta da configuração do agente não exclui os agendamentos salvos. Quando necessário, pause ou exclua esses agendamentos pela API.

Mantenha as tarefas repetitivas fora do contexto principal

Para objetivos contínuos, habilite a orquestração de múltiplos agentes com agent.multi_agent.enabled: true. Peça ao agente principal que guarde o objetivo e o agendamento, delegue cada tarefa a um subagente e registre um breve resumo do resultado. Assim, a saída detalhada das ferramentas usadas nas verificações repetidas fica fora da janela de contexto da sessão principal.

Por exemplo, inclua o seguinte nas instruções do agente principal:

Delegue cada tarefa agendada a um subagente. Informe o objetivo e os resultados anteriores relevantes e peça uma resposta concisa. Analise o resultado, guarde um resumo do que for útil e decida se deve manter, alterar ou encerrar o agendamento.

A ferramenta automations gerencia os agendamentos. Mantenha as demais ferramentas e o acesso aos dados de que o agente precisa para executar as tarefas agendadas.

Agende pelo aplicativo o acompanhamento de novos usuários

Seu aplicativo também pode criar agendamentos em resposta aos próprios eventos. Por exemplo, quando um usuário se cadastrar, inicie uma sessão de integração e agende a primeira tarefa de acompanhamento para 48 horas depois.

Agende uma tarefa de acompanhamento da integração
import time

from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.create(
    type="once",
    name="Onboarding follow-up",
    run_at=int(time.time()) + 48 * 60 * 60,
    target={
        "type": "existing_session",
        "session_id": "sess_123",
        "instructions": (
            "Review onboarding progress and send the next onboarding message "
            "if the user has not completed onboarding."
        ),
    },
)
print(automation.to_json())

Sempre que uma tarefa de acompanhamento for concluída, seu aplicativo poderá agendar outra para 48 horas depois. Encerre o acompanhamento quando a integração terminar ou o usuário optar por não continuar. Exclua qualquer tarefa de acompanhamento pendente. Use agendamentos de execução única para esse intervalo. Uma expressão cron baseada no dia do mês não mantém um intervalo de 48 horas na virada do mês.

O agente de integração precisa ter acesso ao progresso do usuário na integração e às ferramentas de mensagens do aplicativo. Criar a automação agenda a tarefa. A mensagem não é enviada imediatamente.

Teste uma execução e verifique a entrega

Para testar uma automação salva imediatamente, envie POST /v1/agents/automations/auto_123/invocations sem corpo na requisição. Uma invocação manual não altera o agendamento salvo nem consome a execução prevista em um agendamento de execução única. Ela também funciona enquanto o agendamento está pausado.

Salve o ID da invocação retornado pela API. Consulte a invocação com GET /v1/agents/automations/auto_123/invocations/ainv_123 ou liste o histórico de entregas com GET /v1/agents/automations/auto_123/invocations.

Para ter uma visão geral das execuções anteriores, liste as invocações da automação.

Monitore as invocações de automações
import OpenAI from "openai";

const client = new OpenAI();
for await (const invocation of client.beta.agents.automations.invocations.list(
  "auto_123"
)) {
  console.log(invocation.id, invocation.status, invocation.session_id);
}

O histórico contém as invocações já criadas, mas não inclui todas as ocorrências futuras. Verifique os seguintes campos:

Campo O que verificar
status O valor inicial é queued e muda para completed quando a entrega é bem-sucedida.
session_id Identifica a sessão a acompanhar após a entrega. Pode ser null antes que uma sessão esteja disponível.
source.type O valor é manual para uma invocação manual ou automation para uma execução agendada.
scheduled_at O horário previsto no agendamento ou null para uma invocação manual.

Uma entrega concluída não significa que o agente terminou a tarefa. Para uma nova sessão, significa que ela aceitou os dados de entrada iniciais. Para uma sessão existente, significa que ela aceitou a notificação e a solicitação para iniciar a tarefa.

Use o session_id da invocação para acompanhar os eventos da sessão e verificar o resultado do turno.

A automação agenda a tarefa. Seu aplicativo exibe a saída da sessão e envia as notificações ao usuário.

Altere ou encerre um agendamento

Consulte uma automação com GET /v1/agents/automations/auto_123. Liste as automações do projeto com GET /v1/agents/automations. Adicione session_id=sess_123 para encontrar automações que tenham essa sessão existente como destino.

Atualize a expressão cron para mudar o horário de uma verificação recorrente para as 11h.

Altere um agendamento
from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.update(
    automation_id="auto_123",
    expression="0 11 * * *",
)
print(automation.to_json())

Os campos omitidos mantêm seus valores. Se você informar target, o novo valor substituirá todo o destino. Inclua todos os campos obrigatórios e mantenha o tipo do destino. Atualize o texto do lembrete em target.instructions ou as mensagens iniciais em target.input. Uma automação criada por um agente deve manter como destino a sessão em que foi criada.

Faça as alterações antes do próximo horário agendado. As atualizações se aplicam às invocações futuras. Uma invocação que já está na fila mantém o destino e os dados de entrada salvos no momento de sua criação.

Use as seguintes operações sem corpo na requisição:

Objetivo Operação Efeito
Pausar as tarefas agendadas. POST /v1/agents/automations/auto_123/pause Suspende as entregas agendadas pendentes. A invocação manual continua disponível.
Retomar as tarefas agendadas. POST /v1/agents/automations/auto_123/resume Reativa o agendamento salvo.
Remover o agendamento. DELETE /v1/agents/automations/auto_123 Impede novas invocações agendadas e manuais.

Pausar ou excluir uma automação não interrompe tarefas que uma sessão já aceitou nem exclui a sessão. Uma entrega em andamento ainda pode chegar à sessão de destino. Para interromper o trabalho atual, cancele o turno ativo.

Se o horário agendado de uma automação de execução única passar enquanto ela estiver pausada, defina um novo horário futuro em run_at antes de retomá-la. Uma automação de execução única já concluída não pode ser pausada nem retomada. Crie outra automação para agendar uma nova tarefa de acompanhamento.