@tetral-ai/sdk 0.110.0-alpha.1

package/src/resources/beta/agents/agents.ts

@@ -0,0 +1,1279 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as BetaAPI from '../beta';
+import * as VersionsAPI from './versions';
+import { VersionListParams, Versions } from './versions';
+import * as SessionsAPI from '../sessions/sessions';
+import { APIPromise } from '../../../core/api-promise';
+import { PageCursor, type PageCursorParams, PagePromise } from '../../../core/pagination';
+import { buildHeaders } from '../../../internal/headers';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+export class Agents extends APIResource {
+  versions: VersionsAPI.Versions = new VersionsAPI.Versions(this._client);
+
+  /**
+   * Create Agent
+   *
+   * @example
+   * ```ts
+   * const betaManagedAgentsAgent =
+   *   await client.beta.agents.create({
+   *     model: 'anthropic/claude-opus-4-8',
+   *     name: 'My First Agent',
+   *     approval_mode: 'ask_for_approval',
+   *     tools: [{ type: 'tetral_agent_toolset', family: 'claude' }],
+   *   });
+   * ```
+   */
+  create(params: AgentCreateParams, options?: RequestOptions): APIPromise<BetaManagedAgentsAgent> {
+    const { betas, ...body } = params;
+    return this._client.post('/v1/agents?beta=true', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { 'anthropic-beta': [...(betas ?? []), 'managed-agents-2026-04-01'].toString() },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Get Agent
+   *
+   * @example
+   * ```ts
+   * const betaManagedAgentsAgent =
+   *   await client.beta.agents.retrieve(
+   *     'agent_011CZkYpogX7uDKUyvBTophP',
+   *   );
+   * ```
+   */
+  retrieve(
+    agentID: string,
+    params: AgentRetrieveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<BetaManagedAgentsAgent> {
+    const { betas, ...query } = params ?? {};
+    return this._client.get(path`/v1/agents/${agentID}?beta=true`, {
+      query,
+      ...options,
+      headers: buildHeaders([
+        { 'anthropic-beta': [...(betas ?? []), 'managed-agents-2026-04-01'].toString() },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Update Agent
+   *
+   * @example
+   * ```ts
+   * const betaManagedAgentsAgent =
+   *   await client.beta.agents.update(
+   *     'agent_011CZkYpogX7uDKUyvBTophP',
+   *     { version: 1 },
+   *   );
+   * ```
+   */
+  update(
+    agentID: string,
+    params: AgentUpdateParams,
+    options?: RequestOptions,
+  ): APIPromise<BetaManagedAgentsAgent> {
+    const { betas, ...body } = params;
+    return this._client.post(path`/v1/agents/${agentID}?beta=true`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { 'anthropic-beta': [...(betas ?? []), 'managed-agents-2026-04-01'].toString() },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * List Agents
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const betaManagedAgentsAgent of client.beta.agents.list()) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    params: AgentListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<BetaManagedAgentsAgentsPageCursor, BetaManagedAgentsAgent> {
+    const { betas, ...query } = params ?? {};
+    return this._client.getAPIList('/v1/agents?beta=true', PageCursor<BetaManagedAgentsAgent>, {
+      query,
+      ...options,
+      headers: buildHeaders([
+        { 'anthropic-beta': [...(betas ?? []), 'managed-agents-2026-04-01'].toString() },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Archive Agent
+   *
+   * @example
+   * ```ts
+   * const betaManagedAgentsAgent =
+   *   await client.beta.agents.archive(
+   *     'agent_011CZkYpogX7uDKUyvBTophP',
+   *   );
+   * ```
+   */
+  archive(
+    agentID: string,
+    params: AgentArchiveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<BetaManagedAgentsAgent> {
+    const { betas } = params ?? {};
+    return this._client.post(path`/v1/agents/${agentID}/archive?beta=true`, {
+      ...options,
+      headers: buildHeaders([
+        { 'anthropic-beta': [...(betas ?? []), 'managed-agents-2026-04-01'].toString() },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export type BetaManagedAgentsAgentsPageCursor = PageCursor<BetaManagedAgentsAgent>;
+
+export type AgentApprovalMode = 'full_access' | 'ask_for_approval' | 'approve_for_me';
+
+/**
+ * A Managed Agents `agent`.
+ */
+export interface BetaManagedAgentsAgent {
+  id: string;
+
+  /**
+   * A timestamp in RFC 3339 format
+   */
+  archived_at: string | null;
+
+  /**
+   * A timestamp in RFC 3339 format
+   */
+  created_at: string;
+
+  description: string | null;
+
+  mcp_servers: Array<BetaManagedAgentsMCPServerURLDefinition>;
+
+  /**
+   * Resolved approval mode for tool use. When omitted on create, Tetral resolves
+   * the default to `ask_for_approval`.
+   */
+  approval_mode: AgentApprovalMode;
+
+  metadata: { [key: string]: string };
+
+  /**
+   * Model identifier and configuration.
+   */
+  model: BetaManagedAgentsModelConfig;
+
+  /**
+   * Resolved coordinator topology with a concrete agent roster.
+   */
+  multiagent: SessionsAPI.BetaManagedAgentsMultiagent | null;
+
+  name: string;
+
+  skills: Array<BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill>;
+
+  system: string | null;
+
+  tools: Array<
+    | BetaManagedAgentsTetralAgentToolset
+    | BetaManagedAgentsAgentToolset20260401
+    | BetaManagedAgentsMCPToolset
+    | BetaManagedAgentsCustomTool
+  >;
+
+  type: 'agent';
+
+  /**
+   * A timestamp in RFC 3339 format
+   */
+  updated_at: string;
+
+  /**
+   * The agent's current version. Starts at 1 and increments when the agent is
+   * modified.
+   */
+  version: number;
+}
+
+/**
+ * A resolved agent reference with a concrete version.
+ */
+export interface BetaManagedAgentsAgentReference {
+  id: string;
+
+  type: 'agent';
+
+  version: number;
+}
+
+/**
+ * Configuration for a specific agent tool.
+ */
+export interface BetaManagedAgentsAgentToolConfig {
+  enabled: boolean;
+
+  /**
+   * Built-in agent tool identifier.
+   */
+  name: 'bash' | 'edit' | 'read' | 'write' | 'glob' | 'grep' | 'web_fetch' | 'web_search';
+
+  /**
+   * Permission policy for tool execution.
+   */
+  permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy;
+}
+
+/**
+ * Configuration override for a specific tool within a toolset.
+ */
+export interface BetaManagedAgentsAgentToolConfigParams {
+  /**
+   * Built-in agent tool identifier.
+   */
+  name: 'bash' | 'edit' | 'read' | 'write' | 'glob' | 'grep' | 'web_fetch' | 'web_search';
+
+  /**
+   * Whether this tool is enabled and available to Claude. Overrides the
+   * default_config setting.
+   */
+  enabled?: boolean | null;
+
+  /**
+   * Permission policy for tool execution.
+   */
+  permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null;
+}
+
+/**
+ * Resolved default configuration for agent tools.
+ */
+export interface BetaManagedAgentsAgentToolsetDefaultConfig {
+  enabled: boolean;
+
+  /**
+   * Permission policy for tool execution.
+   */
+  permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy;
+}
+
+/**
+ * Default configuration for all tools in a toolset.
+ */
+export interface BetaManagedAgentsAgentToolsetDefaultConfigParams {
+  /**
+   * Whether tools are enabled and available to Claude by default. Defaults to true
+   * if not specified.
+   */
+  enabled?: boolean | null;
+
+  /**
+   * Permission policy for tool execution.
+   */
+  permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null;
+}
+
+export type BetaManagedAgentsTetralPlatformToolName = 'web' | 'memory' | 'subagent';
+
+export type BetaManagedAgentsTetralClaudeToolName =
+  | 'bash'
+  | 'read'
+  | 'write'
+  | 'edit'
+  | 'glob'
+  | 'grep'
+  | BetaManagedAgentsTetralPlatformToolName;
+
+export type BetaManagedAgentsTetralGPTToolName =
+  | 'exec_command'
+  | 'write_stdin'
+  | 'view_image'
+  | 'apply_patch'
+  | BetaManagedAgentsTetralPlatformToolName;
+
+export type BetaManagedAgentsTetralAgentToolset =
+  | BetaManagedAgentsTetralClaudeAgentToolset
+  | BetaManagedAgentsTetralGPTAgentToolset;
+
+export type BetaManagedAgentsTetralAgentToolsetParams =
+  | BetaManagedAgentsTetralClaudeAgentToolsetParams
+  | BetaManagedAgentsTetralGPTAgentToolsetParams;
+
+/**
+ * Resolved Tetral built-in tool configuration for a Claude-family agent.
+ */
+export interface BetaManagedAgentsTetralClaudeToolConfig {
+  enabled: boolean;
+
+  name: BetaManagedAgentsTetralClaudeToolName;
+
+  /**
+   * Permission policy for tool execution.
+   */
+  permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy;
+}
+
+/**
+ * Tetral built-in tool configuration for a Claude-family agent.
+ */
+export interface BetaManagedAgentsTetralClaudeToolConfigParams {
+  name: BetaManagedAgentsTetralClaudeToolName;
+
+  /**
+   * Whether this tool is enabled and available to the agent.
+   */
+  enabled?: boolean | null;
+
+  /**
+   * Permission policy for tool execution.
+   */
+  permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null;
+}
+
+/**
+ * Resolved Tetral built-in tool configuration for a GPT-family agent.
+ */
+export interface BetaManagedAgentsTetralGPTToolConfig {
+  enabled: boolean;
+
+  name: BetaManagedAgentsTetralGPTToolName;
+
+  /**
+   * Permission policy for tool execution.
+   */
+  permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy;
+}
+
+/**
+ * Tetral built-in tool configuration for a GPT-family agent.
+ */
+export interface BetaManagedAgentsTetralGPTToolConfigParams {
+  name: BetaManagedAgentsTetralGPTToolName;
+
+  /**
+   * Whether this tool is enabled and available to the agent.
+   */
+  enabled?: boolean | null;
+
+  /**
+   * Permission policy for tool execution.
+   */
+  permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null;
+}
+
+export interface BetaManagedAgentsTetralClaudeAgentToolset {
+  configs: Array<BetaManagedAgentsTetralClaudeToolConfig>;
+
+  /**
+   * Resolved default configuration for Tetral built-in tools.
+   */
+  default_config: BetaManagedAgentsAgentToolsetDefaultConfig;
+
+  family: 'claude';
+
+  type: 'tetral_agent_toolset';
+}
+
+export interface BetaManagedAgentsTetralClaudeAgentToolsetParams {
+  type: 'tetral_agent_toolset';
+
+  family: 'claude';
+
+  /**
+   * Per-tool configuration overrides. Claude-family configs accept Claude built-ins
+   * plus platform built-ins.
+   */
+  configs?: Array<BetaManagedAgentsTetralClaudeToolConfigParams>;
+
+  /**
+   * Default configuration for all tools in the toolset.
+   */
+  default_config?: BetaManagedAgentsAgentToolsetDefaultConfigParams | null;
+}
+
+export interface BetaManagedAgentsTetralGPTAgentToolset {
+  configs: Array<BetaManagedAgentsTetralGPTToolConfig>;
+
+  /**
+   * Resolved default configuration for Tetral built-in tools.
+   */
+  default_config: BetaManagedAgentsAgentToolsetDefaultConfig;
+
+  family: 'gpt';
+
+  type: 'tetral_agent_toolset';
+}
+
+export interface BetaManagedAgentsTetralGPTAgentToolsetParams {
+  type: 'tetral_agent_toolset';
+
+  family: 'gpt';
+
+  /**
+   * Per-tool configuration overrides. GPT-family configs accept GPT built-ins plus
+   * platform built-ins.
+   */
+  configs?: Array<BetaManagedAgentsTetralGPTToolConfigParams>;
+
+  /**
+   * Default configuration for all tools in the toolset.
+   */
+  default_config?: BetaManagedAgentsAgentToolsetDefaultConfigParams | null;
+}
+
+/**
+ * Legacy Anthropic-managed built-in toolset retained for upstream compatibility.
+ * Tetral Agent create/update uses `tetral_agent_toolset`; Tetral rejects this
+ * legacy shape in this stage.
+ */
+export interface BetaManagedAgentsAgentToolset20260401 {
+  configs: Array<BetaManagedAgentsAgentToolConfig>;
+
+  /**
+   * Resolved default configuration for agent tools.
+   */
+  default_config: BetaManagedAgentsAgentToolsetDefaultConfig;
+
+  type: 'agent_toolset_20260401';
+}
+
+/**
+ * Input payload for the `bash` tool of the `agent_toolset_20260401` toolset. All
+ * fields are optional; a normal invocation supplies `command`, while
+ * `restart=true` (with no `command`) reboots the runner-side bash session.
+ */
+export interface BetaManagedAgentsAgentToolset20260401BashInput {
+  /**
+   * Shell command to execute. Omit only when `restart` is true.
+   */
+  command?: string;
+
+  /**
+   * When true, restart the persistent bash session instead of running a command.
+   * Subsequent calls without `restart` will run against the fresh session.
+   */
+  restart?: boolean;
+
+  /**
+   * Per-call timeout in milliseconds. Defaults to the runner-wide tool timeout when
+   * omitted or zero.
+   */
+  timeout_ms?: number;
+}
+
+/**
+ * Input payload for the `edit` tool. Performs a string replacement in the named
+ * file; by default `old_string` must occur exactly once.
+ */
+export interface BetaManagedAgentsAgentToolset20260401EditInput {
+  /**
+   * Path of the file to edit.
+   */
+  file_path: string;
+
+  /**
+   * Replacement text.
+   */
+  new_string: string;
+
+  /**
+   * Substring to find and replace.
+   */
+  old_string: string;
+
+  /**
+   * When true, replace every occurrence of `old_string` instead of requiring a
+   * unique match.
+   */
+  replace_all?: boolean;
+}
+
+/**
+ * Input payload for the `glob` tool. Returns paths matching a doublestar glob
+ * pattern, newest first.
+ */
+export interface BetaManagedAgentsAgentToolset20260401GlobInput {
+  /**
+   * Doublestar glob pattern (e.g. `** /*.go`). Absolute patterns are only permitted
+   * when the runner is configured to allow them.
+   */
+  pattern: string;
+
+  /**
+   * Optional directory root to search under. Defaults to the runner's working
+   * directory.
+   */
+  path?: string;
+}
+
+/**
+ * Input payload for the `grep` tool. Searches file contents for a regular
+ * expression, returning matching lines.
+ */
+export interface BetaManagedAgentsAgentToolset20260401GrepInput {
+  /**
+   * Regular expression to search for.
+   */
+  pattern: string;
+
+  /**
+   * Optional directory root to search under. Defaults to the runner's working
+   * directory.
+   */
+  path?: string;
+}
+
+/**
+ * Legacy Anthropic-managed built-in toolset params retained for upstream
+ * compatibility. Tetral Agent create/update uses `tetral_agent_toolset`; Tetral
+ * rejects this legacy shape in this stage.
+ */
+export interface BetaManagedAgentsAgentToolset20260401Params {
+  type: 'agent_toolset_20260401';
+
+  /**
+   * Per-tool configuration overrides.
+   */
+  configs?: Array<BetaManagedAgentsAgentToolConfigParams>;
+
+  /**
+   * Default configuration for all tools in a toolset.
+   */
+  default_config?: BetaManagedAgentsAgentToolsetDefaultConfigParams | null;
+}
+
+/**
+ * Input payload for the `read` tool. Reads file contents relative to the runner's
+ * working directory (or absolute when the runner permits).
+ */
+export interface BetaManagedAgentsAgentToolset20260401ReadInput {
+  /**
+   * Path of the file to read.
+   */
+  file_path: string;
+
+  /**
+   * Optional `[start_line, end_line]` 1-indexed inclusive range. When omitted the
+   * entire file is returned. `end_line` of 0 or negative means "to end of file".
+   */
+  view_range?: Array<number>;
+}
+
+/**
+ * Input payload for the `write` tool. Writes (overwriting) the entire file
+ * contents.
+ */
+export interface BetaManagedAgentsAgentToolset20260401WriteInput {
+  /**
+   * Full file contents to write.
+   */
+  content: string;
+
+  /**
+   * Path of the file to write.
+   */
+  file_path: string;
+}
+
+/**
+ * Tool calls are automatically approved without user confirmation.
+ */
+export interface BetaManagedAgentsAlwaysAllowPolicy {
+  type: 'always_allow';
+}
+
+/**
+ * Tool calls require user confirmation before execution.
+ */
+export interface BetaManagedAgentsAlwaysAskPolicy {
+  type: 'always_ask';
+}
+
+/**
+ * A resolved Anthropic-managed skill.
+ */
+export interface BetaManagedAgentsAnthropicSkill {
+  skill_id: string;
+
+  type: 'anthropic';
+
+  version: string;
+}
+
+/**
+ * An Anthropic-managed skill.
+ */
+export interface BetaManagedAgentsAnthropicSkillParams {
+  /**
+   * Identifier of the Anthropic skill (e.g., "xlsx").
+   */
+  skill_id: string;
+
+  type: 'anthropic';
+
+  /**
+   * Version to pin. Defaults to latest if omitted.
+   */
+  version?: string | null;
+}
+
+/**
+ * A resolved user-created custom skill.
+ */
+export interface BetaManagedAgentsCustomSkill {
+  skill_id: string;
+
+  type: 'custom';
+
+  version: string;
+}
+
+/**
+ * A user-created custom skill.
+ */
+export interface BetaManagedAgentsCustomSkillParams {
+  /**
+   * Tagged ID of the custom skill (e.g., "skill_01XJ5...").
+   */
+  skill_id: string;
+
+  type: 'custom';
+
+  /**
+   * Version to pin. Defaults to latest if omitted.
+   */
+  version?: string | null;
+}
+
+/**
+ * A custom tool as returned in API responses. Retained for upstream compatibility;
+ * Tetral rejects client-executed custom Agent tools in this stage.
+ */
+export interface BetaManagedAgentsCustomTool {
+  description: string;
+
+  /**
+   * JSON Schema for custom tool input parameters.
+   */
+  input_schema: BetaManagedAgentsCustomToolInputSchema;
+
+  name: string;
+
+  type: 'custom';
+}
+
+/**
+ * JSON Schema for custom tool input parameters.
+ */
+export interface BetaManagedAgentsCustomToolInputSchema {
+  type: 'object';
+
+  properties?: { [key: string]: unknown } | null;
+
+  required?: Array<string> | null;
+
+  [k: string]: unknown;
+}
+
+/**
+ * A custom tool that is executed by the API client rather than the agent. Retained
+ * for upstream compatibility; Tetral rejects this Agent tool shape in this stage
+ * instead of treating it as a local success or no-op.
+ */
+export interface BetaManagedAgentsCustomToolParams {
+  /**
+   * Description of what the tool does, shown to the agent to help it decide when to
+   * use the tool. 1-1024 characters.
+   */
+  description: string;
+
+  /**
+   * JSON Schema for custom tool input parameters.
+   */
+  input_schema: BetaManagedAgentsCustomToolInputSchema;
+
+  /**
+   * Unique name for the tool. 1-128 characters; letters, digits, underscores, and
+   * hyphens.
+   */
+  name: string;
+
+  type: 'custom';
+}
+
+/**
+ * URL-based MCP server connection as returned in API responses.
+ */
+export interface BetaManagedAgentsMCPServerURLDefinition {
+  name: string;
+
+  type: 'url';
+
+  url: string;
+}
+
+/**
+ * Resolved configuration for a specific MCP tool.
+ */
+export interface BetaManagedAgentsMCPToolConfig {
+  enabled: boolean;
+
+  name: string;
+
+  /**
+   * Permission policy for tool execution.
+   */
+  permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy;
+}
+
+/**
+ * Configuration override for a specific MCP tool.
+ */
+export interface BetaManagedAgentsMCPToolConfigParams {
+  /**
+   * Name of the MCP tool to configure. 1-128 characters.
+   */
+  name: string;
+
+  /**
+   * Whether this tool is enabled. Overrides the `default_config` setting.
+   */
+  enabled?: boolean | null;
+
+  /**
+   * Permission policy for tool execution.
+   */
+  permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null;
+}
+
+export interface BetaManagedAgentsMCPToolset {
+  configs: Array<BetaManagedAgentsMCPToolConfig>;
+
+  /**
+   * Resolved default configuration for all tools from an MCP server.
+   */
+  default_config: BetaManagedAgentsMCPToolsetDefaultConfig;
+
+  mcp_server_name: string;
+
+  type: 'mcp_toolset';
+}
+
+/**
+ * Resolved default configuration for all tools from an MCP server.
+ */
+export interface BetaManagedAgentsMCPToolsetDefaultConfig {
+  enabled: boolean;
+
+  /**
+   * Permission policy for tool execution.
+   */
+  permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy;
+}
+
+/**
+ * Default configuration for all tools from an MCP server.
+ */
+export interface BetaManagedAgentsMCPToolsetDefaultConfigParams {
+  /**
+   * Whether tools are enabled by default. Defaults to true if not specified.
+   */
+  enabled?: boolean | null;
+
+  /**
+   * Permission policy for tool execution.
+   */
+  permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null;
+}
+
+/**
+ * Configuration for tools from an MCP server defined in `mcp_servers`.
+ */
+export interface BetaManagedAgentsMCPToolsetParams {
+  /**
+   * Name of the MCP server. Must match a server name from the mcp_servers array.
+   * 1-255 characters.
+   */
+  mcp_server_name: string;
+
+  type: 'mcp_toolset';
+
+  /**
+   * Per-tool configuration overrides.
+   */
+  configs?: Array<BetaManagedAgentsMCPToolConfigParams>;
+
+  /**
+   * Default configuration for all tools from an MCP server.
+   */
+  default_config?: BetaManagedAgentsMCPToolsetDefaultConfigParams | null;
+}
+
+/**
+ * The model that will power your agent.
+ *
+ * Known Tetral model IDs are `openai/gpt-5.5`, `openai/gpt-5.6-sol`,
+ * `anthropic/claude-opus-4-8`, `anthropic/claude-fable-5`,
+ * `deepseek/deepseek-v4-pro`, `moonshotai/kimi-k3`, and `zai/glm-5.2`.
+ * This type provides autocomplete, not admission: arbitrary strings
+ * type-check, while the engine gates model IDs and rejects unknown values with
+ * a 400 response that enumerates the allowed set.
+ */
+export type BetaManagedAgentsModel =
+  | 'openai/gpt-5.5'
+  | 'openai/gpt-5.6-sol'
+  | 'anthropic/claude-opus-4-8'
+  | 'anthropic/claude-fable-5'
+  | 'deepseek/deepseek-v4-pro'
+  | 'moonshotai/kimi-k3'
+  | 'zai/glm-5.2'
+  | (string & {});
+
+/**
+ * Model identifier and configuration.
+ */
+export interface BetaManagedAgentsModelConfig {
+  /**
+   * The model that will power your agent.
+   *
+   * Known Tetral model IDs are `openai/gpt-5.5`, `openai/gpt-5.6-sol`,
+   * `anthropic/claude-opus-4-8`, `anthropic/claude-fable-5`,
+   * `deepseek/deepseek-v4-pro`, `moonshotai/kimi-k3`, and `zai/glm-5.2`.
+   * This type provides autocomplete, not admission: arbitrary strings
+   * type-check, while the engine gates model IDs and rejects unknown values
+   * with a 400 response that enumerates the allowed set.
+   */
+  id: BetaManagedAgentsModel;
+
+  /**
+   * Inference speed mode. `fast` provides significantly faster output token
+   * generation at premium pricing. Not all models support `fast`; invalid
+   * combinations are rejected at create time.
+   */
+  speed?: 'standard' | 'fast';
+}
+
+/**
+ * An object that defines additional configuration control over model use
+ */
+export interface BetaManagedAgentsModelConfigParams {
+  /**
+   * The model that will power your agent.
+   *
+   * Known Tetral model IDs are `openai/gpt-5.5`, `openai/gpt-5.6-sol`,
+   * `anthropic/claude-opus-4-8`, `anthropic/claude-fable-5`,
+   * `deepseek/deepseek-v4-pro`, `moonshotai/kimi-k3`, and `zai/glm-5.2`.
+   * This type provides autocomplete, not admission: arbitrary strings
+   * type-check, while the engine gates model IDs and rejects unknown values
+   * with a 400 response that enumerates the allowed set.
+   */
+  id: BetaManagedAgentsModel;
+
+  /**
+   * Inference speed mode. `fast` provides significantly faster output token
+   * generation at premium pricing. Not all models support `fast`; invalid
+   * combinations are rejected at create time.
+   */
+  speed?: 'standard' | 'fast' | null;
+}
+
+/**
+ * Resolved coordinator topology with a concrete agent roster.
+ */
+export interface BetaManagedAgentsMultiagentCoordinator {
+  /**
+   * Agents the coordinator may spawn as session threads, each resolved to a specific
+   * version.
+   */
+  agents: Array<BetaManagedAgentsAgentReference>;
+
+  type: 'coordinator';
+}
+
+/**
+ * A coordinator topology: the session's primary thread orchestrates work by
+ * spawning session threads, each running an agent drawn from the `agents` roster.
+ */
+export interface BetaManagedAgentsMultiagentCoordinatorParams {
+  /**
+   * Agents the coordinator may spawn as session threads. 1–20 entries. Each entry is
+   * an agent ID string, a versioned `{"type":"agent","id","version"}` reference, or
+   * `{"type":"self"}` to allow recursive self-invocation. Entries must reference
+   * distinct agents (after resolving `self` and string forms); at most one `self`.
+   * Referenced agents must exist, must not be archived, and must not themselves have
+   * `multiagent` set (depth limit 1).
+   */
+  agents: Array<SessionsAPI.BetaManagedAgentsMultiagentRosterEntryParams>;
+
+  type: 'coordinator';
+}
+
+/**
+ * Sentinel roster entry meaning "the agent that owns this configuration". Resolved
+ * server-side to a concrete agent reference.
+ */
+export interface BetaManagedAgentsMultiagentSelfParams {
+  type: 'self';
+}
+
+/**
+ * Resolved `agent` definition for a single `session_thread`. Snapshot of the agent
+ * at thread creation time. The multiagent roster is not repeated here; read it
+ * from `Session.agent`.
+ */
+export interface BetaManagedAgentsSessionThreadAgent {
+  id: string;
+
+  description: string | null;
+
+  mcp_servers: Array<BetaManagedAgentsMCPServerURLDefinition>;
+
+  /**
+   * Resolved approval mode for tool use.
+   */
+  approval_mode: AgentApprovalMode;
+
+  /**
+   * Model identifier and configuration.
+   */
+  model: BetaManagedAgentsModelConfig;
+
+  name: string;
+
+  skills: Array<BetaManagedAgentsAnthropicSkill | BetaManagedAgentsCustomSkill>;
+
+  system: string | null;
+
+  tools: Array<
+    | BetaManagedAgentsTetralAgentToolset
+    | BetaManagedAgentsAgentToolset20260401
+    | BetaManagedAgentsMCPToolset
+    | BetaManagedAgentsCustomTool
+  >;
+
+  type: 'agent';
+
+  version: number;
+}
+
+/**
+ * Skill to load in the session container.
+ */
+export type BetaManagedAgentsSkillParams =
+  | BetaManagedAgentsAnthropicSkillParams
+  | BetaManagedAgentsCustomSkillParams;
+
+/**
+ * URL-based MCP server connection.
+ */
+export interface BetaManagedAgentsURLMCPServerParams {
+  /**
+   * Unique name for this server, referenced by mcp_toolset configurations. 1-255
+   * characters.
+   */
+  name: string;
+
+  type: 'url';
+
+  /**
+   * Endpoint URL for the MCP server.
+   */
+  url: string;
+}
+
+export interface AgentCreateParams {
+  /**
+   * Body param: Model identifier. Tetral model IDs use canonical `provider/model`
+   * form and are limited to the supported Tetral Agent model set, or a
+   * `model_config` object for additional configuration control.
+   */
+  model: BetaManagedAgentsModel | BetaManagedAgentsModelConfigParams;
+
+  /**
+   * Body param: Human-readable name for the agent.
+   */
+  name: string;
+
+  /**
+   * Body param: Tool approval mode. Omit to let the backend resolve the default to
+   * `ask_for_approval`.
+   */
+  approval_mode?: AgentApprovalMode;
+
+  /**
+   * Body param: Description of what the agent does.
+   */
+  description?: string | null;
+
+  /**
+   * Body param: MCP servers this agent connects to. Maximum 20. Names must be unique
+   * within the array. Every server must be referenced by an `mcp_toolset` in
+   * `tools`; unreferenced servers are rejected. See the
+   * [MCP connector guide](https://platform.claude.com/docs/en/managed-agents/mcp-connector).
+   */
+  mcp_servers?: Array<BetaManagedAgentsURLMCPServerParams>;
+
+  /**
+   * Body param: Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars,
+   * values up to 512 chars.
+   */
+  metadata?: { [key: string]: string };
+
+  /**
+   * Body param: A coordinator topology: the session's primary thread orchestrates
+   * work by spawning session threads, each running an agent drawn from the
+   * `agents` roster. Tetral supports omitted or `null` in this stage; non-null
+   * coordinator topology is retained as an unsupported compatibility surface and
+   * rejected by backend admission.
+   */
+  multiagent?: SessionsAPI.BetaManagedAgentsMultiagentParams | null;
+
+  /**
+   * Body param: Skills available to the agent.
+   */
+  skills?: Array<BetaManagedAgentsSkillParams>;
+
+  /**
+   * Body param: System prompt for the agent.
+   */
+  system?: string | null;
+
+  /**
+   * Body param: Tool configurations available to the agent. Maximum of 128 tools
+   * across all toolsets allowed. Tetral supports `tetral_agent_toolset` with an
+   * explicit `family` and supported `mcp_toolset` declarations. Legacy
+   * `agent_toolset_20260401` and `custom` tool params remain assignable for
+   * compatibility but are rejected by Tetral in this stage.
+   */
+  tools?: Array<
+    | BetaManagedAgentsTetralAgentToolsetParams
+    | BetaManagedAgentsAgentToolset20260401Params
+    | BetaManagedAgentsMCPToolsetParams
+    | BetaManagedAgentsCustomToolParams
+  >;
+
+  /**
+   * Header param: Optional header to specify the beta version(s) you want to use.
+   */
+  betas?: Array<BetaAPI.AnthropicBeta>;
+}
+
+export interface AgentRetrieveParams {
+  /**
+   * Query param: Agent version. Omit for the most recent version. Must be at least 1
+   * if specified.
+   */
+  version?: number;
+
+  /**
+   * Header param: Optional header to specify the beta version(s) you want to use.
+   */
+  betas?: Array<BetaAPI.AnthropicBeta>;
+}
+
+export interface AgentUpdateParams {
+  /**
+   * Body param: The agent's current version, used to prevent concurrent overwrites.
+   * Obtain this value from a create or retrieve response. The request fails if this
+   * does not match the server's current version.
+   */
+  version: number;
+
+  /**
+   * Body param: Tool approval mode. Omit to preserve the current approval mode.
+   */
+  approval_mode?: AgentApprovalMode;
+
+  /**
+   * Body param: Description. Omit to preserve; send empty string or null to clear.
+   */
+  description?: string | null;
+
+  /**
+   * Body param: MCP servers. Full replacement. Omit to preserve; send empty array or
+   * `null` to clear. Names must be unique. Maximum 20. Every server must be
+   * referenced by an `mcp_toolset` in the agent's resulting `tools`; unreferenced
+   * servers are rejected. See the
+   * [MCP connector guide](https://platform.claude.com/docs/en/managed-agents/mcp-connector).
+   */
+  mcp_servers?: Array<BetaManagedAgentsURLMCPServerParams> | null;
+
+  /**
+   * Body param: Metadata patch. Set a key to a string to upsert it, or to null to
+   * delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up
+   * to 64 chars each) with values up to 512 chars.
+   */
+  metadata?: { [key: string]: string | null } | null;
+
+  /**
+   * Body param: Model identifier. Tetral model IDs use canonical `provider/model`
+   * form and are limited to the supported Tetral Agent model set, or a
+   * `model_config` object for additional configuration control. Omit to
+   * preserve. Cannot be cleared.
+   */
+  model?: BetaManagedAgentsModel | BetaManagedAgentsModelConfigParams;
+
+  /**
+   * Body param: A coordinator topology: the session's primary thread orchestrates
+   * work by spawning session threads, each running an agent drawn from the
+   * `agents` roster. Tetral supports omitted or `null` in this stage; non-null
+   * coordinator topology is retained as an unsupported compatibility surface and
+   * rejected by backend admission.
+   */
+  multiagent?: SessionsAPI.BetaManagedAgentsMultiagentParams | null;
+
+  /**
+   * Body param: Human-readable name. Must be non-empty. Omit to preserve. Cannot be
+   * cleared.
+   */
+  name?: string;
+
+  /**
+   * Body param: Skills. Full replacement. Omit to preserve; send empty array or null
+   * to clear.
+   */
+  skills?: Array<BetaManagedAgentsSkillParams> | null;
+
+  /**
+   * Body param: System prompt. Omit to preserve; send empty string or null to clear.
+   */
+  system?: string | null;
+
+  /**
+   * Body param: Tool configurations available to the agent. Full replacement. Omit
+   * to preserve; send empty array or null to clear. Maximum of 128 tools across all
+   * toolsets allowed. Tetral supports `tetral_agent_toolset` with an explicit
+   * `family` and supported `mcp_toolset` declarations. Legacy
+   * `agent_toolset_20260401` and `custom` tool params remain assignable for
+   * compatibility but are rejected by Tetral in this stage.
+   */
+  tools?: Array<
+    | BetaManagedAgentsTetralAgentToolsetParams
+    | BetaManagedAgentsAgentToolset20260401Params
+    | BetaManagedAgentsMCPToolsetParams
+    | BetaManagedAgentsCustomToolParams
+  > | null;
+
+  /**
+   * Header param: Optional header to specify the beta version(s) you want to use.
+   */
+  betas?: Array<BetaAPI.AnthropicBeta>;
+}
+
+export interface AgentListParams extends PageCursorParams {
+  /**
+   * Query param: Return agents created at or after this time (inclusive).
+   */
+  'created_at[gte]'?: string;
+
+  /**
+   * Query param: Return agents created at or before this time (inclusive).
+   */
+  'created_at[lte]'?: string;
+
+  /**
+   * Query param: Include archived agents in results. Defaults to false.
+   */
+  include_archived?: boolean;
+
+  /**
+   * Header param: Optional header to specify the beta version(s) you want to use.
+   */
+  betas?: Array<BetaAPI.AnthropicBeta>;
+}
+
+export interface AgentArchiveParams {
+  /**
+   * Optional header to specify the beta version(s) you want to use.
+   */
+  betas?: Array<BetaAPI.AnthropicBeta>;
+}
+
+Agents.Versions = Versions;
+
+export declare namespace Agents {
+  export {
+    type BetaManagedAgentsAgent as BetaManagedAgentsAgent,
+    type BetaManagedAgentsAgentReference as BetaManagedAgentsAgentReference,
+    type BetaManagedAgentsAgentToolConfig as BetaManagedAgentsAgentToolConfig,
+    type BetaManagedAgentsAgentToolConfigParams as BetaManagedAgentsAgentToolConfigParams,
+    type BetaManagedAgentsAgentToolsetDefaultConfig as BetaManagedAgentsAgentToolsetDefaultConfig,
+    type BetaManagedAgentsAgentToolsetDefaultConfigParams as BetaManagedAgentsAgentToolsetDefaultConfigParams,
+    type AgentApprovalMode as AgentApprovalMode,
+    type BetaManagedAgentsTetralAgentToolset as BetaManagedAgentsTetralAgentToolset,
+    type BetaManagedAgentsTetralAgentToolsetParams as BetaManagedAgentsTetralAgentToolsetParams,
+    type BetaManagedAgentsTetralClaudeAgentToolset as BetaManagedAgentsTetralClaudeAgentToolset,
+    type BetaManagedAgentsTetralClaudeAgentToolsetParams as BetaManagedAgentsTetralClaudeAgentToolsetParams,
+    type BetaManagedAgentsTetralClaudeToolConfig as BetaManagedAgentsTetralClaudeToolConfig,
+    type BetaManagedAgentsTetralClaudeToolConfigParams as BetaManagedAgentsTetralClaudeToolConfigParams,
+    type BetaManagedAgentsTetralClaudeToolName as BetaManagedAgentsTetralClaudeToolName,
+    type BetaManagedAgentsTetralGPTAgentToolset as BetaManagedAgentsTetralGPTAgentToolset,
+    type BetaManagedAgentsTetralGPTAgentToolsetParams as BetaManagedAgentsTetralGPTAgentToolsetParams,
+    type BetaManagedAgentsTetralGPTToolConfig as BetaManagedAgentsTetralGPTToolConfig,
+    type BetaManagedAgentsTetralGPTToolConfigParams as BetaManagedAgentsTetralGPTToolConfigParams,
+    type BetaManagedAgentsTetralGPTToolName as BetaManagedAgentsTetralGPTToolName,
+    type BetaManagedAgentsTetralPlatformToolName as BetaManagedAgentsTetralPlatformToolName,
+    type BetaManagedAgentsAgentToolset20260401 as BetaManagedAgentsAgentToolset20260401,
+    type BetaManagedAgentsAgentToolset20260401BashInput as BetaManagedAgentsAgentToolset20260401BashInput,
+    type BetaManagedAgentsAgentToolset20260401EditInput as BetaManagedAgentsAgentToolset20260401EditInput,
+    type BetaManagedAgentsAgentToolset20260401GlobInput as BetaManagedAgentsAgentToolset20260401GlobInput,
+    type BetaManagedAgentsAgentToolset20260401GrepInput as BetaManagedAgentsAgentToolset20260401GrepInput,
+    type BetaManagedAgentsAgentToolset20260401Params as BetaManagedAgentsAgentToolset20260401Params,
+    type BetaManagedAgentsAgentToolset20260401ReadInput as BetaManagedAgentsAgentToolset20260401ReadInput,
+    type BetaManagedAgentsAgentToolset20260401WriteInput as BetaManagedAgentsAgentToolset20260401WriteInput,
+    type BetaManagedAgentsAlwaysAllowPolicy as BetaManagedAgentsAlwaysAllowPolicy,
+    type BetaManagedAgentsAlwaysAskPolicy as BetaManagedAgentsAlwaysAskPolicy,
+    type BetaManagedAgentsAnthropicSkill as BetaManagedAgentsAnthropicSkill,
+    type BetaManagedAgentsAnthropicSkillParams as BetaManagedAgentsAnthropicSkillParams,
+    type BetaManagedAgentsCustomSkill as BetaManagedAgentsCustomSkill,
+    type BetaManagedAgentsCustomSkillParams as BetaManagedAgentsCustomSkillParams,
+    type BetaManagedAgentsCustomTool as BetaManagedAgentsCustomTool,
+    type BetaManagedAgentsCustomToolInputSchema as BetaManagedAgentsCustomToolInputSchema,
+    type BetaManagedAgentsCustomToolParams as BetaManagedAgentsCustomToolParams,
+    type BetaManagedAgentsMCPServerURLDefinition as BetaManagedAgentsMCPServerURLDefinition,
+    type BetaManagedAgentsMCPToolConfig as BetaManagedAgentsMCPToolConfig,
+    type BetaManagedAgentsMCPToolConfigParams as BetaManagedAgentsMCPToolConfigParams,
+    type BetaManagedAgentsMCPToolset as BetaManagedAgentsMCPToolset,
+    type BetaManagedAgentsMCPToolsetDefaultConfig as BetaManagedAgentsMCPToolsetDefaultConfig,
+    type BetaManagedAgentsMCPToolsetDefaultConfigParams as BetaManagedAgentsMCPToolsetDefaultConfigParams,
+    type BetaManagedAgentsMCPToolsetParams as BetaManagedAgentsMCPToolsetParams,
+    type BetaManagedAgentsModel as BetaManagedAgentsModel,
+    type BetaManagedAgentsModelConfig as BetaManagedAgentsModelConfig,
+    type BetaManagedAgentsModelConfigParams as BetaManagedAgentsModelConfigParams,
+    type BetaManagedAgentsMultiagentCoordinator as BetaManagedAgentsMultiagentCoordinator,
+    type BetaManagedAgentsMultiagentCoordinatorParams as BetaManagedAgentsMultiagentCoordinatorParams,
+    type BetaManagedAgentsMultiagentSelfParams as BetaManagedAgentsMultiagentSelfParams,
+    type BetaManagedAgentsSessionThreadAgent as BetaManagedAgentsSessionThreadAgent,
+    type BetaManagedAgentsSkillParams as BetaManagedAgentsSkillParams,
+    type BetaManagedAgentsURLMCPServerParams as BetaManagedAgentsURLMCPServerParams,
+    type BetaManagedAgentsAgentsPageCursor as BetaManagedAgentsAgentsPageCursor,
+    type AgentCreateParams as AgentCreateParams,
+    type AgentRetrieveParams as AgentRetrieveParams,
+    type AgentUpdateParams as AgentUpdateParams,
+    type AgentListParams as AgentListParams,
+    type AgentArchiveParams as AgentArchiveParams,
+  };
+
+  export { Versions as Versions, type VersionListParams as VersionListParams };
+}