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).

Use Action Gateway to give a production agent the tools its workflow needs without granting access to the entire catalog. An All tools session supports open-ended tasks. For a known workflow, select specific tools, define their permissions, and control how the agent discovers them and consumes their results.

These controls make tool use more predictable, but do not make model decisions deterministic. Put fixed tool calls and step ordering in application code when the workflow must follow a known sequence.

Prerequisites

• Access to Action Gateway and a working client connection.
• A development environment where you can test tools without changing production resources.

Restrict the Session’s Tools and Permissions

Start with one workflow. For example, a capacity-planning agent might read Droplet sizes and inventory to recommend a configuration, without permission to create or delete Droplets.

Use Tool Playground during development to inspect the tools’ names, arguments, and results. When creating the production session:

1. Choose Selected tools instead of All tools and include only the operations the workflow needs.
2. Set Default Action to Deny.
3. Set Allow for reviewed calls that can run unattended. Use Ask only where a person can complete the approval flow.
4. Leave unrelated operations out of the selection. An approval or an allow rule cannot authorize a tool outside that selection.

Use a versioned Toolbelt to reuse an approved group across sessions. Review its members before adopting a new version. Session instructions can describe the workflow, but only tool selection and policy enforce tool access.

If your agent uses action_search, action_invoke, or action_code, allow the required meta tools as well. Their catalog calls still obey the selected-tool policy.

Preload Known Tools and Limit Runtime Discovery

Enable Preload for the small set of tools the agent regularly uses. Their definitions are available immediately, so the model can call them without first searching. Preloading reduces discovery calls, but adds definitions to model context even when a task does not use them.

Keep Tool Search available when the agent needs to choose among the session’s permitted tools. For a fixed workflow, preload the required tools and omit search access. Preloading alone does not restrict access; the session’s selection and policy do.

MCP clients receive preloaded definitions in the session’s tool list. With PyDo, use session.tools(include_all=True) when supplying those definitions to a model. The default session.tools() supplies the meta tools instead. See Preloading Tools.

Call Tools Directly for Fixed Workflow Steps

When your application already knows the tool and its arguments, call it from Python instead of asking a model to select it. Your code controls the call and its place in the workflow; the gateway still checks permissions and resolves provider credentials.

The following example creates a session that selects, allows, and preloads only the read-only Droplet sizes tool. It calls that tool without a model, search, or action_code execution.

Install PyDo in your Python environment:

pip install pydo

Make a DigitalOcean personal access token authorized for Action Gateway available as DIGITALOCEAN_TOKEN. Keep the token out of source control and agent conversations. Create capacity_planner.py with the following content, replacing <actor-id> with your application’s stable user identifier:

import os

from pydo.action_gateway import ActionGatewayClient

gateway = ActionGatewayClient(token=os.environ["DIGITALOCEAN_TOKEN"])
session = gateway.session.create(
    actor_id="<actor-id>",
    name="capacity-planner",
    tools=["digitalocean_size-list"],
    permissions={
        "default_action": "deny",
        "rules": [{"tool": "digitalocean_size-list", "action": "allow"}],
    },
    config={"preloadTools": ["digitalocean_size-list"]},
)

sizes = session.tools.call("digitalocean_size-list", {})
print(sizes)

Run the example to create the session and retrieve the available sizes:

python capacity_planner.py

Each run creates a session. In your application, reuse the session for subsequent calls in the workflow. Handle invocation errors before advancing to dependent steps, and send only the data needed for any later model decision.

For agent-written Python workflows, use the Code Execution Tool. It runs code in a temporary sandbox and can combine tool calls and filter intermediate results before returning a summary to the model. It does not make generated code deterministic or bypass the session’s permissions.

Return Only the Fields the Workflow Needs

Create an output view for each tool with a supported output schema. Keep the fields needed for the next decision. For a capacity-planning workflow, those might include size, memory, and price information rather than every provider field.

When creating the session, choose the view in the tool’s Output view control instead of Full output. The view applies to direct calls, action_invoke, and calls inside action_code. Test downstream code against this reduced output shape, including empty results and missing optional fields.

Views reduce result data and can lower model-token costs; they do not change the provider operation, credential scopes, or invocation charges. The Python example uses full output and does not require an output view.

Authorize Accounts Before Unattended Runs

Authorize provider connections before deploying a workload that cannot pause for sign-in. Create the connection and session as the same DigitalOcean user, in the same team, with the same actor ID. Limit the credential’s scopes in the provider itself; gateway policy does not reduce those scopes.

For agents serving multiple users, derive the actor ID from your application’s authenticated user. Do not let a caller select another user’s actor ID. Use different actors for different accounts at the same provider, and handle expired or revoked authorization separately from tool approval.

Test and Deploy the Configuration

Before deploying, verify that:

• Required calls succeed, while calls outside the selected tools or policy fail. Test restrictions in a development environment without attempting unwanted production writes.
• The session uses the intended provider accounts and returns the output fields your application expects.
• The application handles denied calls, unavailable connections, rate limits, timeouts, and partial failures without treating them as successful results.
• Write recovery checks provider state before resubmitting an operation. Automatic retries do not make a new invocation safe to repeat or a multi-tool workflow transactional.

Keep the tool selection, policy, preloads, and output-view bindings in your deployment configuration. Create a replacement session when those settings change, test it, and update the application or MCP client to use it. Check view compatibility when changing tool versions.

Monitor errors, latency, and calls in Action Gateway Insights. Review pricing for tool invocation, code execution, and paid provider tools before scaling the workload.

For complete session configurations that apply these controls, use the web research assistant or Jira issue triage examples.