http

Fetch URLs from Agency code. Returns the response as text, JSON, or Markdown. Aborting tears down the in-flight request.

import { fetch, fetchJSON } from "std::http"

node main() {
  const page = fetch("https://example.com")
  const data = fetchJSON("https://api.example.com/status")
  print(page)
}

Effects

std::http::fetch

effect std::http::fetch {
  baseUrl: string;
  path: string
}

(source)

std::http::fetchJSON

effect std::http::fetchJSON {
  baseUrl: string;
  path: string
}

(source)

std::http::fetchMarkdown

effect std::http::fetchMarkdown {
  baseUrl: string;
  path: string
}

(source)

Functions

fetch

fetch(baseUrl: string, path: string, headers: Record<string, any>, allowedDomains: string[]): Result

Fetch a URL and return the response as text.

@param baseUrl - The base URL to fetch @param path - Optional path appended to baseUrl @param headers - Custom request headers @param allowedDomains - Restrict fetches to these domains (empty allows all)

On abort, Agency tears down the in-flight HTTP request and body read. The abort surfaces as an AgencyCancelledError that propagates out of the surrounding try.

Parameters:

Name	Type	Default
baseUrl	string
path	string	""
headers	Record<string, any>	{}
allowedDomains	string[]	[]

Returns: Result

Throws: std::http::fetch

(source)

fetchJSON

fetchJSON(baseUrl: string, path: string, headers: Record<string, any>, allowedDomains: string[]): Result

Fetch a URL and return the response parsed as JSON.

@param baseUrl - The base URL to fetch @param path - Optional path appended to baseUrl @param headers - Custom request headers @param allowedDomains - Restrict fetches to these domains (empty allows all)

On abort, Agency tears down the in-flight HTTP request and body read. The abort surfaces as an AgencyCancelledError that propagates out of the surrounding try.

Parameters:

Name	Type	Default
baseUrl	string
path	string	""
headers	Record<string, any>	{}
allowedDomains	string[]	[]

Returns: Result

Throws: std::http::fetchJSON

(source)

fetchMarkdown

fetchMarkdown(baseUrl: string, path: string, headers: Record<string, any>, allowedDomains: string[]): Result

Fetch a URL and return the body as readable markdown when the response is HTML, or as plain text otherwise. Good for extracting page content for an LLM. Fails on network errors, domain violations, or if the response body exceeds 10 MB.

@param baseUrl - The base URL to fetch @param path - Optional path appended to baseUrl @param headers - Custom request headers @param allowedDomains - Restrict fetches to these domains (empty allows all)

On abort, Agency tears down the in-flight HTTP request and body read. The abort surfaces as an AgencyCancelledError that propagates out of the surrounding try.

Parameters:

Name	Type	Default
baseUrl	string
path	string	""
headers	Record<string, any>	{}
allowedDomains	string[]	[]

Returns: Result

Throws: std::http::fetchMarkdown

(source)