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
- Inspect existing agents with
veryfront__list_agentsand schedules withveryfront__list_schedules, without a status filter. Follow everypage_info.nextcursor so paused or otherwise inactive schedules cannot be missed. - 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, thenveryfront__get_agent_capabilities, using the same project and source target. Stop if either readback fails. Otherwise continue scheduling in the same run. - Collect only missing schedule requirements. Required fields are the agent ID, schedule expression, timezone, and run prompt.
- Reuse a matching active schedule. If the user requested different settings, change them with
veryfront__update_scheduleusing the existing schedule ID. - 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_scheduleonly when no matching schedule exists. - 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_agentandveryfront__create_schedule. Complete the avatar assignment and both agent readbacks first. Once they succeed, callveryfront__create_scheduleunless 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:
{
"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.
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:
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_agentsbefore creating or choosing the target agent. - Use
veryfront__list_schedulesbeforeveryfront__create_scheduleand again when verification needs a follow-up read. - Use
veryfront__create_schedulefor new schedules. - Use
veryfront__update_scheduleonly 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.
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:
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.