Provider APIs

Developer Preview: Provider API access is part of the planned plugin model. Keep provider API work behind plugin helpers.

Default order

Use the cheapest reliable path that preserves the agent’s provider identity.

1. http.fetch for public provider APIs that do not need an authenticated browser session.
2. browser.sessionFetch for authenticated provider web APIs from the agent’s browser session.
3. browser.act for steps that only exist in visible UI, such as login, OTP entry, captcha, consent screens, or click-throughs the provider does not expose as an API.
4. browser.navigate to get the browser profile into the state needed for the other calls.

Most production skills should use sessionFetch after setup or recovery has authenticated the browser profile. Browser actions are the slow path; use them when the provider gives you no stable request to call.

Capability boundary

Provider API calls are allowed only when the manifest declares HTTP capability and the destination host is listed in http.egressDomains.

capabilities: {
  http: {
    egressDomains: ['sample.example', 'api.sample.example'],
  },
}

Calls outside the declared domains should fail at runtime. Keep the list as small as the provider allows.

Which path to use

Use http.fetch for provider API calls that do not depend on live page state.

const response = await http.fetch('https://api.sample.example/orders/status', {
  method: 'POST',
  json: { orderRef },
});

Use browser.sessionFetch when a provider call must use the agent’s authenticated provider session, cookies, or same-session risk context. It still follows the declared egress-domain rules.

Use browser interaction when the flow depends on visible UI, human review, provider risk checks, or a step that is safer to complete through the website. When a visible action triggers a provider API request, prefer capturing that request shape and replaying it with sessionFetch in future runs.

See Provider API Discovery for the capture-and-replay workflow.

Keep APIs behind skills

Provider web APIs from the agent’s authenticated session are implementation details. Their paths, request bodies, response shapes, and headers can change without notice.

Expose stable skills instead.

export const checkOrder: SkillHandler<{ orderRef: string }> = async ({
  input,
  http,
  log,
}) => {
  const status = await providerApi.getOrderStatus({
    http,
    orderRef: input.orderRef,
  });

  log.info('Checked order status', { orderRef: input.orderRef });

  return {
    ok: true,
    data: { status },
  };
};

Keep the skill name and result shape stable even when the provider API changes underneath.

Safety rules

• Return structured data and a short safe summary for read-only calls.
• Validate inputs before calling the provider.
• Use context.idempotencyKey for calls that change provider state.
• Re-check totals, targets, or selected records before submitting.
• Put provider identifiers in structured data or log fields, not in user-facing message text.
• Return login_required instead of creating a duplicate provider account when the session expires.
• Return rate_limited when the provider asks the plugin to slow down.

For irreversible or costly actions, mark the skill with mutating: true and requiresConfirmation: true.