--- title: pydo.sessions.create() description: Create a Session product: Reference url: https://docs.digitalocean.com/reference/pydo/reference/sessions/create/ last_updated: "2026-10-16" --- > **For AI agents:** The documentation index is at [https://docs.digitalocean.com/llms.txt](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). # pydo.sessions.create() Generated on 16 Oct 2026 from `pydo` version [`v0.44.0`](https://github.com/digitalocean/pydo/releases/tag/v0.44.0v0.44.0) ## Usage ```python client.sessions.create( body={ "name": "support-bot-alice", "actorId": "alice", "policy": {...}, ..., }, ) ``` Returns `JSON` Raises `HttpResponseError` ## 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 `@`, or a toolbelt as `toolbelt:@`. 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 `` or `@`, using provider-qualified tool slugs, and a pinned version must be the released one; toolbelt references must be version-pinned as `toolbelt:@`. `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 ## Show Request Sample ```python 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 ## Show Response Example ```json { "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`](https://docs.digitalocean.com/reference/api/reference/action-gateway/index.html.md#sessions_create) in the API reference for additional detail on responses, headers, parameters, and more.