Schedules

Schedules are the LangSmith Agent Server primitive for running an assistant on a recurring timetable. Instead of relying on an application worker to wake up, reconstruct input, and call an agent manually, a schedule stores the recurrence rule, assistant identity, run payload, execution configuration, and lifecycle options in the Agent Server. The official API exposes this as cron creation for either a new run thread or an existing thread, making scheduled work a deployment-level concern rather than only an in-process loop. In the Python repository evidence for this page, the closest source-backed runtime concept is the classic agent iterator: it shows how an agent execution is prepared, tagged, traced through callbacks, and advanced step by step once the server or application starts a run. Sources: libs/langchain/langchain_classic/agents/agent_iterator.py

Purpose and Scope

Use a schedule when the same assistant should run repeatedly without a user sending each message. Common examples include periodic monitoring, report generation, cleanup tasks, synchronization with external systems, or proactive workflows that should continue until an end time. The API distinguishes between creating a cron under /runs/crons, where the server can create and track the associated thread, and creating a thread cron under /threads/{thread_id}/runs/crons, where recurring runs are tied to an existing conversation state. Both forms return a cron record with identifiers, timestamps, enabled state, assistant identity, next run date, metadata, and the stored payload.

A schedule does not replace the agent execution model. It supplies the timing and persisted run request; the assistant still runs with inputs, configuration, context, streaming preferences, interruption controls, and tool access. The source-backed AgentExecutorIterator is useful for understanding that a run is not a single opaque call: inputs are prepared by the executor, callbacks can observe execution, tags and metadata can be attached, and the iterator can yield actions or final output depending on how execution is configured. That same mental model matters for scheduled agents because each cron firing becomes a normal agent run with observable lifecycle and tool-use behavior. Sources: libs/langchain/langchain_classic/agents/agent_iterator.py

Core Primitives

The central object is the cron record. A create-cron request includes schedule, assistant_id, optional timezone, optional end_time, input, metadata, config, context, webhook, interruption controls, enablement, stream options, and durability. The response includes cron_id, thread_id, schedule, created_at, updated_at, payload, enabled, assistant_id, user_id, next_run_date, and metadata. Treat cron_id as the management handle for the schedule and thread_id as the conversation or run context that scheduled executions use or create.

The run payload follows the same shape developers use when invoking agent workflows directly. input carries the user or system data for the assistant, context carries additional runtime context, and config carries execution configuration such as tags, recursion_limit, and configurable values. The source iterator accepts related execution metadata directly: callbacks, tags, metadata, run_name, run_id, include_run_info, and yield_actions. That correspondence is important operationally: schedule authors should choose tags and metadata that make repeated runs easy to filter, debug, and evaluate after many invocations have accumulated. Sources: libs/langchain/langchain_classic/agents/agent_iterator.py

Relevant Source Files

• libs/langchain/langchain_classic/agents/agent_iterator.py — Defines AgentExecutorIterator, the classic in-process execution iterator that prepares inputs, tracks callbacks, tags, metadata, run identifiers, tool mappings, colors, and resettable step state for agent runs.
• libs/langchain/langchain_classic/agents/agent_toolkits/__init__.py — Documents agent toolkits as integrations with external resources such as APIs, databases, and file systems, and warns developers to inspect tool capabilities and permissions.
• libs/langchain/langchain_classic/agents/agent_toolkits/ainetwork/__init__.py — Package marker for the classic AINetwork toolkit compatibility namespace.
• libs/langchain/langchain_classic/agents/agent_toolkits/ainetwork/toolkit.py — Provides dynamic deprecated import lookup for AINetworkToolkit from the community package.
• libs/langchain/langchain_classic/agents/agent_toolkits/amadeus/__init__.py — Package marker for the classic Amadeus toolkit compatibility namespace.
• libs/langchain/langchain_classic/agents/agent_toolkits/amadeus/toolkit.py — Provides dynamic deprecated import lookup for AmadeusToolkit from the community package.

API Reference

Create a schedule for server-managed recurring runs with POST /runs/crons. Create a schedule bound to an existing thread with POST /threads/{thread_id}/runs/crons. Both endpoints return 200 on success and may return 404 or 422 for missing resources or invalid request bodies. For a thread-bound cron, the request also supports multitask_strategy, with the documented example using enqueue, so repeated firings can be queued against the target thread rather than treated as independent calls. For non-thread creation, the documented request includes on_run_completed, with the example value delete, allowing cleanup behavior to be associated with completed scheduled runs.

