Resource / practical agent operations

Setup Friction Is the Product Killer

The demo was magical. Then someone asked for the bot token. This checklist names the boring setup blockers that decide whether an agent feels usable or fragile.

Seven setup demonsNo formsNo pricingSetup preflight

Boundary note

This resource is a checklist for setup risk. It is not a provider-specific setup tutorial, security hardening guide, pricing page, legal advice, service agreement, lead-capture flow, or managed-support promise.

Do not use it as permission to automate messages, outreach, replies, DMs, account changes, payment changes, credential resets, or paid provider work. Those actions need their own authority, proof, and review.

Who this is for

Builders, operators, and service teams trying to make practical agents usable outside the demo bubble.

Use it before handing an agent to a buyer, teammate, or operator; connecting a bot to a real channel; running paid provider work; scheduling unattended jobs; claiming a public URL is available; or offering setup support.

The blunt version

Setup friction is not a pre-product nuisance. It is part of the product. If users cannot safely connect an agent, verify it, and understand what support includes, they do not have an agent. They have a haunted chore with nicer marketing.

The seven setup demons

1. Bot, token, and channel-ID soup

The failure: The route is treated as one step when it actually requires identity, credential, permissions, destination, subscription, router, and a harmless smoke test.

Practical checks:

  • Name platform identity without exposing credential value.
  • Use fictional or redacted identifiers in docs and screenshots.
  • Verify exact safe destination before sending anything.
  • Run harmless receive/send smoke test in a test-safe destination.
  • Write forbidden send actions before enabling real routes.

Refuse to proceed when:

  • Only proof is that a token exists.
  • Destination ID came from a private screenshot or unverified chat.
  • Agent is expected to DM, post, invite, scrape, or reply to real people before approval.
  • User asks to bypass 2FA, CAPTCHA, rate limits, moderation rules, or platform consent.

Receipt evidence to look for: identity proof, destination proof, permission map, test message result, approval gate.

2. Wrong working directory

The failure: The agent reads stale inputs, writes outputs into scratch, misses project config, or reports success from a path nobody checks.

Practical checks:

  • State intended project root as a placeholder, not a private machine path.
  • Confirm current working directory before running the job.
  • Write final artifacts under agreed durable output root.
  • Read final artifacts back after writing.
  • Pin task to the right profile and workspace when multiple profiles exist.

Refuse to proceed when:

  • Live operation depends on whatever directory the shell happens to be in.
  • Output path is not agreed before the run.
  • Support request cannot locate the durable artifact.
  • Fix requires changing another profile, service, gateway, or production process without approval.

Receipt evidence to look for: start path, output root, artifact paths, read-back check, workspace/profile note.

3. Missing environment variables and hidden config

The failure: Required config is absent, stale, scoped wrong, or only present in one developer's shell.

Practical checks:

  • Maintain public-safe inventory of required variable names and purposes without values.
  • Keep secrets out of public docs, screenshots, prompts, commits, and tickets.
  • Use cheap or read-only tests for each external capability.
  • Fail clearly when required config is absent.
  • Define fallback or refusal path for missing paid/provider credentials.

Refuse to proceed when:

  • Real keys are pasted into chat, public docs, screenshots, issue threads, or model prompts.
  • Paid provider run is requested before account status, scope, billing/spend boundary, and route are verified.
  • Setup depends on a human's private shell session with no documented handoff.
  • Agent silently downgrades quality or switches providers without telling the operator.

Receipt evidence to look for: config name inventory, capability tests, missing-config behavior, spend boundary, fallback/refusal path.

4. Unverified public URL

The failure: A local file exists, so people claim the resource is live before an external URL resolves and renders correctly.

Practical checks:

  • Separate local file, staged route, live route, and verified-live state.
  • Fetch/check URL from outside the build context when public status is claimed.
  • Verify rendered title, body, links, and absence of placeholder junk.
  • Exclude drafts, private notes, local paths, and internal manifests from public package unless intentionally safe.
  • Label publication status honestly.

