Deployments and Scheduled Runs

Purpose and Scope

Deployments are the Managed Agents mechanism for running an already configured agent repeatedly or manually without recreating the same session setup each time. In the TypeScript SDK, the public entry point is client.beta.deployments, backed by the generated Deployments API resource. A deployment ties together the agent, the environment that will host session execution, the initial user event that starts work, and optional scheduling metadata such as a cron expression and timezone. The SDK also exposes deployment run types and parameters so applications can inspect execution history and diagnose why a scheduled or manual run succeeded or failed.

Sources: src/resources/beta/deployments.ts, src/resources/beta/index.ts

A scheduled deployment is not a replacement for agent setup or environment setup. It composes those resources. The agent describes behavior, tools, skills, MCP toolsets, and model configuration; the environment describes the container or self-hosted execution context; the deployment supplies a reusable launch recipe. This separation matters because the deployment can reference an agent by ID or by a more precise agent reference, while the environment ID points at infrastructure configuration that may be cloud-hosted or self-hosted. The SDK mirrors that product model through separate generated namespaces for agents, environments, deployments, deployment runs, memory stores, and beta messages.

Sources: src/resources/beta/agents/index.ts, src/resources/beta/environments/index.ts, src/resources/beta/deployments.ts

Relevant Source Files

• src/resources/beta/deployments.ts - Defines the generated Deployments API resource, including create, retrieve, update, list, beta-header handling, pagination, path construction, and deployment response/request types.
• src/resources/beta/agents/index.ts - Re-exports Managed Agents agent types and parameters used when selecting the agent that a deployment will run.
• src/resources/beta/environments/index.ts - Re-exports environment configuration types and self-hosted work APIs that deployments rely on for execution infrastructure.
• src/resources/beta/index.ts - Aggregates the beta namespace, including Deployments, DeploymentRuns, deployment error types, trigger context types, and Managed Agents beta exports.
• src/resources/beta/memory-stores/index.ts - Re-exports memory store, memory, and memory version resources that can participate in Managed Agent execution context.
• src/resources/beta/messages/index.ts - Re-exports beta message primitives used across beta functionality, including content block and message-related types relevant to initial events and session-style work.

System-to-Code Mapping

The Deployments class extends the shared APIResource base and uses the SDK client's HTTP helpers directly. create posts to /v1/deployments?beta=true, retrieve gets /v1/deployments/{deploymentID}?beta=true, update posts to the same deployment-specific path, and list calls getAPIList for cursor-paginated results. Each method pulls a betas field out of the parameter object, forwards the remaining fields as the body or query, and appends managed-agents-2026-04-01 to the anthropic-beta header through buildHeaders. That implementation detail is important for users because Managed Agents calls require the beta header, but normal SDK calls do not need users to manually construct it for these resource methods.

Sources: src/resources/beta/deployments.ts

The beta namespace export file is the best map of how deployment-related concepts surface to application code. It exports DeploymentRuns and many run error and trigger types, including schedule and manual trigger context types, alongside Deployments and deployment schedule types such as BetaManagedAgentsCronSchedule and its parameter form. That means a consumer can import deployment response types, create parameter types, run list parameter types, and run error discriminants from the SDK package rather than duplicating API shapes in application code. For deployment observability, this is as important as the create call itself: scheduled automation needs run history, trigger classification, and structured failure reasons.

Sources: src/resources/beta/index.ts

Execution Flow

A typical scheduled-run workflow starts outside the deployment resource. First, create or choose an agent through the Managed Agents agent APIs; that agent can include model settings, tool configuration, skills, MCP server definitions, and multi-agent relationships exposed from the agents namespace. Next, create or choose an environment through the environments namespace; the environment exports include cloud, package, network, and self-hosted configuration types. After those prerequisites exist, call client.beta.deployments.create with a name, the agent reference, an environment_id, and initial_events containing a user.message event. If the deployment should run on a cadence, include a cron schedule with an expression and timezone.

