Claude Platform Docs

Create Session

client.Beta.Sessions.New(ctx, params) (*BetaManagedAgentsSession, error)
POST/v1/sessions

Create Session

Parameters
params BetaSessionNewParams
Agent param.Field[BetaSessionNewParamsAgentUnion]

Body param: Agent identifier. Accepts the agent ID string, which pins the latest version for the session, or an agent object with both id and version specified.

string
type BetaManagedAgentsAgentParamsResp struct{…}

Specification for an Agent. Provide a specific version or use the short-form agent="agent_id" for the most recent version

Type BetaManagedAgentsAgentParamsType
ID string

The agent ID.

minLength1
maxLength128
Version int64 Optional

The specific agent version to use. Omit to use the latest version. Must be at least 1 if specified.

formatint32
type BetaManagedAgentsAgentWithOverridesParamsResp struct{…}

Reference to an agent plus optional configuration overrides. Each provided field replaces the agent's value for the caller's use; the agent resource is unchanged.

EnvironmentID param.Field[string]

Body param: ID of the environment defining the container configuration for this session.

minLength1
maxLength128
Budget param.Field[BetaManagedAgentsBudgetLimit] Optional

Body param: A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches max_list_cost.

InitialEvents param.Field[[]BetaSessionNewParamsInitialEventUnion] Optional

Body param: Initial events to send to the session at creation, processed in order. Supports user.message and user.define_outcome events. Maximum 50 events.

type BetaManagedAgentsUserMessageEventParams struct{…}

Parameters for sending a user message to the session.

type BetaManagedAgentsUserDefineOutcomeEventParams struct{…}

Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.

Type BetaManagedAgentsUserDefineOutcomeEventParamsType
Description string

What the agent should produce. This is the task specification.

Rubric BetaManagedAgentsUserDefineOutcomeEventParamsRubricUnionResp

Rubric for grading the quality of an outcome.

One of the following:
type BetaManagedAgentsFileRubricParams struct{…}

Rubric referenced by a file uploaded via the Files API.

Type BetaManagedAgentsFileRubricParamsType
FileID string

ID of the rubric file.

type BetaManagedAgentsTextRubricParams struct{…}

Rubric content provided inline as text.

Type BetaManagedAgentsTextRubricParamsType
Content string

Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.

maxLength262144
MaxIterations int64 Optional

Eval→revision cycles before giving up. Default 3, max 20.

formatint32
Metadata param.Field[map[string, string]] Optional

Body param: Arbitrary key-value metadata attached to the session. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.

Resources param.Field[[]BetaSessionNewParamsResourceUnion] Optional

Body param: Resources (e.g. repositories, files) to mount into the session's container.

type BetaManagedAgentsGitHubRepositoryResourceParamsResp struct{…}

Mount a GitHub repository into the session's container.

Type BetaManagedAgentsGitHubRepositoryResourceParamsType
URL string

Github URL of the repository

minLength1
maxLength2048
AuthorizationToken string Optional

GitHub authorization token used to clone the repository. Required for private repositories; optional for public ones.

minLength1
maxLength4096
Checkout BetaManagedAgentsGitHubRepositoryResourceParamsCheckoutUnionResp Optional

Branch or commit to check out. Defaults to the repository's default branch.

One of the following:
type BetaManagedAgentsBranchCheckout struct{…}
Type BetaManagedAgentsBranchCheckoutType
Name string

Branch name to check out.

minLength1
maxLength255
type BetaManagedAgentsCommitCheckout struct{…}
Type BetaManagedAgentsCommitCheckoutType
Sha string

Full commit SHA to check out.

minLength7
maxLength64
MountPath string Optional

Mount path in the container. Defaults to /workspace/<repo-name>.

minLength1
maxLength4096
type BetaManagedAgentsFileResourceParamsResp struct{…}

Mount a file uploaded via the Files API into the session.

Type BetaManagedAgentsFileResourceParamsType
FileID string

ID of a previously uploaded file.