Refuse to proceed when:

  • Only evidence is that an HTML or Markdown file exists.
  • URL has not been fetched/rendered after deployment.
  • Page contains private paths, account notes, tokens, real channel IDs, or unapproved provider/client claims.
  • Request jumps from draft to public post without staging and review.

Receipt evidence to look for: public URL, render proof, link check, safety scan, publication status.

5. Broken provider route

The failure: The integration exists in theory, but the actual model/media/API/browser/email/payment-related route fails or costs money without proof.

Practical checks:

  • Confirm provider capability is needed for the job.
  • Run cheap or read-only probe to prove route works today.
  • Bound spend before paid calls.
  • Inspect output quality, not just API success.
  • Define refusal path when provider is down, unverified, or outside approval.

Refuse to proceed when:

  • Route would trigger paid API/provider/render/upload/export/subscription spend without approval.
  • Action would change credentials, accounts, DNS, payment, profiles, gateways, or provider settings.
  • Provider result cannot be read back, inspected, or linked to a durable receipt.
  • Support team would have to debug a live account with no authority boundary.

Receipt evidence to look for: capability probe, spend limit, output artifact, quality check, fallback/refusal decision.

6. No artifact proof

The failure: The agent says it worked but leaves no durable file, URL, screenshot, receipt, checksum, log, approval state, source list, or side-effect record.

Practical checks:

  • Require durable artifact or explicit no-output reason for meaningful runs.
  • Record path or URL, bytes/hash where practical, source inputs, checks, approval state, spend, and side effects.
  • Read artifact back after creation.
  • Record failures honestly instead of replacing them with confident prose.
  • Make verification reproducible by a reviewer.

Refuse to proceed when:

  • Requested claim is done but artifact cannot be located.
  • Public posting, provider spend, account action, data mutation, or user contact has no receipt.
  • Proof would require exposing private paths, credentials, customer data, account IDs, or unapproved screenshots.
  • Operator wants success based only on the agent's own summary.

Receipt evidence to look for: artifact path_or_url, bytes, sha256_where_practical, checks, approval_state, spend, side_effects.

7. Support-boundary failures

The failure: Setup help is undefined, so it expands into account recovery, payment setup, legal promises, production uptime, provider debugging, private data handling, platform appeals, and emergency restarts.

Practical checks:

  • Write support boundary before handoff.
  • List forbidden actions: credential resets, account/profile/DNS/payment/provider changes, service restarts, public posting, outreach, DMs, private-data collection, legal/client commitments.
  • Define escalation paths for credentials, billing, privacy, production incidents, and platform policy issues.
  • Distinguish education, setup diagnostics, implementation work, and managed support.
  • Teach the agent when to block for human authority.

Refuse to proceed when:

  • User expects account, payment, legal, or platform-policy fixes without explicit authority.
  • Setup issue requires touching private customer data or live accounts with no consent path.
  • Service scope is vague enough that every failure becomes support.
  • Agent is asked to make uptime, refund, security, legal compliance, or client outcome commitments.

Receipt evidence to look for: scope boundary, forbidden actions, escalation path, approval gates, support tier distinction.

Ten-minute preflight

If any answer is no or unknown, do not pretend the setup is ready.

Minimum receipt for a setup run

A useful setup run records the resource or task name, date, inputs, output target, files changed, bytes and checksums where practical, checks run, approval state, external side effects, spend, known limits, and next review owner.

No receipt, no trust. A useful agent leaves proof a human can inspect.

Source and evidence notes

This resource generalizes setup-risk patterns from internal content research and review. Examples are sanitized and use placeholders only. No private paths, credentials, internal hostnames, account details, raw logs, customer data, pricing terms, forms, or service commitments are included.

Treat publication status as a separate receipt: a route should only be described as available after the exact page has been fetched, rendered, and reviewed.

Back to resource index