Your AI browser agent can open a page.

It can click buttons.

It can fill forms.

It can even complete a workflow that looks correct from the outside.

But here is the more important question:

Can you prove it used the right account, the right browser profile, the right proxy, the right session history, and the right workflow boundary?

For many browser automation projects, the answer is no.

Not because the automation framework is bad. Playwright, Puppeteer, browser MCP servers, and AI agents are all powerful.

The problem is more basic:

Most systems treat browser control as the whole workflow.

In real account-based automation, browser control is only one layer.

The missing layer is account context.

This post introduces a simple pattern I call an Account Context Manifest: a structured file that tells an AI browser agent which account environment it is allowed to use, what assumptions must stay stable, and what evidence should be recorded.

It is not a silver bullet.

It is not a replacement for security, platform compliance, or human review.

But it is a practical way to stop AI browser automation from becoming a pile of disconnected scripts, state files, proxy flags, and screenshots.

Browser control is not account-aware execution

Most browser automation examples start like this:

const browser = await chromium.launch();
const page = await browser.newPage();

await page.goto("https://example.com");
await page.click("text=Login");

That is fine for tests, demos, and simple one-off tasks.

But real account workflows are different.

A real workflow usually depends on more than a URL and a selector.

It depends on questions like:

• Which account is being used?
• Which browser profile belongs to that account?
• Which proxy or network route should be used?
• Does the timezone match the proxy region?
• Does the locale match the account environment?
• Is the session expected to be fresh or persistent?
• Are browser extensions required?
• Is this task safe for headless execution?
• When should the agent stop for human review?
• What evidence should be saved if the workflow fails?

If these details live in different places, the agent may still run.

But the result becomes hard to audit.

That is where many browser agents fail in practice.

Not because they cannot click.

But because they do not know enough about the account environment they are clicking inside.

What is an Account Context Manifest?

An Account Context Manifest is a structured definition of the browser environment an automation run is allowed to use.

It connects these fields into one object:

• account identity
• browser profile
• proxy configuration
• timezone and locale
• session state
• browser mode
• workflow permissions
• human review rules
• debugging evidence

Here is a minimal example:

{
  "account_id": "acct_us_042",
  "profile_id": "profile_us_042",
  "profile_path": "./profiles/acct_us_042",

  "proxy": {
    "id": "proxy_us_res_07",
    "country": "US",
    "timezone": "America/New_York",
    "locale": "en-US"
  },

  "browser": {
    "mode": "headed",
    "persistent_context": true,
    "extensions_required": ["wallet", "password-manager"]
  },

  "state": {
    "storage_state_path": "./states/acct_us_042.json",
    "last_verified_at": "2026-05-18T10:00:00Z"
  },

  "workflow": {
    "allowed_tasks": [
      "login-check",
      "page-inspection",
      "report-export"
    ],
    "requires_human_review": [
      "verification",
      "payment",
      "profile-reset"
    ]
  },

  "evidence": {
    "save_screenshot": true,
    "save_dom_snapshot": true,
    "log_proxy_check": true
  }
}

The manifest does not make the agent smarter by itself.

Instead, it makes the execution environment explicit.

Before the agent acts, it should know:

I am operating account acct_us_042, inside profile profile_us_042, using a US proxy, with New York timezone, in headed mode, and I must stop before verification or payment actions.

That is very different from:

Open Chromium and do the task.

Key fields in the manifest

A useful Account Context Manifest does not need to be complex.

But a few fields should be treated as first-class execution inputs.

These fields turn hidden assumptions into explicit constraints.

That is the main value of the manifest.

Why storageState alone is not enough

Playwright’s storageState is useful.

It can save cookies and local storage. It can help skip repeated login steps. For many testing workflows, that is exactly what you need.

But storageState is only a snapshot of part of the browser state.

It does not describe the full account environment.

For example, storageState does not tell you:

• which long-lived browser profile the account belongs to
• whether the workflow was run in headed or headless mode
• which proxy was used
• whether the proxy region matched the timezone and locale
• whether required extensions were available
• whether the run required a human review point
• whether the run produced useful debugging evidence

