For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

Usage

client.sessions.create(
    body={
        "name": "support-bot-alice",
        "actorId": "alice",
        "policy": {...},
        ...,
    },
)

Description

Creates a session owned by your team, with a new session URN, and returns the MCP URL an agent connects to. tools selects the tools and toolbelts the session exposes, and policy decides which calls run, need approval, or are refused.

Parameters

name string required

Example: support-bot-alice

Required human-readable session name.

actorId string optional

Example: alice

Optional actor binding: the user whose connections the session's tool calls use, matched against connection user_id. When set it must use the same alphabet as a connection's user_id, [A-Za-z0-9._-], at most 64 characters; anything else is rejected with 400.

policy object optional

Optional tool-permission policy. Omitted asks before every call.

Show child properties

defaultAction string optional

Action for calls no rule matches. Empty means ask; otherwise this must be allow, ask, or deny.

One of: allow, ask, deny

rules array of objects optional

Rules for specific tools or toolbelts.

Show child properties

tool string optional

Example: exa_web_search

Required. A tool slug, optionally <tool_slug>@<version>, or a toolbelt as toolbelt:<name>@<version>. When the session selects tools, the rule must name one of them.

match object optional

Example: {}

Optional argument conditions, keyed by argument name; the rule applies only to calls whose arguments match.

action string optional

Required: allow, ask, or deny.

One of: allow, ask, deny

tools array of strings optional

Example: ['toolbelt:search-toolbelt@1', 'jira_create_issue']

Omitted enables every tool. An explicit empty array enables no tools. Direct tools may be <tool> or <tool>@<version>, using provider-qualified tool slugs, and a pinned version must be the released one; toolbelt references must be version-pinned as toolbelt:<belt-name>@<version>.

config object optional

Example: {'preloadTools': ['exa_web_search'], 'outputViews': {'exa_web_search': 'titles-and-urls'}, 'customInstructions': 'Prefer primary sources and cite URLs.'}

Optional session options. config.preloadTools may contain concrete tool names (optionally version-pinned) and version-pinned toolbelt references. config.customInstructions is a string of at most 1000 characters. config.outputViews maps up to 100 tool slugs to the name of an output view to apply to that tool's results.

network object optional

Product-level session network binding. When set, vpc_uuid must identify a VPC owned by the session's team.

Show child properties

vpcUuid string optional

Example: 5a4981aa-9653-4bd1-bef5-d6bff52042e4

UUID of a VPC owned by your team, in a region that supports sessions.

insights object optional

Omitted when the request omitted insights or explicitly sent null.

Show child properties

metrics boolean or null optional

Example: True

Accepted and stored for parity with the Insights schema.

logs boolean or null optional

Example: True

Whether the session's customer logs are sent to Insights.

traces boolean or null optional

Example: False

Whether the session's customer traces are sent to Insights.

Request Sample

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "name": "support-bot-alice",
  "actorId": "alice",
  "tools": [
    "toolbelt:search-toolbelt@1",
    "jira_create_issue"
  ],
  "policy": {
    "defaultAction": "ask",
    "rules": [
      {
        "tool": "toolbelt:search-toolbelt@1",
        "match": {},
        "action": "allow"
      },
      {
        "tool": "jira_create_issue",
        "match": {},
        "action": "ask"
      }
    ]
  },
  "config": {
    "preloadTools": [
      "exa_web_search"
    ],
    "outputViews": {
      "exa_web_search": "titles-and-urls"
    }
  }
}

resp = client.sessions.create(body=req)

Response Example

{
  "session": {
    "sessionUrn": "do:managed_agent_session:2b3c9f0e-1a4d-4e5f-8a7b-6c5d4e3f2a1b",
    "policy": {
      "defaultAction": "ask",
      "rules": [
        {
          "tool": "toolbelt:search-toolbelt@1",
          "match": {},
          "action": "allow"
        },
        {
          "tool": "jira_create_issue",
          "match": {},
          "action": "ask"
        }
      ]
    },
    "createdAt": "2026-09-24T12:00:00Z",
    "updatedAt": "2026-09-24T12:00:00Z",
    "name": "support-bot-alice",
    "actorId": "alice",
    "tools": {
      "references": [
        {
          "kind": "SESSION_TOOL_REFERENCE_KIND_TOOLBELT",
          "name": "search-toolbelt",
          "version": "1"
        },
        {
          "kind": "SESSION_TOOL_REFERENCE_KIND_TOOL",
          "name": "jira_create_issue",
          "version": "1"
        }
      ]
    },
    "config": {
      "preloadTools": [
        "exa_web_search"
      ],
      "outputViews": {
        "exa_web_search": "titles-and-urls"
      }
    },
    "agentUrn": "",
    "agentName": "",
    "owning_user_id": "2f8e1c3a-6b4d-4f7e-9a1c-5d3b7e9f1a2c"
  },
  "mcpUrl": "https://actions.do-ai.run/mcp/session/2b3c9f0e-1a4d-4e5f-8a7b-6c5d4e3f2a1b",
  "tools": [
    "toolbelt:search-toolbelt@1",
    "jira_create_issue@1"
  ]
}

More Information

See /v2/action-gateway/sessions in the API reference for additional detail on responses, headers, parameters, and more.