Sources: src/resources/beta/agents/index.ts, src/resources/beta/environments/index.ts, src/resources/beta/deployments.ts

import Anthropic from '@anthropic-ai/sdk';
 
const client = new Anthropic();
 
const deployment = await client.beta.deployments.create({
  name: 'Weekly compliance scan',
  agent: 'agent_123',
  environment_id: 'env_123',
  initial_events: [
    {
      type: 'user.message',
      content: [{ type: 'text', text: 'Run the weekly compliance scan.' }],
    },
  ],
  schedule: {
    type: 'cron',
    expression: '0 20 * * 5',
    timezone: 'America/New_York',
  },
});

After a deployment exists, applications usually need both configuration management and operational monitoring. Configuration management uses retrieve, update, list, and archive behavior on client.beta.deployments. Operational monitoring uses deployment run APIs exported from the beta namespace. The official API model distinguishes runs by trigger type, including scheduled and manual triggers, and exposes filtering by deployment ID, creation time, error presence, limit, page cursor, and trigger type. In practice, that lets a dashboard show whether a cron-driven run created a session, whether it failed before session creation, and whether the failure came from an archived agent, archived environment, missing file, memory store issue, vault issue, or another run error type exported by the SDK.

Sources: src/resources/beta/deployments.ts, src/resources/beta/index.ts

API Components

The deployment resource follows normal SDK request conventions. RequestOptions can still be passed as the final argument, so callers can attach per-request configuration such as headers supported by the SDK's core request layer. The resource itself is responsible for composing Managed Agents beta headers with any caller-provided headers, preserving SDK ergonomics while keeping beta activation explicit in generated code. For list operations, the return type is a PagePromise, so for await iteration can automatically advance through pages while still allowing users who need cursor-level control to work with page objects.

Sources: src/resources/beta/deployments.ts

Scheduling, Context, and Self-Hosted Work

The schedule is only one part of the context a deployment uses to create sessions. The official Managed Agents model says deployments require agent and environment configuration and may also involve files, GitHub, memory stores, and vaults. The source mapping supports that composition: memory store resources are exported separately, and environment exports include both cloud/self-hosted configuration types and a Work resource for self-hosted work queues. When an environment is self-hosted, a worker-style service can use work APIs such as polling, acknowledgement, heartbeat, update, stats, and stop operations to process session work generated by deployments or other Managed Agent flows.

Sources: src/resources/beta/environments/index.ts, src/resources/beta/memory-stores/index.ts

Initial events deserve special attention because they define the first instruction sent into the session created by a deployment run. The generated create example in the deployment resource uses a user.message event whose content contains a text block. That shape matches the broader beta message vocabulary exported from src/resources/beta/messages/index.ts, where many message content and block types are made available for beta APIs. For scheduled automation, treat this initial event as the stable task prompt: include enough context for the recurring job to be meaningful, but keep changing operational inputs in resources such as files, memory, vault-backed credentials, or external integrations when appropriate.

Sources: src/resources/beta/deployments.ts, src/resources/beta/messages/index.ts

Practical Next Steps

When implementing scheduled deployments, build in three checks before turning on a cron cadence. First, verify the agent reference is intentional: use a plain agent ID when tracking the latest version is acceptable, or a versioned agent reference when repeatability is more important. Second, verify the environment is appropriate for the workload, especially if self-hosted workers are responsible for processing work. Third, create a run-inspection path using the deployment run exports so failures are visible instead of silently accumulating. For a production service, pair deployment creation with list or retrieve calls, run filters by deployment ID and trigger type, and structured handling for exported run error types.

Sources: src/resources/beta/index.ts, src/resources/beta/environments/index.ts

Related reading in this wiki: start with managed-agent-setup for creating agents, continue to managed-agent-environments for cloud and self-hosted execution, use managed-agent-sessions for the sessions that deployments create, and use beta-environments-reference or beta-managed-agent-resources-reference when you need method-level detail for work queues, memory stores, vaults, and other supporting resources.