So storageState is helpful, but it should not be the only source of truth for account-based automation.

The manifest gives the state file context.

Instead of treating a state file as a magic login shortcut, the agent treats it as one part of a larger account environment.

A minimal Playwright implementation

Here is a simple TypeScript example using Playwright.

The point is not to build a full production system.

The point is to show that a browser run should begin by loading account context, not by launching a random browser.

import { chromium } from "playwright";
import fs from "fs";

type AccountManifest = {
  account_id: string;
  profile_id: string;
  profile_path: string;

  proxy: {
    id: string;
    country: string;
    timezone: string;
    locale: string;
  };

  browser: {
    mode: "headed" | "headless";
    persistent_context: boolean;
    extensions_required?: string[];
  };

  workflow: {
    allowed_tasks: string[];
    requires_human_review: string[];
  };

  evidence: {
    save_screenshot: boolean;
    save_dom_snapshot: boolean;
    log_proxy_check: boolean;
  };
};

const manifest: AccountManifest = JSON.parse(
  fs.readFileSync("./manifests/acct_us_042.json", "utf-8")
);

function assertTaskAllowed(taskName: string, manifest: AccountManifest) {
  if (!manifest.workflow.allowed_tasks.includes(taskName)) {
    throw new Error(
      `Task "${taskName}" is not allowed for account ${manifest.account_id}`
    );
  }
}

const taskName = "page-inspection";

assertTaskAllowed(taskName, manifest);

const context = await chromium.launchPersistentContext(
  manifest.profile_path,
  {
    headless: manifest.browser.mode === "headless",
    timezoneId: manifest.proxy.timezone,
    locale: manifest.proxy.locale
  }
);

const page = await context.newPage();

console.log({
  event: "browser_context_started",
  account_id: manifest.account_id,
  profile_id: manifest.profile_id,
  profile_path: manifest.profile_path,
  proxy_id: manifest.proxy.id,
  mode: manifest.browser.mode,
  task: taskName
});

await page.goto("https://example.com");

if (manifest.evidence.save_screenshot) {
  await page.screenshot({
    path: `./evidence/${manifest.account_id}-${taskName}.png`,
    fullPage: true
  });
}

await context.close();

A production version should do more:

• validate the manifest with a schema
• check proxy availability before starting
• confirm account identity after login
• save structured logs
• encrypt sensitive fields
• separate read-only tasks from account-changing tasks
• stop before risky actions
• require review for sensitive workflows

But even this minimal version creates a better habit:

The agent reads the account context before it touches the browser.

Add schema validation before execution

If an AI agent can trigger browser workflows, the manifest should be validated before execution.

A lightweight schema can prevent avoidable mistakes.

For example:

import { z } from "zod";
import fs from "fs";

const ManifestSchema = z.object({
  account_id: z.string().min(1),
  profile_id: z.string().min(1),
  profile_path: z.string().min(1),

  proxy: z.object({
    id: z.string().min(1),
    country: z.string().min(2),
    timezone: z.string().min(1),
    locale: z.string().min(2)
  }),

  browser: z.object({
    mode: z.enum(["headed", "headless"]),
    persistent_context: z.boolean(),
    extensions_required: z.array(z.string()).optional()
  }),

  workflow: z.object({
    allowed_tasks: z.array(z.string()),
    requires_human_review: z.array(z.string())
  }),

  evidence: z.object({
    save_screenshot: z.boolean(),
    save_dom_snapshot: z.boolean(),
    log_proxy_check: z.boolean()
  })
});

const manifest = ManifestSchema.parse(
  JSON.parse(fs.readFileSync("./manifests/acct_us_042.json", "utf-8"))
);

This is especially useful when manifests are generated by another system, edited by operators, or selected by an AI agent.

Do not let the agent guess the environment.

Make the environment explicit.

Validate it first.

Pre-run checks before the agent acts