minLength1
maxLength128
MountPath string Optional

Mount path in the container. Defaults to /mnt/session/uploads/<file_id>.

minLength1
maxLength4096
type BetaManagedAgentsMemoryStoreResourceParamResp struct{…}

Parameters for attaching a memory store to an agent session.

Type BetaManagedAgentsMemoryStoreResourceParamType
MemoryStoreID string

The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

Access BetaManagedAgentsMemoryStoreResourceParamAccess Optional

Access mode for an attached memory store.

One of the following:
const BetaManagedAgentsMemoryStoreResourceParamAccessReadWrite BetaManagedAgentsMemoryStoreResourceParamAccess = "read_write"
const BetaManagedAgentsMemoryStoreResourceParamAccessReadOnly BetaManagedAgentsMemoryStoreResourceParamAccess = "read_only"
Instructions string Optional

Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

maxLength4096
Title param.Field[string] Optional

Body param: Human-readable session title.

maxLength500
VaultIDs param.Field[[]string] Optional

Body param: Vault IDs for stored credentials the agent can use during the session.

Betas param.Field[[]AnthropicBeta] Optional

Header param: Optional header to specify the beta version(s) you want to use.

string
type AnthropicBeta string
One of the following:
const AnthropicBetaMessageBatches2024_09_24 AnthropicBeta = "message-batches-2024-09-24"
const AnthropicBetaPromptCaching2024_07_31 AnthropicBeta = "prompt-caching-2024-07-31"
const AnthropicBetaComputerUse2024_10_22 AnthropicBeta = "computer-use-2024-10-22"
const AnthropicBetaComputerUse2025_01_24 AnthropicBeta = "computer-use-2025-01-24"
const AnthropicBetaPDFs2024_09_25 AnthropicBeta = "pdfs-2024-09-25"
const AnthropicBetaTokenCounting2024_11_01 AnthropicBeta = "token-counting-2024-11-01"
const AnthropicBetaTokenEfficientTools2025_02_19 AnthropicBeta = "token-efficient-tools-2025-02-19"
const AnthropicBetaOutput128k2025_02_19 AnthropicBeta = "output-128k-2025-02-19"
const AnthropicBetaFilesAPI2025_04_14 AnthropicBeta = "files-api-2025-04-14"
const AnthropicBetaMCPClient2025_04_04 AnthropicBeta = "mcp-client-2025-04-04"
const AnthropicBetaMCPClient2025_11_20 AnthropicBeta = "mcp-client-2025-11-20"
const AnthropicBetaDevFullThinking2025_05_14 AnthropicBeta = "dev-full-thinking-2025-05-14"
const AnthropicBetaInterleavedThinking2025_05_14 AnthropicBeta = "interleaved-thinking-2025-05-14"
const AnthropicBetaCodeExecution2025_05_22 AnthropicBeta = "code-execution-2025-05-22"
const AnthropicBetaExtendedCacheTTL2025_04_11 AnthropicBeta = "extended-cache-ttl-2025-04-11"
const AnthropicBetaContext1m2025_08_07 AnthropicBeta = "context-1m-2025-08-07"
const AnthropicBetaContextManagement2025_06_27 AnthropicBeta = "context-management-2025-06-27"
const AnthropicBetaModelContextWindowExceeded2025_08_26 AnthropicBeta = "model-context-window-exceeded-2025-08-26"
const AnthropicBetaSkills2025_10_02 AnthropicBeta = "skills-2025-10-02"
const AnthropicBetaFastMode2026_02_01 AnthropicBeta = "fast-mode-2026-02-01"
const AnthropicBetaOutput300k2026_03_24 AnthropicBeta = "output-300k-2026-03-24"
const AnthropicBetaUserProfiles2026_03_24 AnthropicBeta = "user-profiles-2026-03-24"
const AnthropicBetaUserProfiles2026_08_18 AnthropicBeta = "user-profiles-2026-08-18"
const AnthropicBetaUserProfiles2026_09_04 AnthropicBeta = "user-profiles-2026-09-04"
const AnthropicBetaAdvisorTool2026_03_01 AnthropicBeta = "advisor-tool-2026-03-01"
const AnthropicBetaManagedAgents2026_04_01 AnthropicBeta = "managed-agents-2026-04-01"
const AnthropicBetaCacheDiagnosis2026_04_07 AnthropicBeta = "cache-diagnosis-2026-04-07"
const AnthropicBetaDreaming2026_04_21 AnthropicBeta = "dreaming-2026-04-21"
const AnthropicBetaThinkingTokenCount2026_05_13 AnthropicBeta = "thinking-token-count-2026-05-13"
const AnthropicBetaServerSideFallback2026_06_01 AnthropicBeta = "server-side-fallback-2026-06-01"
const AnthropicBetaServerSideFallback2026_07_01 AnthropicBeta = "server-side-fallback-2026-07-01"
const AnthropicBetaFallbackCredit2026_06_01 AnthropicBeta = "fallback-credit-2026-06-01"
const AnthropicBetaFallbackCredit2026_07_01 AnthropicBeta = "fallback-credit-2026-07-01"
const AnthropicBetaAgentMemory2026_07_22 AnthropicBeta = "agent-memory-2026-07-22"
const AnthropicBetaMidConversationToolChanges2026_07_01 AnthropicBeta = "mid-conversation-tool-changes-2026-07-01"
const AnthropicBetaCompact2026_01_12 AnthropicBeta = "compact-2026-01-12"
const AnthropicBetaComputerUse2025_11_24 AnthropicBeta = "computer-use-2025-11-24"
const AnthropicBetaMCPTunnels2026_06_22 AnthropicBeta = "mcp-tunnels-2026-06-22"
const AnthropicBetaStructuredOutputs2025_11_13 AnthropicBeta = "structured-outputs-2025-11-13"
const AnthropicBetaTaskBudgets2026_03_13 AnthropicBeta = "task-budgets-2026-03-13"
const AnthropicBetaThinkingDisplayUpdates2026_08_18 AnthropicBeta = "thinking-display-updates-2026-08-18"
const AnthropicBetaCEUserManagement2026_07_13 AnthropicBeta = "ce-user-management-2026-07-13"
const AnthropicBetaMidConversationOutputConfig2026_07_01 AnthropicBeta = "mid-conversation-output-config-2026-07-01"
const AnthropicBetaThinkingBindingControls2026_08_01 AnthropicBeta = "thinking-binding-controls-2026-08-01"
const AnthropicBetaMidConversationSystemClearAt2026_08_21 AnthropicBeta = "mid-conversation-system-clear-at-2026-08-21"
WorkspaceID param.Field[string] Optional

