# gizweb:chat agents and the conversations with them, kept as the rows of tables. The table of items is the conversation's log, as a model API has it (a message, the reasoning, a tool call and its result): a page writes what the person does as an item (a message, "again", "stop", a decision on a tool call), and `serve` runs the agent on it in the background and writes each piece of the answer as items that grow. Every open page follows the run by itself (only a changed row is sent); a closed page does not stop it, and after a restart each conversation goes on. ```gizlang import * as Chat from "gizweb:chat"; ``` ## Types ### `Assistant` ```gizlang type Assistant = { @Model.Key id: string; @Model.MaxLength(80) name: string; @Model.Min(0) instructions: string; @Model.Min(0) model: string; @Model.Min(0) tools: string; @Model.Min(0) approve: string; } ``` An agent a person talks to: its name, its instructions, its model ("" the default), the tools it may use and the tools that wait for the person's approval before they run (their names by commas; `tools` "" is all of them). `serve` makes the first one from the agent it is given. - `id`: `string` - `name`: `string` - `instructions`: `string` - `model`: `string` - `tools`: `string` - `approve`: `string` ### `Conversation` ```gizlang type Conversation = { @Model.Key id: string; @Model.Min(0) agent: string; @Model.Min(0) title: string; } ``` A conversation with the agent `agent`; its title is the person's first words until the first answer names it (Agent.title). - `id`: `string` - `agent`: `string` - `title`: `string` ### `Item` ```gizlang type Item = { @Model.Key id: string; @Model.Min(0) chat: string; @Model.Values("user,text,reasoning,call,plan,error,retry,stop") kind: string; @Model.Min(0) text: string; @Model.Min(0) name: string; @Model.Min(0) input: string; @Model.Min(0) output: string; @Model.Min(0) file: string; @Model.Min(0) files: string; @Model.Min(0) model: string; @Model.Min(0) state: string; done: bool; } ``` One item of the conversation `chat`, in the order of its key: - "user": the person's message `text` to `model` ("" the agent's), with the `files` attached (Pages.files); `done` once it is answered. - "text", "reasoning": the agent's answer and its reasoning, growing while `done` is false. - "call": a tool call: the tool `name`, its `input`, its `output` (or why it failed in `text`), the `file` it made, and its `state`: running, approval (waiting for the person), approved, declined, done or failed. - "plan": the agent's plan of the work, a Markdown checklist (one for the conversation, kept up to date). - "error": why the run failed. - "retry" and "stop": the person's wish for the last answer again (from `model`), or for the run to stop. - `id`: `string` - `chat`: `string` - `kind`: `string` - `text`: `string` - `name`: `string` - `input`: `string` - `output`: `string` - `file`: `string` - `files`: `string` - `model`: `string` - `state`: `string` - `done`: `bool` ### `Choice` ```gizlang type Choice = { @Model.Key id: string; @Model.Min(0) name: string; @Model.Min(0) group: string; @Model.Min(0) note: string; } ``` A model a person can choose: its id (as Studio.model takes it), its name, the group it is listed under (where it runs) and a note. `serve` lists the models of this computer, the giz.ai account and AI_URL. - `id`: `string` - `name`: `string` - `group`: `string` - `note`: `string` ### `Plugin` ```gizlang type Plugin = { @Model.Key id: string; @Model.Min(0) agent: string; @Model.MaxLength(80) name: string; @Model.Min(0) address: string; @Model.Min(0) header: string; @Model.Min(0) secret: string; enabled: bool; @Model.Min(0) status: string; } ``` An MCP server whose tools the agent `agent` may use (gizai:mcp): its name (its tools' prefix), its address, the header that carries its key and the key, whether its tools are offered, and what the last run found (its tool count, or why it could not be read). Only public Internet addresses are reached unless CHAT_PRIVATE_PLUGINS=1. - `id`: `string` - `agent`: `string` - `name`: `string` - `address`: `string` - `header`: `string` - `secret`: `string` - `enabled`: `bool` - `status`: `string` ### `Skill` ```gizlang type Skill = { @Model.Key id: string; @Model.Min(0) name: string; @Model.Min(0) description: string; @Model.Min(0) body: string; } ``` How to do one kind of work (a SKILL.md): every agent of the app sees its name and when to use it, and reads its instructions with load_skill when the work is that kind. The person writes it on the Skills tab. - `id`: `string` - `name`: `string` - `description`: `string` — When to use it, in a sentence. - `body`: `string` — Its instructions, in Markdown. ### `Memory` ```gizlang type Memory = { @Model.Key id: string; @Model.Min(0) agent: string; @Model.Min(0) text: string; created: i64; } ``` What the agent `agent` keeps of the person across conversations: a fact or a preference it was told or learned (its tool remember), read back at each run, shown on the agent's Memory tab, where the person deletes it. - `id`: `string` - `agent`: `string` - `text`: `string` - `created`: `i64` ### `Context` ```gizlang type Context = { @Model.Key id: string; used: i64; window: i64; } ``` How full the model's context of the conversation `id` was at its last turn: the tokens it read and wrote, of the model's window. - `id`: `string` - `used`: `i64` - `window`: `i64` ### `Source` ```gizlang type Source = { title: string; url: string; } ``` A page a tool read (a search result, a fetched page), as a chip under its step. - `title`: `string` - `url`: `string` ### `Chip` ```gizlang type Chip = { letter: string; site: string; title: string; url: string; } ``` A source as its chip shows it: the first letter of its site, the site and the page's title. - `letter`: `string` - `site`: `string` - `title`: `string` - `url`: `string` ## Functions ### `skill` ```gizlang function skill(): Skill ``` A new, empty skill. ### `shapes` ```gizlang function shapes(): Vec ``` The tables of agents and conversations, for Pages.app: `Pages.app(sys, site, Chat.shapes())`. Effects: fail, console. ### `item` ```gizlang function item(kind: string, text: string, chat: string = ""): Item ``` A new item of KIND with TEXT in the conversation CHAT. ### `asked` ```gizlang function asked(text: string, chat: string, model: string = "", files: string = ""): Item ``` The person's message TEXT in CHAT to MODEL ("" the agent's): `items.add(Chat.asked(prompt, chat, model))`. ### `retried` ```gizlang function retried(chat: string, model: string = ""): Item ``` The person's wish for the last answer of CHAT again, from MODEL ("" the one it had). ### `stopped` ```gizlang function stopped(chat: string): Item ``` The person's wish that the run of CHAT stops; what it wrote stays. ### `decided` ```gizlang function decided(c: Item, yes: bool): Item ``` The call C as the person decided it: approved or declined. ### `assistant` ```gizlang function assistant(id: string, name: string): Assistant ``` A new agent, as the page adds it. ### `plugin` ```gizlang function plugin(agent: string, address: string): Plugin ``` A new plugin of the agent AGENT at ADDRESS, as the page adds it, enabled and named after its site: mcp.example.com is "example"; an address by number keeps it, as 127_0_0_1. Effects: fail. ### `serve` ```gizlang function serve(app: Pages.Application, ai: Ai.Studio, agent: Agent.Agent): void ``` Runs the agents in the background: each message of the person that is not answered, one at a time, by the agent of its conversation (Assistant: its instructions, model and tools from `agent`'s tools), with the conversation as the history and the model the message asks (Studio.model). The answer is written as items while it comes; a growing text is saved at most every 50 ms. The models the person can choose are listed in the table of Choice. Effects: fail, read, write, console, io. ### `choiceOf` ```gizlang function choiceOf(id: string, fallback: bool = false): Choice ``` The choice of the model ID: "local:NAME" runs on this computer (named as the catalog names it), "giz:NAME" on the giz.ai account, another on AI_URL. Effects: fail. ### `inUse` ```gizlang function inUse(models: Vec, agents: Vec, agent: string): string ``` The name of the model the agent AGENT ("" the first) answers with when the person chooses none: its own, else the default. Effects: fail. ### `chips` ```gizlang function chips(sources: Vec): Vec ``` The chips of SOURCES: one for each site (its first page), six at most, since a chip names a site. Effects: fail. ### `keyed` ```gizlang function keyed(text: string, key: string): string ``` Markdown TEXT as HTML blocks keyed `KEY.N`, so a growing answer is sent by its changed blocks (Markdown.patch). Effects: fail, read, write, console, io. ### `groups` ```gizlang function groups(models: Vec): Vec ``` The groups of MODELS, in the order they first come. Effects: fail.