Before an AI browser agent starts a workflow, it should pass a few basic checks.

These checks are not glamorous.

But they prevent a common failure mode in AI automation:

The agent completes a task, but nobody can explain the environment in which it happened.

Common failure modes the manifest prevents

A manifest is useful because it turns hidden assumptions into visible inputs.

The manifest does not remove the need for testing.

It gives your tests, agents, and human reviewers a shared language.

Where MCP and browser agents fit

Browser MCP servers and AI agents are useful because they make browser actions easier to expose as tools.

An agent can navigate, click, read the page, summarize content, and decide the next step.

But MCP does not automatically solve account context.

The agent still needs to know:

• which browser target it is allowed to use
• which profile belongs to the account
• which workflow it is allowed to run
• which actions require human review
• which logs or screenshots should be saved
• which environment assumptions should not change

Without that boundary, the agent is improvising.

With a manifest, the agent is still flexible, but it operates inside a defined environment.

That is the difference between browser access and account-aware execution.

Keep sensitive data out of the manifest

One important rule:

Do not put secrets directly into the manifest.

Avoid storing raw passwords, private keys, seed phrases, API keys, or payment credentials in a plain JSON file.

Instead, the manifest should reference secure storage:

{
  "account_id": "acct_us_042",
  "secrets": {
    "password_ref": "vault://accounts/acct_us_042/password",
    "api_key_ref": "vault://accounts/acct_us_042/api-key"
  }
}

The manifest should describe the account environment.

It should not become a secret dump.

For teams, this distinction matters a lot.

The more agents, profiles, and workflows you add, the more important it becomes to separate:

• identity metadata
• browser state
• secrets
• permissions
• audit logs

A manifest can connect these pieces without exposing all of them in one file.

When a manifest becomes a workspace

A manifest works well when you have a few accounts and a disciplined team.

But as the system grows, you may start to manage:

• many browser profiles
• many proxy routes
• persistent sessions
• headed and headless workflows
• AI agent tasks
• browser MCP tools
• human review points
• recurring logs and screenshots
• team permissions

At that point, the manifest often becomes part of a larger operating layer.

Some teams build this internally. Others use a browser automation workspace for account context so that profiles, proxies, automation tasks, and review evidence stay connected instead of being scattered across scripts and folders.

The important idea is not the tool name.

The important idea is this:

Account identity, browser state, proxy mapping, automation logic, and evidence should not be separated after the workflow starts.

They should be connected before the agent acts.

A practical starting template

If you are building your own system, start small.

Create one manifest per account:

{
  "account_id": "acct_example_001",
  "profile_id": "profile_example_001",
  "profile_path": "./profiles/acct_example_001",

  "proxy": {
    "id": "proxy_001",
    "country": "US",
    "timezone": "America/New_York",
    "locale": "en-US"
  },

  "browser": {
    "mode": "headed",
    "persistent_context": true
  },

  "workflow": {
    "allowed_tasks": [
      "login-check",
      "read-only-inspection"
    ],
    "requires_human_review": [
      "verification",
      "payment",
      "settings-change"
    ]
  },

  "evidence": {
    "save_screenshot": true,
    "save_dom_snapshot": false,
    "log_proxy_check": true
  }
}

Then add three rules:

1. Every browser run must load a manifest.
2. Every manifest must be validated before execution.
3. Every run must log the account ID, profile ID, proxy ID, task name, and execution mode.

That alone will make many automation failures easier to understand.

Final takeaway

AI browser agents do not only need browser access.

They need account context.

Before scaling browser automation, define the account identity, browser profile, proxy mapping, workflow boundary, and evidence trail as first-class execution inputs.

A simple manifest is a good start.

When the manifest becomes too hard to maintain manually, move the same logic into a shared workspace.

The goal is not just to make agents click faster.

The goal is to make browser automation reproducible, reviewable, and safe enough for real account workflows.

Related reading:

If you are deciding how to manage login state in Playwright, this breakdown of storageState vs persistent context may be useful.