# gizai:agent/research

Web research and bounded HTTP reads for agent capabilities. Hosts supply network admission explicitly.

```gizlang
import * as Research from "gizai:agent/research";
```

## Types

### `Link`

```gizlang
type Link = { title: string; url: string; }
```

A source a step found.

- `title`: `string`
- `url`: `string`

### `Outcome`

```gizlang
type Outcome = { ok: bool; text: string; note: string; links: Vec<Link>; }
```

A tool's result: text for the model, a note for the person, sources.

- `ok`: `bool`
- `text`: `string`
- `note`: `string`
- `links`: `Vec<M28.Link>`

### `Context`

```gizlang
type Context = { sys: System; inside: bool; }
```

The host of a research call and whether it runs inside the host's network (private addresses admitted).

- `sys`: `gizlang_system.System`
- `inside`: `bool`

### `Answer`

```gizlang
type Answer = { status: i64; text: string; headers: Vec<Http.Header>; }
```

An API's answer: its status, its body as text and its headers.

- `status`: `i64`
- `text`: `string`
- `headers`: `Vec<gizlang_http.Header>`

## Functions

### `search`

```gizlang
function search(context: Context, query: string): Outcome
```

Up to eight web results: DuckDuckGo's HTML page (no key, no script, no
ads), or Bing's when DuckDuckGo turns the request away: it answers a
rate-limited address with 202, or with 200 and a challenge page instead of
results, often for a whole day.

Effects: fail, read, write, console, io.

### `read`

```gizlang
function read(context: Context, address: string): Outcome
```

A page's title and text, at most MOST_TEXT bytes of it.

Effects: fail, read, write, console, io.

### `linksOf`

```gizlang
function linksOf(json: string): Vec<Link>
```

Sources from the JSON an item keeps.

Effects: fail.

### `call`

```gizlang
function call(context: Context, method: string, address: string, headers: Vec<Http.Header>, body: bytes): Answer
```

Calls an API on the public Internet: `method` to `address` with `headers` and `body`, following redirects and
reading at most MOST_PAGE bytes of text; the body of any status is kept.

Effects: fail, read, write, console, io.