# gizai:a2a

the Agent2Agent protocol (0.3, JSON-RPC over HTTP) for agents. `handle` serves an agent: message/send writes to it, tasks/get reads a turn, tasks/cancel stops one; `card` is what it says about itself. `tool` is the other end: another agent, by its card, as an agent tool that sends it a message and waits for its answer.

```gizlang
import * as A2a from "gizai:a2a";
```

## Types

### `Task`

```gizlang
type Task = { id: string; context: string; state: string; text: string; }
```

A turn of a served agent as A2A shows it: the task's id, the conversation (context) it continues, its state
(submitted, working, input-required, completed, canceled, failed) and its answer so far.

- `id`: `string`
- `context`: `string`
- `state`: `string`
- `text`: `string`

### `Refusal`

```gizlang
type Refusal = { code: i64; message: string; }
```

A JSON-RPC error: TaskNotFound -32001, UnsupportedOperation -32004, InvalidParams -32602.

- `code`: `i64`
- `message`: `string`

### `Answer`

```gizlang
type Answer = Result<Task, Refusal>
```

A turn, or the JSON-RPC error that refuses the call.

## Functions

### `stateOf`

```gizlang
function stateOf(status: string): string
```

The A2A state of a run's status: done, running, failed, stopped, or approval (waiting for the person).

### `card`

```gizlang
function card(name: string, about: string, url: string, version: string, tags: Vec<string>, bearer: string): bytes
```

The card of an agent: who it is, where its JSON-RPC answers, its skill's tags, and, unless BEARER is "", that it
wants a Bearer token (BEARER says where to get one).

Effects: fail.

### `task`

```gizlang
function task(t: Task): JsonValue
```

A turn as an A2A Task: its state, the answer as the status message and, once completed, as the one artifact.

Effects: fail.

### `textOf`

```gizlang
function textOf(message: JsonValue): string
```

The text of a Message's text parts.

Effects: fail.

### `handle`

```gizlang
function handle(request: Http.Request, send: (context: string, text: string) => Answer, get: (task: string) => Answer, cancel: (task: string) => Answer): Http.Response
```

One JSON-RPC request to an agent: `send(context, text)` writes to it ("" for a new conversation), `get(task)` reads
a turn, `cancel(task)` stops one. Streaming and push are refused as unsupported.

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

### `isCard`

```gizlang
function isCard(spec: JsonValue): bool
```

Whether a description is an A2A agent card rather than an API's.

Effects: fail.

### `about`

```gizlang
function about(spec: JsonValue): string
```

What a model is told an agent is good at: its description and skills.

Effects: fail.

### `sending`

```gizlang
function sending(id: string, text: string, context: string): bytes
```

The JSON-RPC body of message/send: TEXT, continuing CONTEXT unless it is "".

Effects: fail.

### `getting`

```gizlang
function getting(id: string, task: string): bytes
```

The JSON-RPC body of tasks/get.

Effects: fail.

### `heard`

```gizlang
function heard(result: JsonValue): Task
```

An agent's answer as read: a Task, or a plain Message as a completed one with no id.

Effects: fail.

### `settled`

```gizlang
function settled(state: string): bool
```

Whether a task's state is its last (or waits for the caller).

### `tool`

```gizlang
function tool(sys: System, spec: JsonValue, headers: Vec<Mcp.Header>, prefix: string, inside: bool = false): Agent.Tool
```

Another agent, by its A2A card, as one agent tool PREFIX_ask: the model sends it a message (and the context its
last answer named, to continue), and reads its answer, a task still working read again until it ends or WAIT_MS
passes. HEADERS go with each request (its key); only the public Internet is reached unless `inside`. The answer
may do anything the agent does, so the tool is not read-only.

Effects: fail.

## Constants

### `PROTOCOL`

```gizlang
const PROTOCOL = "0.3.0"
```

The version of the A2A protocol that the served agents speak.