# gizai:agent/connections

Agent connection protocols: an API or another agent an Agent is connected to (shared agent connections). An A2A agent card becomes one tool that talks to that agent (agentCard). An OpenAPI 3 description becomes Operations: each one a tool with its JSON schema, under the host's tool policy: a read (GET, HEAD) runs at once, anything else waits for the person's approval. A call goes to the public Internet only (Research.call), with the connection's secret header the model never sees.

```gizlang
import * as Connections from "gizai:agent/connections";
```

## Types

### `Connection`

```gizlang
type Connection = { id: string; name: string; base: string; header: string; secret: string; }
```

Credentials and endpoint identity supplied by the host after authorization.

- `id`: `string`
- `name`: `string`
- `base`: `string`
- `header`: `string`
- `secret`: `string`

### `Param`

```gizlang
type Param = { name: string; at: string; }
```

Where an input goes: "path", "query", "header" or "body" (the JSON request body).

- `name`: `string`
- `at`: `string`

### `Endpoint`

```gizlang
type Endpoint = { name: string; method: string; path: string; description: string; schema: Json; params: Vec<Param>; destructive: bool; idempotent: bool; }
```

One endpoint of an API (an OpenAPI operation): the tool name the model calls, its HTTP method and path, what it does and its input.

- `name`: `string`
- `method`: `string`
- `path`: `string`
- `description`: `string`
- `schema`: `gizlang_json.Json`
- `params`: `Vec<M29.Param>`
- `destructive`: `bool`
- `idempotent`: `bool`

### `Described`

```gizlang
type Described = { base: string; operations: Vec<Endpoint>; }
```

The API an OpenAPI 3 description at `address` serves: its server address (relative ones resolved against
`address`) and its Operations, named PREFIX_operationId.

- `base`: `string`
- `operations`: `Vec<M29.Endpoint>`

## Functions

### `described`

```gizlang
function described(spec: Json, address: string, prefix: string): Result<Described, string>
```

The API the OpenAPI 3 description `spec` at `address` serves, or why it is not one.

Effects: fail.

### `agentCard`

```gizlang
function agentCard(spec: Json, prefix: string): Described
```

Another agent, by its A2A card (gizai:agent/a2a): one Endpoint, PREFIX_ask, that sends it a message at the card's
JSON-RPC address. Its answer may do anything the agent does, so a call waits for the person as any write does.

Effects: fail.

### `mcpTools`

```gizlang
function mcpTools(context: Research.Context, address: string, secret: Vec<Http.Header>, prefix: string): Result<Described, string>
```

The protocol owner discovers tools; this host maps connection records and policy.

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

### `stored`

```gizlang
function stored(operations: Vec<Endpoint>): string
```

Operations as a connection keeps them.

Effects: fail.

### `allowsOperation`

```gizlang
function allowsOperation(scopes: string, name: string): bool
```

Empty scopes expose all operations; otherwise only exact whitespace-separated names are admitted.

Effects: fail.

### `operationsOf`

```gizlang
function operationsOf(stored: string, scopes: string = ""): Vec<Endpoint>
```

The Operations of a stored connection that `scopes` admits (allowsOperation); none when it does not parse.

Effects: fail.

### `reads`

```gizlang
function reads(op: Endpoint): bool
```

Whether an endpoint only reads: GET, HEAD and a tool its MCP server marks read-only run without asking.

### `invoke`

```gizlang
function invoke(context: Research.Context, c: Connection, op: Endpoint, input: Json): Research.Outcome
```

Calls `op` of `c` with the model's `input`: path and query values encoded, the body as JSON, the secret header
added here. A failed status is an error the model reads, with what the API said.

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

## Constants

### `MOST_OPERATIONS`

```gizlang
const MOST_OPERATIONS = 64
```

The most Operations one connection offers.