web4browser

Posted on May 18

Designing an Account Context Manifest for AI Browser Agents

#ai #webdev #automation #playwright

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.

Field	Meaning	Why it matters
account_id	The business or platform account being used	Prevents account confusion
profile_id	The browser profile assigned to the account	Keeps browser identity consistent
profile_path	Local path for persistent browser context	Allows repeatable, long-lived sessions
proxy.id	The selected proxy route	Makes network identity auditable
proxy.timezone	Expected timezone for the proxy region	Reduces environment mismatch
proxy.locale	Expected language and locale	Keeps browser behavior consistent
browser.mode	`headed` or `headless`	Helps reproduce failures
persistent_context	Whether a long-lived profile is used	Keeps session continuity
allowed_tasks	Tasks this account can run	Prevents accidental misuse
requires_human_review	Actions where the agent must stop	Adds safety boundaries
evidence	Logs, screenshots, snapshots	Makes debugging possible

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.

Check	Why it matters
Is the selected profile the expected one?	Prevents the agent from using a clean or wrong browser profile
Does the proxy region match timezone and locale?	Reduces inconsistent execution environments
Is the run headed or headless?	Makes failures easier to reproduce
Is this task allowed for this account?	Prevents unsafe or unintended actions
Are cookies and local storage from the expected profile?	Avoids state confusion between accounts
Does the workflow require human review?	Stops the agent before sensitive steps
Will evidence be saved?	Makes debugging possible after failure

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.

Failure mode	Without manifest	With manifest
Wrong proxy	A script runs with a random proxy flag	Proxy is bound to account context
Wrong browser profile	The agent opens a clean browser	The agent launches the expected persistent profile
Headed/headless mismatch	Failure is hard to reproduce	Execution mode is logged
Cookie confusion	State files are reused blindly	State file is tied to account and profile
Unsafe retry	Agent repeats account-changing actions	Workflow rules define review boundaries
Weak debugging	“It worked yesterday”	Logs show account, profile, proxy, task, and evidence

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:

Every browser run must load a manifest.
Every manifest must be validated before execution.
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.

DEV Community