Schedule an agent

Execution reference: This page specifies the tool protocol for automation agents. For instructions to follow in Studio, use the user guide.

Create or update a schedule for a project agent. Check existing schedules first and verify the saved target, timing and task.

Agent-facing flow

  1. Inspect existing agents with veryfront__list_agents and schedules with veryfront__list_schedules, without a status filter. Follow every page_info.next cursor so paused or otherwise inactive schedules cannot be missed.
  2. If the target agent does not exist, follow Create an agent first. Complete avatar assignment and verify the saved agent with veryfront__get_agent_source, then veryfront__get_agent_capabilities, using the same project and source target. Stop if either readback fails. Otherwise continue scheduling in the same run.
  3. Collect only missing schedule requirements. Required fields are the agent ID, schedule expression, timezone, and run prompt.
  4. Reuse a matching active schedule. If the user requested different settings, change them with veryfront__update_schedule using the existing schedule ID.
  5. If a matching inactive schedule exists, inspect it and resume or repair it only when the user has requested that action. Do not create a replacement just because the existing schedule is paused or deleting. Create a schedule with veryfront__create_schedule only when no matching schedule exists.
  6. Verify the schedule creation result or read the schedule back with veryfront__list_schedules.

Guardrails

  • Use conversation_mode: "create_new" for recurring autonomous agent schedules unless the user explicitly asks to reuse an existing conversation. See Conversation modes for what each mode gives up.
  • Do not create duplicate schedules for the same target agent and cadence.
  • Do not emit progress-only assistant text between veryfront__create_agent and veryfront__create_schedule. Complete the avatar assignment and both agent readbacks first. Once they succeed, call veryfront__create_schedule unless no schedule creation surface exists. Never activate a schedule after a failed agent verification.

Schedule target

Agent schedules use a typed schedule target. The target is the agent itself, not a wrapper task or workflow:

json
{
  "kind": "agent",
  "id": "<agent-id>",
  "conversation_mode": "create_new"
}

conversation_mode and conversation_id are valid only for agent targets. Sending them on a task or workflow target returns a validation error.

Conversation modes

conversation_mode controls whether each occurrence has a conversation. All modes retain the run and its events, and all support delegation.

ModeEach occurrenceUse when
create_newOpens a fresh conversation, hidden from the chat list.Recommended for recurring autonomous schedules when each run needs its own message history.
noneCreates no conversation.The run and its events provide enough history.
existingAppends to conversation_id.One thread should accumulate occurrences. Requires conversation_id.

Use create_new to read a past occurrence as a conversation in Studio. Under none, inspect its run and events instead.

Source definitions use camelCase on the target and put the run prompt in agentMessage:

ts
export default schedule({
  id: "triage-new-cases",
  schedule: "*/10 * * * *",
  timezone: "Europe/Berlin",
  target: { kind: "agent", id: "case-triage", conversationMode: "create_new" },
  agentMessage: { prompt: "Triage every open case." },
});

Requires veryfront 0.1.1239 or later. Earlier versions reject conversationMode on the target and agentMessage, so the schedule file fails to load.

Tool selection

  • Use veryfront__list_agents before creating or choosing the target agent.
  • Use veryfront__list_schedules before veryfront__create_schedule and again when verification needs a follow-up read.
  • Use veryfront__create_schedule for new schedules.
  • Use veryfront__update_schedule only when a matching schedule already exists and the user asked to change it.

Example pattern

This example lists agents and schedules before creating a schedule. Use the verified agent ID as target.id. If you created the agent first, complete avatar assignment and both readbacks before scheduling it.

ts
const project = "<project>";
const agentId = "salesforce-case-triage";
const definition = {
  name: "Hourly Salesforce case triage",
  target: { kind: "agent", id: agentId, conversation_mode: "create_new" },
  schedule: "0 * * * *",
  timezone: "Europe/Berlin",
  runtime_target_kind: "main_branch",
  config: { prompt: "Check open Salesforce cases, prioritize cases that need attention, and apply only safe triage updates." },
  concurrency_policy: "Forbid"
};
const agents = await veryfront__list_agents({ project_reference: project });
if (!agents.data.some(agent => agent.id === agentId)) {
  throw new Error("Select or create and verify the target agent before scheduling it.");
}

const schedules = [];
let cursor;
do {
  const page = await veryfront__list_schedules({
    project_reference: project,
    ...(cursor ? { cursor } : {})
  });
  schedules.push(...page.data);
  cursor = page.page_info.next;
} while (cursor);

const matches = schedules.filter(schedule =>
  schedule.target.kind === "agent" && schedule.target.id === agentId &&
  schedule.runtime_target_kind === definition.runtime_target_kind
);
if (matches.length > 1) throw new Error("Inspect existing duplicate schedules before making changes.");
const existing = matches[0];
if (existing && existing.status !== "active") {
  throw new Error("A matching inactive schedule exists. Inspect it and resume or repair it only when requested.");
}
if (existing && (
  existing.name !== definition.name ||
  existing.schedule !== definition.schedule || existing.timezone !== definition.timezone ||
  existing.target.conversation_mode !== definition.target.conversation_mode ||
  existing.target.conversation_id != null ||
  existing.config.prompt !== definition.config.prompt || Object.keys(existing.config).length !== 1 ||
  existing.concurrency_policy !== definition.concurrency_policy
)) {
  throw new Error("An existing schedule targets this agent with different settings. Use veryfront__update_schedule with its returned ID for an authorized change; do not create another schedule.");
}

const savedSchedule = existing ?? await veryfront__create_schedule({
  project_reference: project,
  ...definition
});
// Verify the returned target, cadence, timezone, prompt, conversation mode and enabled state.

Resolve schedules by agent and runtime target before comparing settings. Reuse an active schedule only when its requested name, cadence, timezone, prompt, conversation mode and concurrency policy match. Otherwise inspect the existing configuration and update only the changes the user requested. For a cadence or timezone change, use the selected schedule’s actual returned ID:

js
await veryfront__update_schedule({
  project_reference: project,
  schedule_id: existing.id,
  schedule: "0 * * * *",
  timezone: "Europe/Berlin"
});

Changing a paused schedule's timing does not authorize resuming it. Inspect its state and use the live update schema for any user-requested activation change.

Output shape

Return the created or reused agent and schedule IDs, schedule expression, timezone, conversation mode and verification result. If the run has no schedule creation tool, report that scheduling remains incomplete even if the agent was created or found.