Sign in

v2

OpenAPI 3.0.02026-08-051996591.2 MB
Agent Schedules

Create agent schedule

Creates a schedule that runs an agent automatically at specified intervals. Each execution creates a new session with the configured message and metadata.

Use schedules for automated agent workflows such as daily reports, periodic monitoring, or regular data processing. The schedule tags each created session with metadata that identifies it as a scheduled execution.

Example request

\$ curl -X POST https://api.vectara.io/v2/agents/support-agent/schedules \
-H "Authorization: Bearer YOUR_API_KEY" \c
-H "Content-Type: application/json" \
-d '{
  "key": "daily-report",
  "name": "Daily Summary Report",
  "message": [{"type": "text", "content": "Generate a summary of today's activities"}],
  "schedule": {
    "type": "interval",
    "interval": "PT24H"
  },
  "session_metadata": {
    "report_type": "daily"
  }
}'

A successful response includes the unique schedule key, configuration, and creation timestamp.

post/v2/agents/{agent_key}/schedules

Path parameters

agent_keystring required

A unique key that identifies an agent.

Example:customer_support

The unique key of the agent to create a schedule for.

Headers

Request-Timeoutinteger

The platform makes a best effort to complete the request in the specified seconds, or it times out.

Request-Timeout-Millisinteger

The platform makes a best effort to complete the request in the specified milliseconds, or it times out.

Request body

keystring

A unique key that identifies an agent schedule.

namestring required

The human-readable name of an agent schedule.

descriptionstring

Optional detailed description of the schedule's purpose.

enabledboolean

Whether the schedule is active upon creation.

session_metadataobject

Arbitrary metadata to include in each session created by this schedule.

run_conditionstring

A UserFn boolean expression that gates execution. On each scheduled execution the agent's enrichment runs first. The schedule then evaluates this expression against the enriched session context. When the expression evaluates to true, the schedule creates the session and the agent runs. When it evaluates to false, the schedule skips the execution and creates no session.

The expression uses the get() function with JSONPath to read the enriched context:

  • $.session.metadata.* for values written by the agent's enrichment
  • $.agent.metadata.* for the owning agent's metadata

An enrichment tool call's output is visible to the condition only when the call writes it to metadata via metadata_target_path. Missing paths return null. Comparing against null is falsy, so an unresolved path skips the execution. Use get('$.path', default) for an explicit fallback. Omit this field to run on every execution.

See https://docs.vectara.com/docs/reference/userfn-language for the UserFn language reference.

max_executions_to_keepinteger

Maximum number of past execution records to keep. Defaults to 10.

stall_timeout_secondsinteger

The number of seconds a scheduled run may go without producing output (streamed tokens, tool calls, or other progress events). After this period, the run is considered stalled and is retried. Set this above the longest silent operation the agent performs, so an in-flight run is not retried mid-operation.

Example request

{
  "key": "daily-report",
  "name": "Daily Summary Report",
  "message": [
    {
      "type": "text",
      "content": "I need help with my widget installation"
    }
  ],
  "schedule": {
    "type": "interval",
    "interval": "PT24H"
  },
  "run_condition": "get('$.session.metadata.open_incidents') > 0",
  "stall_timeout_seconds": 1800
}

Response

The created schedule, including the unique schedule key, interval, and timestamps.

keystring required

A unique key that identifies an agent schedule.

agent_keystring required

A unique key that identifies an agent.

namestring required

The human-readable name of an agent schedule.

descriptionstring

A detailed description of the schedule's purpose.

enabledboolean required

Whether the schedule is currently active and executing.

session_metadataobject

Arbitrary metadata to include in each session created by this schedule.

run_conditionstring

A UserFn boolean expression that gates execution. On each scheduled execution the agent's enrichment runs first. The schedule then evaluates this expression against the enriched session context. When the expression evaluates to true, the schedule creates the session and the agent runs. When it evaluates to false, the schedule skips the execution and creates no session.

The expression uses the get() function with JSONPath to read the enriched context:

  • $.session.metadata.* for values written by the agent's enrichment
  • $.agent.metadata.* for the owning agent's metadata

An enrichment tool call's output is visible to the condition only when the call writes it to metadata via metadata_target_path. Missing paths return null. Comparing against null is falsy, so an unresolved path skips the execution. Use get('$.path', default) for an explicit fallback. Omit this field to run on every execution.

See https://docs.vectara.com/docs/reference/userfn-language for the UserFn language reference.

max_executions_to_keepinteger

Maximum number of past execution records to keep. Older records are deleted automatically when a new execution is recorded.

stall_timeout_secondsinteger

The number of seconds a scheduled run may go without producing output (streamed tokens, tool calls, or other progress events). After this period, the run is considered stalled and is retried. Set this above the longest silent operation the agent performs, so an in-flight run is not retried mid-operation.

last_execution_atstring date-time nullable

Timestamp of the most recent execution. Updated automatically after each execution. Null until the schedule executes for the first time.

created_atstring date-time required

Timestamp when the schedule was created. Create and update responses return the current time. Later reads return 1970-01-01T00:00:00Z.

Example response

{
  "key": "daily-report",
  "agent_key": "customer_support",
  "name": "Daily Summary Report",
  "description": "Generates a daily summary report of customer support activities",
  "message": [
    {
      "type": "text",
      "content": "Generate a summary of today's activities"
    }
  ],
  "schedule": {
    "type": "interval",
    "interval": "PT24H"
  },
  "enabled": true,
  "session_metadata": {
    "report_type": "daily",
    "format": "markdown"
  },
  "run_condition": "get('$.session.metadata.open_incidents') > 0",
  "max_executions_to_keep": 10,
  "stall_timeout_seconds": 1800,
  "last_execution_at": "2024-01-15T10:30:00Z",
  "created_at": "1970-01-01T00:00:00Z"
}