{
  "schedule": "<string>",
  "assistant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "timezone": "<string>",
  "end_time": "2023-11-07T05:31:56Z",
  "input": [{}],
  "metadata": {},
  "config": {
    "tags": ["<string>"],
    "recursion_limit": 123,
    "configurable": {}
  },
  "context": {},
  "webhook": "<string>",
  "interrupt_before": "*",
  "interrupt_after": "*",
  "enabled": true,
  "stream_mode": ["values"],
  "stream_subgraphs": false,
  "stream_resumable": false,
  "durability": "async"
}

When choosing fields, start with the minimum operational contract: schedule, assistant_id, input, and an explicit enabled value. Add timezone when the schedule is expressed for a business region rather than UTC, end_time when the recurrence should expire, and metadata for ownership or purpose labels. Add config.tags early, because recurring background runs otherwise become hard to distinguish from interactive traffic. Use interrupt_before and interrupt_after only when a human approval or inspection workflow is expected; scheduled jobs that routinely pause need an owner and a resume procedure.

System-to-Code Mapping

Scheduled execution often needs tools, because recurring agents usually act on external systems. The classic toolkit package describes toolkits as integrations with local and remote file systems, APIs, databases, and other resources. It also emphasizes a security review: developers should inspect the capabilities and permissions of the underlying tools and decide whether they are appropriate for the application. That guidance is especially important for schedules because a permissioned tool may run unattended at every recurrence. A travel, payments, ticketing, or network action that is acceptable in a supervised chat can become risky when repeated automatically. Sources: libs/langchain/langchain_classic/agents/agent_toolkits/init.py

The compatibility toolkit modules show how older import paths resolve provider-specific toolkits from community packages. AINetworkToolkit and AmadeusToolkit are both exposed through dynamic __getattr__ lookup backed by create_importer, with __all__ defining the exported public symbol. For schedule authors, the practical lesson is that a deployed assistant may depend on integrations whose import path is a compatibility layer. Before scheduling that assistant, verify the runtime environment includes the needed community package and that its credentials, network permissions, and rate limits are suitable for unattended recurrence. Sources: libs/langchain/langchain_classic/agents/agent_toolkits/ainetwork/toolkit.py, libs/langchain/langchain_classic/agents/agent_toolkits/amadeus/toolkit.py

Execution Flow

A typical scheduled-agent flow begins by designing the assistant and validating it interactively. Run it with representative input, confirm tool access, inspect callback traces, and decide whether actions should be streamed, interrupted, or allowed to complete without review. Then create the cron using the Agent Server API, storing operational labels in metadata and trace labels in config.tags. At each scheduled time, the server uses the stored payload to start a run, and the run proceeds through the normal agent execution path: inputs are prepared, tools are addressable by name, callbacks receive lifecycle events, and intermediate steps accumulate until completion or interruption. Sources: libs/langchain/langchain_classic/agents/agent_iterator.py

For thread crons, think carefully about concurrency and conversation state. Binding a schedule to /threads/{thread_id}/runs/crons means each recurrence targets the same thread, so previous state can influence later runs. The documented multitask_strategy option is therefore not just a queueing detail; it is part of how you protect a stateful workflow from overlapping executions. For standalone /runs/crons, the response still includes a thread_id, so downstream observability and management should record both identifiers. If a webhook is configured, design it as a delivery mechanism for completion notifications rather than the only source of truth; the cron record and run traces remain the primary control-plane data.

Operational Guidance

Before enabling a schedule in production, review four areas: recurrence, payload, permissions, and observability. Recurrence covers the schedule, timezone, end_time, and enabled values. Payload covers input, context, and any configurable runtime values needed by the assistant. Permissions cover every tool reachable by the assistant, including compatibility-imported toolkits and remote APIs. Observability covers metadata, tags, callbacks, stream options, and webhook destinations. This is the difference between a useful scheduled agent and an unattended loop that is hard to diagnose after it has consumed model calls or invoked external systems.

Next, read the pages on human-in-the-loop approvals and event streaming if your schedule can pause or needs live progress updates. Read the tool integrations and MCP pages if the scheduled assistant calls external systems. For teams deploying recurring work, pair this page with deployment and auth guidance so API keys, workspace permissions, and environment-specific credentials are handled deliberately rather than embedded in payloads.