OpenWikianthropics/anthropic-sdk-typescript

Beta Namespace Reference

Purpose and Scope

The beta namespace is the SDK entry point for Anthropic API surfaces that are available behind beta contracts, versioned beta headers, or Managed Agents feature gates. In TypeScript usage, a namespace means a grouped set of resource clients and exported types under the main Anthropic package rather than a separate package. This page explains what the repository exposes from src/resources/beta/index.ts, how those exports relate to the generated API reference, and how client-level configuration applies when a caller uses beta resources from the same SDK client.

Sources: src/resources/beta/index.ts, tests/index.test.ts, api.md

Beta APIs should be treated as stable enough to use through the generated SDK surface, but not identical to generally available resources. The official API reference defines an AnthropicBeta domain type as either a string or a set of named beta values such as message batches, prompt caching, computer use, files, MCP client, skills, managed agents, user profiles, and other dated feature flags. The SDK mirrors that model by exporting beta-specific domain types, error shapes, and resource groups from the beta barrel file, letting TypeScript users import concrete parameter and response types without manually copying API schemas.

Relevant Source Files

  • src/resources/beta/index.ts - Generated beta namespace barrel that re-exports beta resource classes, request parameter types, response types, pagination types, and shared beta domain types.
  • tests/index.test.ts - Client-level test coverage for construction, default headers, request building, logging, environment-derived log level, and other behaviors that beta resources inherit through the main Anthropic client.
  • api.md - Repository API reference surface used as a reader-facing cross-check for generated resource names and public SDK organization.

System-to-Code Mapping

The core implementation detail is that src/resources/beta/index.ts is a generated aggregation file. It does not define endpoint behavior inline; instead, it re-exports resource classes and types from files such as ./agents/index, ./beta, ./deployment-runs, and other beta submodules. That structure is important for consumers because the public import surface is intentionally centralized. A user can rely on the generated names exported from the beta namespace while the underlying generated files remain organized by API resource family.

Sources: src/resources/beta/index.ts

The file first exposes the Agents resource and a large set of Managed Agents types, including agent references, tool configuration parameters, toolset inputs for bash, edit, glob, grep, read, and write operations, MCP toolset definitions, model configuration types, multi-agent coordinator types, and pagination and request parameter types such as AgentCreateParams, AgentRetrieveParams, AgentUpdateParams, AgentListParams, and AgentArchiveParams. In practical terms, this means the beta namespace is not only a place for experimental message options; it is also the type-level root for the Managed Agents control plane.

Sources: src/resources/beta/index.ts

The same barrel exports Beta and the shared beta domain types from ./beta. Those include AnthropicBeta, BetaAPIError, BetaAuthenticationError, BetaBillingError, BetaError, BetaErrorResponse, BetaGatewayTimeoutError, BetaInvalidRequestError, BetaNotFoundError, BetaOverloadedError, BetaPermissionError, and BetaRateLimitError. These names line up with the official beta API reference’s error taxonomy, where beta errors are discriminated by type values such as authentication_error, permission_error, not_found_error, rate_limit_error, timeout_error, api_error, and overloaded_error. Use these exported types when writing shared error handling around beta endpoints.

Sources: src/resources/beta/index.ts

Public Export Surface

The beta namespace is broad because it includes both beta variants of core Claude APIs and Managed Agents resources. From the evidence in the generated barrel, the public contract includes at least these resource groups and type families: Agents, Beta, DeploymentRuns, and Deployments, with many related Managed Agents request and response models. Adjacent generated beta index files in the repository also show the same export pattern for agents versions, environments and work queues, memory stores, memories, memory versions, messages, and message batches, but the central beta namespace file is the page’s authoritative source for what is exposed from this specific namespace entry point.

Sources: src/resources/beta/index.ts

A compact way to read this surface is by category. Beta contains shared beta-level types and beta-domain error models. Agents contains the agent resource plus typed configuration for tools, skills, MCP servers, tool policies, model configuration, and multi-agent behavior. DeploymentRuns contains run records, trigger contexts, and run-level failure reasons such as archived agents, missing environments, missing files, blocked MCP egress, missing skills, or disabled organizations. Deployments contains deployment models, schedules, initial events, and paused-reason structures. Each category exports both data models and method parameter types, so users can type request bodies and list parameters without reaching into private implementation files.