Header param: Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).

Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.

Returns
type BetaManagedAgentsSession struct{…}

A Managed Agents session.

Create Session
package main

import (
	"context"
	"fmt"

	"github.com/anthropics/anthropic-sdk-go"
	"github.com/anthropics/anthropic-sdk-go/option"
)

func main() {
	client := anthropic.NewClient(
		option.WithAPIKey("my-anthropic-api-key"),
	)
	betaManagedAgentsSession, err := client.Beta.Sessions.New(context.TODO(), anthropic.BetaSessionNewParams{
		Agent: anthropic.BetaSessionNewParamsAgentUnion{
			OfString: anthropic.String("agent_011CZkYpogX7uDKUyvBTophP"),
		},
		EnvironmentID: "env_011CZkZ9X2dpNyB7HsEFoRfW",
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", betaManagedAgentsSession.ID)
}
Returns Examples
Response 200
{
  "id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
  "agent": {
    "id": "agent_011CZkYpogX7uDKUyvBTophP",
    "description": "A general-purpose starter agent.",
    "mcp_servers": [
      {
        "name": "example-mcp",
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse"
      }
    ],
    "model": {
      "id": "claude-opus-5",
      "effort": {
        "type": "low"
      },
      "inference_geo": "inference_geo",
      "speed": "standard"
    },
    "multiagent": {
      "agents": [
        {
          "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
          "description": "A focused research subagent.",
          "mcp_servers": [
            {
              "name": "example-mcp",
              "type": "url",
              "url": "https://example-server.modelcontextprotocol.io/sse"
            }
          ],
          "model": {
            "id": "claude-opus-5",
            "effort": {
              "type": "low"
            },
            "inference_geo": "inference_geo",
            "speed": "standard"
          },
          "name": "Researcher",
          "skills": [
            {
              "skill_id": "xlsx",
              "type": "anthropic",
              "version": "1"
            }
          ],
          "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.",
          "tools": [
            {
              "configs": [
                {
                  "enabled": true,
                  "name": "bash",
                  "permission_policy": {
                    "type": "always_allow"
                  },
                  "type": "bash"
                }
              ],
              "default_config": {
                "enabled": true,
                "permission_policy": {
                  "type": "always_ask"
                }
              },
              "type": "agent_toolset_20260401"
            }
          ],
          "type": "agent",
          "version": 1
        }
      ],
      "type": "coordinator"
    },
    "name": "My First Agent",
    "skills": [
      {
        "skill_id": "xlsx",
        "type": "anthropic",
        "version": "1"
      },
      {
        "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
        "type": "custom",
        "version": "2"
      }
    ],
    "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
    "tools": [
      {
        "configs": [
          {
            "enabled": true,
            "name": "bash",
            "permission_policy": {
              "type": "always_allow"
            },
            "type": "bash"
          }
        ],
        "default_config": {
          "enabled": true,
          "permission_policy": {
            "type": "always_ask"
          }
        },
        "type": "agent_toolset_20260401"
      }
    ],
    "type": "agent",
    "version": 1
  },
  "archived_at": null,
  "budget": {
    "max_list_cost": {
      "amount": "2500",
      "currency": "USD"
    },
    "type": "limit"
  },
  "created_at": "2026-03-15T10:00:00Z",
  "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
  "metadata": {},
  "outcome_evaluations": [
    {
      "completed_at": "2026-03-15T10:02:31Z",
      "description": "Produce a 2-page summary as summary.md",
      "explanation": "All five sections present with inline citations.",
      "iteration": 0,
      "outcome_id": "outc_011CZkZRSw2kEfs6ncTVljxP",
      "result": "satisfied",
      "type": "outcome_evaluation"
    }
  ],
  "resources": [
    {
      "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht",
      "created_at": "2026-03-15T10:00:00Z",
      "file_id": "file_011CNha8iCJcU1wXNR6q4V8w",
      "mount_path": "/uploads/receipt.pdf",
      "type": "file",
      "updated_at": "2026-03-15T10:00:00Z"
    },
    {
      "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu",
      "created_at": "2026-03-15T10:00:00Z",
      "mount_path": "/workspace/example-repo",
      "type": "github_repository",
      "updated_at": "2026-03-15T10:00:00Z",
      "url": "https://github.com/example-org/example-repo",
      "checkout": {
        "name": "main",
        "type": "branch"
      }
    }
  ],
  "stats": {
    "active_seconds": 0,
    "duration_seconds": 0
  },
  "status": "idle",
  "title": "Order #1234 inquiry",
  "type": "session",
  "updated_at": "2026-03-15T10:00:00Z",
  "usage": {
    "active_seconds": 0,
    "cache_creation": {
      "ephemeral_1h_input_tokens": 0,
      "ephemeral_5m_input_tokens": 0
    },
    "cache_read_input_tokens": 0,
    "input_tokens": 0,
    "list_cost": {
      "amount": "2500",
      "currency": "USD"
    },
    "output_tokens": 0,
    "server_tool_use": {
      "web_fetch_requests": 0,
      "web_search_requests": 3
    }
  },
  "vault_ids": [
    "vlt_011CZkZDLs7fYzm1hXNPeRjv"
  ],
  "deployment_id": "deployment_id"
}