SDK agent reference

import { Web } from "@webcompute/sdk";

const web = new Web({ apiKey: process.env.WEBCOMPUTE_API_KEY! });

const agent = web.agent({
  model: {
    route: "openai",
    model: "gpt-5.4-mini",
    apiKeyEnv: "OPENAI_API_KEY",
  },
  browser: {
    policy: { allowedDomains: ["sec.gov"] },
  },
  approval: "ask",
});

const result = await agent.run({
  startUrl: "https://www.sec.gov/edgar/search/",
  goal: "Find Apple's latest 10-Q filings and return filing metadata.",
});

web.agent<TOutput = unknown>(
  config: WebAgentConfig<TOutput>
): WebAgent

interface WebAgent {
  run<TOutput = unknown>(
    input: string | WebAgentRunInput<TOutput>
  ): Promise<WebAgentResult<TOutput>>;

  stream<TOutput = unknown>(
    input: string | WebAgentRunInput<TOutput>
  ): AsyncIterable<WebAgentStreamEvent>;

  session(input?: { startUrl?: string; browserId?: string }): Promise<WebAgentSession>;
}

type WebAgentRoute =
  | "openai"
  | "openrouter"
  | "openai-compatible"
  | "anthropic"
  | "google";

interface WebAgentBrowserConfig {
  policy?: BrowserNavigationPolicy;
  create?: Omit<BrowserCreateOptions, "policy"> & {
    policy?: BrowserNavigationPolicy;
  };
}

const agent = web.agent({
  model,
  browser: {
    create: {
      proxy: process.env.RESIDENTIAL_PROXY_URL,
      recording: true,
      policy: { allowedDomains: ["vendor.example"] },
    },
  },
});

interface WebAgentRunInput<TOutput = unknown> {
  goal: string;
  startUrl?: string;
  browserId?: string;
  approval?: WebAgentApprovalMode;
  onConfirm?: WebAgentConfirmationHandler;
  captcha?: WebAgentCaptchaResolutionOptions;
  variables?: WebAgentVariables;
  outputSchema?: WebAgentSchema<TOutput>;
  metadata?: Record<string, unknown>;
  signal?: AbortSignal;
}

await agent.run("Open the pricing page and summarize enterprise plan differences.");

interface WebAgentResult<TOutput = unknown> {
  status: "completed" | "blocked" | "needs_confirmation" | "failed" | "cancelled";
  text: string;
  output?: TOutput;
  error?: WebAgentError;
  needsConfirmation?: WebAgentConfirmationRequest;
  browserId: string;
  debugUrl?: string;
  steps: WebAgentStep[];
  usage?: WebAgentUsage;
  artifacts: WebAgentArtifact[];
  transcript?: WebAgentTranscriptItem[];
  schema?: WebAgentSchemaMetadata;
  timings: {
    startedAt: string;
    finishedAt: string;
    elapsedMs: number;
  };
}

for await (const event of agent.stream({ goal, startUrl })) {
  if (event.type === "tool.completed") {
    console.log(event.step, event.success, event.summary);
  }

  if (event.type === "run.completed") {
    console.log(event.result.status, event.result.text);
  }
}

const session = await agent.session({
  startUrl: "https://vendor.example/dashboard",
});

await session.run("Collect invoice totals from the current account.");
await session.run("Download the most recent invoice PDF.");

await session.close();

interface WebAgentSession {
  readonly browserId: string;
  run<TOutput = unknown>(
    input: string | WebAgentRunInput<TOutput>
  ): Promise<WebAgentResult<TOutput>>;
  stream<TOutput = unknown>(
    input: string | WebAgentRunInput<TOutput>
  ): AsyncIterable<WebAgentStreamEvent>;
  close(): Promise<void>;
}

const agent = web.agent({
  model,
  approval: "ask",
  onConfirm: async (request) => {
    if (request.risk === "payment") {
      return { approved: false, reason: "Payments require a human operator." };
    }
    return { approved: true };
  },
});

const agent = web.agent({
  model,
  variables: {
    email: {
      value: process.env.VENDOR_EMAIL!,
      sensitive: true,
      allowedDomains: ["vendor.example"],
      description: "Vendor portal email",
    },
  },
});