# gizai:agent an agent is a model, its instructions, typed tools and the conversation so far. `run` streams one answer: the model writes, calls tools (the calls of one turn run at once), reads their results and writes again, until it answers or a limit ends the run. `ask` asks for a record T and gives a T. A tool is a plain function of a record: its JSON Schema comes from the record's declaration and docs (Memory.describe), and its arguments are read as that record (Json.decode), so no schema is written by hand. A model is one function that streams a turn: `endpoint` is any OpenAI-compatible API (gizlang:hub), and a test gives a scripted one. ```gizlang import * as Agent from "gizai:agent"; ``` ## Types ### `Call` ```gizlang type Call = Hub.Call ``` A tool call the model made: its id, the tool, and its arguments (a JSON object's text). ### `Message` ```gizlang type Message = { role: string; text: string; reasoning: string; calls: Vec; call: string; details: Vec; images?: Vec; } ``` One message of the conversation: "user", "assistant" (its text, reasoning, the calls it made and the provider's reasoning details that continue it) or "tool" (the result `text` of the call `call`). - `role`: `string` - `text`: `string` - `reasoning`: `string` - `calls`: `Vec` - `call`: `string` - `details`: `Vec` - `images`: `_gizlang_sdk_core.Option>` — The pictures the person showed with a "user" message, as data URLs (data:image/png;base64,...). ### `Piece` ```gizlang type Piece = { kind: string; text: string; call: Call; } ``` What a run shows as it goes: "text" and "reasoning" as the model writes them, "call" when it calls a tool (`call`: its name and JSON input), "result" or "failed" with the tool's answer, and at the end "done" with the answer or "error" with why the run failed, or "stopped" with the text written when `stop` ended it. - `kind`: `string` - `text`: `string` - `call`: `gizlang_hub.Call` ### `Request` ```gizlang type Request = { instructions: string; messages: Vec; tools: Vec; answer: bool; } ``` What the model is asked for one turn: the instructions, the conversation, the tools (OpenAI function objects), and `answer`: write, do not call a tool. - `instructions`: `string` - `messages`: `Vec` - `tools`: `Vec` - `answer`: `bool` ### `Turn` ```gizlang type Turn = { text: string; reasoning: string; calls: Vec; details: Vec; tokens: i64; input: i64; window: i64; } ``` One turn of the model: its text, reasoning, tool calls and reasoning details, the tokens it wrote and read, and the model's context window in tokens (0: unknown). - `text`: `string` - `reasoning`: `string` - `calls`: `Vec` - `details`: `Vec` - `tokens`: `i64` - `input`: `i64` - `window`: `i64` ### `Model` ```gizlang type Model = { name: string; turn: (sys: System, r: Request, each: (p: Piece) => bool) => Result; } ``` A model: its name and the function that writes a turn, giving each text or reasoning piece to `each` as it comes (a false from `each` stops the turn). - `name`: `string` - `turn`: `(sys: gizlang_system.System, r: M19.Request, each: (p: M19.Piece) => bool) => _gizlang_sdk_core.Result` ### `Tool` ```gizlang type Tool = { name: string; description: string; parameters: JsonValue; readOnly: bool; run: (arguments: string) => Result; } ``` A tool: its name, what it does, the JSON Schema of its input, whether it only reads (a call of it runs without `approve`), and the function that runs it on its arguments' text and answers JSON text. - `name`: `string` - `description`: `string` - `parameters`: `gizlang_json.Json` - `readOnly`: `bool` - `run`: `(arguments: string) => _gizlang_sdk_core.Result` ### `Agent` ```gizlang type Agent = { model: Model; instructions: string; tools: Vec; history: Vec; rounds: i64; maxTokens: i64; maxMs: i64; stop: () => bool; approve: (c: Call) => bool; tokens: i64; input: i64; context: i64; window: i64; } ``` An agent: the model, its instructions and tools, the conversation so far (each run adds to it), its limits (tool rounds of one run; tokens written and milliseconds of one run, 0: none), the tokens its runs wrote and read, how many tokens the conversation holds after the last turn (`context`) of the model's window (`window`, 0: unknown), and what a person does to a running agent: `stop`, asked between pieces and between rounds (true ends the run, keeping what was written, with a "stopped" piece), and `approve`, asked before each tool call runs (it may wait for the person; false gives the model DECLINED as the result). - `model`: `M19.Model` - `instructions`: `string` - `tools`: `Vec` - `history`: `Vec` - `rounds`: `i64` - `maxTokens`: `i64` - `maxMs`: `i64` - `stop`: `() => bool` - `approve`: `(c: gizlang_hub.Call) => bool` - `tokens`: `i64` - `input`: `i64` - `context`: `i64` - `window`: `i64` ### `Attachment` ```gizlang type Attachment = { name: string; type: string; path: string; } ``` A file the person gives with a message: its name, its media type (image/png, application/pdf, text/csv...) and where it is on this computer. A picture goes to the model as a picture; a document's text (a PDF's words, a text file) joins the message, and a long one is read in parts with the tool read_file. - `name`: `string` - `type`: `string` - `path`: `string` ## Functions ### `agent` ```gizlang function agent(model: Model, instructions: string, tools: Vec): Agent ``` An agent of `model` with `instructions` and `tools`, an empty conversation and at most 16 tool rounds a run. ### `tool` ```gizlang function tool(name: string, run: (input: I) => Result): Tool ``` The tool `name` that runs `run` on its input record I and answers O as JSON. Its description is I's doc comment and each field's doc describes that field. `run` is a function `(input: I): O throws string`; what it throws goes back to the model as the tool's error. ### `schema` ```gizlang function schema(): JsonValue ``` The JSON Schema of the record or union T, from its declaration. ### `run` ```gizlang function run(sys: System, a: mut Agent, prompt: string, each?: (p: Piece) => void, files: Vec = []): string throws string ``` Asks the agent `prompt` with the attached `files` (Attachment) and gives its answer, after the tool calls it makes; each piece goes to `each` as it comes. The prompt and every message of the run join `a.history`. Effects: fail, read, write, console, io. ### `ask` ```gizlang function ask(sys: System, a: mut Agent, prompt: string, each?: (p: Piece) => void): T throws string ``` Asks the agent `prompt` for a record T: the model answers by calling the tool `answer` with a T, which is read and checked as T. An answer that does not read as T goes back to the model as the error of its call. ### `title` ```gizlang function title(sys: System, model: Model, first: string): string throws string ``` A short title for a conversation that begins with `first`, for a list of conversations: one turn of `model`, no tools, its first line without quotes, at most 60 characters. Effects: fail, read, write, console, io. ### `endpoint` ```gizlang function endpoint(sys: System, model: string = ""): Model throws string ``` The model `model` (by default AI_MODEL) of the OpenAI-compatible API of AI_URL and AI_API_KEY (gizlang:hub's modelApi: OpenRouter when AI_URL is unset; vLLM, Ollama, llama.cpp or `giz ai serve` by AI_URL). Effects: fail, write, io. ### `served` ```gizlang function served(name: string, id: string, window: i64, api: (s: System) => Result): Model ``` Model `id` of the API that `api` gives at each turn, shown as `name`; `window` is its context window (-1: read from the API at the first turn). The API is taken per turn because its key may expire (a sign-in's token): a key that cannot be had fails that turn with why, and the next turn tries again. Effects: fail, write. ### `windowOf` ```gizlang function windowOf(api: Hub.ModelApi, name: string): i64 ``` The context window of model `name` as the API `api` lists it (GET /models, asked once a model); 0 when it does not say or does not answer, which only leaves the window unknown. Effects: fail, read, write, console, io. ### `streamed` ```gizlang function streamed(api: Hub.ModelApi, name: string, window: i64, r: Request, each: (p: Piece) => bool): Result ``` One turn of `r` from model `name` of the API `api`, streamed; `window` is the model's context window (0: unknown). Effects: fail, read, write, console, io. ### `scripted` ```gizlang function scripted(turns: Vec): Model ``` A model that gives `turns` in order, one a request, each text in pieces of at most 4 bytes. For tests and examples that need no GPU and no network. Effects: fail, write. ### `says` ```gizlang function says(text: string): Turn ``` A scripted turn that says `text`. ### `calls` ```gizlang function calls(named: Vec): Turn ``` A scripted turn that calls `calls` (each a tool name and its arguments' JSON text), with ids call_0, call_1... ## Constants ### `ANSWER` ```gizlang const ANSWER = "answer" ``` The name of the tool that `ask` adds: its input is the record asked for. ### `DECLINED` ```gizlang const DECLINED = "The person declined this call." ``` What a declined call gives the model as its result. ### `READ_FILE` ```gizlang const READ_FILE = "read_file" ``` The name of the tool that reads a long document in parts.