Quickstart

This example generates a client from the OpenAPI document, creates an agent for a user, and writes a file with the agent’s runtime token. Use an existing Dropbox user’s token or a token minted for a managed user.

Choose TypeScript or Python in the code switcher.

Before you begin

You need:

• An app enabled for the Agent Filesystem Private Preview. Follow Application Setup to create an Agent Filesystem application in the Developer Console.
• A user access token with the required file and Agent Filesystem scopes.
• Java 11 or later for OpenAPI Generator.
• Node.js 18 or later for TypeScript, or Python 3.10 or later for Python.

Download the Agent Filesystem OpenAPI document and save it as agentfs-openapi.yaml in your project.

Generate the client

These commands use OpenAPI Generator 7.26.0. Pin the generator version in your project so regenerated clients keep a predictable interface.

TypeScript

npm install --save-dev \
  @openapitools/openapi-generator-cli \
  @types/node \
  tsx \
  typescript
npx openapi-generator-cli version-manager set 7.26.0
npx openapi-generator-cli generate \
  -i agentfs-openapi.yaml \
  -g typescript-fetch \
  -o generated/agentfs \
  --additional-properties=npmName=agentfs-client
npm install ./generated/agentfs dropbox

Python

python3 -m pip install openapi-generator-cli==7.26.0
openapi-generator-cli generate \
  -i agentfs-openapi.yaml \
  -g python \
  -o generated/agentfs \
  --additional-properties=packageName=agentfs_client,projectName=agentfs-client,poetry1=true
python3 -m pip install ./generated/agentfs dropbox

Set the credentials

To test with your own Dropbox account, open your enabled app in My apps, find the OAuth 2 section of its settings, and click Generate. This creates a user access token for your account. To get a token for another user, follow the OAuth guide to connect them through your app.

For a managed user, follow the managed user flow to create the user and mint a token, then use that token below.

Set the resulting token in a trusted server-side environment:

export DROPBOX_USER_ACCESS_TOKEN='your-user-access-token'

Keep the user token in your trusted backend. Give the agent runtime only its short-lived agent token.

Run the example

import {
  AgentFilesystemApi,
  Configuration,
} from "agentfs-client";
import { Dropbox } from "dropbox";
function required(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Missing ${name}`);
  return value;
}
async function main(): Promise<void> {
  const userAccessToken = required("DROPBOX_USER_ACCESS_TOKEN");
  const sampleId = Date.now().toString(36);
  const userConfiguration = new Configuration({
    accessToken: userAccessToken,
  });
  const workspacePath = `/agentfs-sample-${sampleId}`;
  const userFiles = new Dropbox({ accessToken: userAccessToken });
  await userFiles.filesCreateFolderV2({
    path: workspacePath,
    autorename: false,
  });
  const agents = new AgentFilesystemApi(userConfiguration);
  const created = await agents.agentFilesystemAgentsCreate({
    agentFilesystemCreateAgentsArg: {
      entries: [{
        workspace: [{
          path: workspacePath,
          role: { tag: "read_write" },
        }],
      }],
    },
  });
  const agentId = created.agents[0].agentId;
  const runtime = await new AgentFilesystemApi(
    userConfiguration,
  ).agentFilesystemAgentsAccessTokenMint({
    agentFilesystemMintAgentAccessTokenArg: {
      agent: { tag: "agent_id", agentId },
      scope: "files.metadata.read files.content.write",
    },
  });
  const runtimeFiles = new Dropbox({ accessToken: runtime.accessToken });
  const uploadPath = `${workspacePath}/agent-result-${sampleId}.txt`;
  await runtimeFiles.filesUpload({
    path: uploadPath,
    mode: { ".tag": "overwrite" },
    autorename: false,
    contents: Buffer.from("Created by an Agent Filesystem runtime.\n"),
  });
  console.log(`Agent ID: ${agentId}`);
  console.log(`Uploaded: ${uploadPath}`);
}
main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});

npx tsx agentfs-example.ts

Store the returned agent ID. Your backend uses it to mint later tokens and manage the same agent.

Which credential goes where

Only the runtime token enters the agent environment.

Managed users and tenants

The same agent and file operations work with a managed user’s token. Tenants are Coming soon and will add a separate administration and credential boundary.

See Authentication for token storage, caching, and revocation guidance.