Sources: src/resources/beta/index.ts

import Anthropic, { type AnthropicBeta } from '@anthropic-ai/sdk';
 
const client = new Anthropic({
  apiKey: process.env['ANTHROPIC_API_KEY'],
});
 
const betas: AnthropicBeta[] = ['managed-agents-2026-04-01'];
 
// Resource methods are accessed from the generated beta namespace on the client.
// Exact method names and parameters should be checked against api.md and types.

Client Behavior Inherited by Beta Resources

Beta resources use the same SDK client machinery as the rest of the TypeScript package. The client tests show that default headers supplied at construction are included in built requests, that an individual request can leave a default header unchanged by passing undefined, and that a header can be removed by passing null. This is especially relevant for beta usage because beta access often depends on request headers or beta option values; callers should prefer SDK-provided beta parameters where available and use request options deliberately when overriding headers.

Sources: tests/index.test.ts

The tests also demonstrate that SDK logging is controlled at the client level. A client constructed with logLevel: 'debug' calls the provided logger’s debug method, while the default log level is warn, and the ANTHROPIC_LOG environment variable can set debug logging. Because beta resource calls are made through the same client instance, the same logging and request-building behavior applies when diagnosing beta endpoint requests, response handling, retries, or middleware. For operational troubleshooting, configure the client once, then exercise the beta method path you intend to ship.

Sources: tests/index.test.ts

This shared-client model has a practical consequence: beta namespaces should not be configured as if they were a separate transport. API key configuration, base URL overrides, default headers, request-specific headers, and logger settings belong to the Anthropic client. The beta resource object is a generated resource tree mounted under that client. When building internal wrappers, pass around the configured client or the specific beta resource instance, but keep authentication and global request settings centralized so stable and beta calls behave consistently.

Sources: tests/index.test.ts, src/resources/beta/index.ts

Error and Beta-Type Reference

Use the beta error types when code needs to distinguish API failures at the beta schema level rather than only by thrown SDK error classes. The beta domain model exports individual variants for invalid request, authentication, billing, permission, not found, rate limit, gateway timeout, generic API, and overloaded errors, plus a BetaError union and BetaErrorResponse wrapper. The official beta API documentation describes the same shape as an object with an error, a request_id, and a type, so application-level observability should preserve request IDs when logging beta failures.

Sources: src/resources/beta/index.ts

Reference summary:

  • AnthropicBeta - Type for beta feature identifiers accepted by beta-capable requests.
  • Beta - Shared generated beta resource/type module re-exported by the namespace barrel.
  • BetaError - Union of beta error variants.
  • BetaErrorResponse - Error response wrapper for beta API failures.
  • Agents - Managed Agents beta resource group with agent CRUD/archive parameter types and Managed Agents tool, skill, MCP, model, and multi-agent configuration types.
  • DeploymentRuns - Managed Agents deployment run resource group with run records, trigger contexts, run list/retrieve parameters, and run-error variants.
  • Deployments - Managed Agents deployment resource group with deployment models, schedules, initial events, and paused-reason types.

Usage Guidance and Next Steps

When adding beta functionality to an application, start by identifying the beta feature flag or resource family in the official API reference, then use the SDK’s generated TypeScript types to constrain request bodies and response handling. For Managed Agents work, begin at the Agents and deployment-related resources because the namespace exposes both configuration models and operational run models. For beta message behavior, follow the beta messages and message batch references in the wider wiki so that request parameters, streaming behavior, and beta headers are handled at the right layer.

Sources: src/resources/beta/index.ts, api.md

Before productionizing a beta integration, add small tests around your wrapper rather than around the generated SDK itself. Confirm that your client construction supplies the intended API key, default headers, logger, and base URL, then assert that your code passes the intended beta option values and handles the exported beta error variants. The repository’s own client tests are a useful signal for how default headers and logging behave, while api.md and the generated beta namespace are the reference points for public names that application code should import.

Ask a question...