web Plugin

web is a very thin system text plugin.

It mainly does two things:

• inject general methodology for web research, page reading, and browser work into the agent
• expose an install action for preparing web-related skills and CLIs such as web-access and agent-browser

It does not:

• choose a provider
• decide which web implementation the agent must use at runtime
• perform actual web search or browser interaction
• persist project-level web configuration

What it does

web appends a methodology block when the agent system prompt is assembled.

That text tells the agent to:

• avoid assuming any specific web tool exists
• inspect current tools, skills, and context first
• choose different paths for search, fetch, browser, and logged-in tasks
• verify research conclusions against primary sources where possible
• state missing web capability directly instead of pretending it browsed

So its role is not “web executor.” It is the web-task thinking layer.

What the install action does

install is a setup action. It prepares capability, but it does not mean the agent must use a specific provider at runtime.

await agent.plugins.runAction({
  plugin: "web",
  action: "install",
  payload: {
    target: "agent-browser",
    scope: "user",
  },
});

Available target values:

• web-access: install the web-access skill, default
• agent-browser: install the agent-browser skill and prepare the agent-browser CLI package
• all: prepare both capabilities

Available scope values:

• user: install into user-level skills / global CLI, default
• project: install into the current project's skills / devDependency

Relationship to concrete web capabilities

Concrete web capability comes from the current agent environment: tools, skills, or other plugins.

For example:

• If search or fetch tools are available, the agent can use them for public web discovery and page reading.
• If browser, Chrome, agent-browser, or computer-use capabilities are available, the agent can handle dynamic pages, logged-in pages, and real browser interaction.
• If a web-access style skill is available, the agent can follow that skill for web search, page extraction, and source verification.

web itself does not decide which one to use. The agent chooses during execution based on the current capabilities and the user's goal.

Which plugin capabilities it uses

web uses:

• actions
• setup
• system

It does not use:

• config
• usage
• availability
• hooks
• runtime HTTP

That is the clean part of the current design: prompt handles methodology, install prepares dependencies, and provider choice, project config, and actual web execution stay separate.

How to register it in the SDK

import { Agent } from "@downcity/agent";
import { WebPlugin } from "@downcity/plugins";

const agent = new Agent({
  id: "research-agent",
  path: "/path/to/project",
  tools: {},
  plugins: [new WebPlugin()],
});

After registration, the methodology returned by WebPlugin.system() is automatically included in the agent's plugin system prompt.

How to call it

web has one action: install.

await agent.plugins.runAction({
  plugin: "web",
  action: "install",
  payload: {
    target: "web-access",
    scope: "user",
  },
});

The right model is:

• new WebPlugin() adds web methodology to the agent system prompt
• web.install prepares web-related skill / CLI dependencies
• the agent chooses a concrete web path from its current tools and skills during execution
• actual search, fetching, clicking, and browser operation still happens in the concrete tool or skill

Natural boundary

web does not read or write project config, including downcity.json.plugins.web.

If you want the agent to have a concrete web capability, provide that capability explicitly through tools, skills, or another plugin instead of putting it into web.

When to use it

Use it when:

• the agent often needs web research, page reading, or browser work
• you want the agent to reason about the right web path before using a capability
• real web capability is already provided by tools, skills, or other plugins

Do not use it when:

• you want it to switch the runtime default provider
• you want it to directly perform web search or browser clicks
• you want to persist web settings into project configuration

Related docs

• Built-in Plugin Overview
• Plugin system
• Plugin actions
• Skill Plugin