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.

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

Types

Connection

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

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

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

• name: string
• at: string

Endpoint

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

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

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

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

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

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

Operations as a connection keeps them.

Effects: fail.

allowsOperation

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

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

Effects: fail.

operationsOf

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

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

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

const MOST_OPERATIONS = 64

The most Operations one connection offers.