# Built for AI agents

People, editors and agents use the same `giz` command, the same compiler and the same console
actions. Agents get structured answers, and they pass the same permission checks as people.

:::status{of="agents"}
:::

## Read the docs

| Resource | What it gives |
| --- | --- |
| [/llms.txt](/llms.txt) | Every page of this site as Markdown, in one list |
| [/llms-full.txt](/llms-full.txt) | All the pages in one file |
| `PAGE.md` | Any page as Markdown: add `.md` to its address, for example [/docs/start.md](/docs/start.md) |
| Copy as Markdown | A button on each docs page, with "Open in ChatGPT" and "Open in Claude" |

## Ask the toolchain

Run `giz capabilities` first. Its JSON (`gizlang.capabilities.v1`) names the toolchain, the
release target, the module ABI and the public operations. Keep the project's toolchain unchanged
for the whole of a task.

| Task | Command | Output |
| --- | --- | --- |
| Identify the toolchain | `giz capabilities` | JSON |
| Diagnostics, without running the program | `giz check --json FILE` | JSON |
| Declarations, effects and identities | `giz outline --json FILE` | JSON |
| Change declarations, all or nothing | `giz edit FILE` | Report, or JSON |
| The declarations about some words | `giz context FILE WORD...` | Source text |
| The docs of a module or declaration | `giz doc NAME`, `giz doc --json` | Text, or JSON (`gizlang.reference.v1`) |
| Validate pinned packages offline | `giz get --frozen DIR` | One line for each package |

- Read the exit status together with the output.
- A passing check does not prove runtime behavior. Run the tests.
- `giz get DIR` changes pins. Run it only when you intend to.

## Install without a prompt

The install script asks nothing, so an agent runs the same command as a person:

```sh
curl -fsSL https://gizstack.com/install | sh
```

Gizlang is open source under the MIT [license](/license). The [install guide](/docs/start) has every option.

## Run code over HTTP

`POST /play/run` with a JSON object that has the field `source`. The result has the schema
`gizlang.playground-result.v1`. Check `status` = `completed` before you treat a run as a success.
The [API page](/docs/platform/api) gives the fields and the limits.

```sh
curl -s https://gizstack.com/play/run -H 'Content-Type: application/json' \
  -d '{"source": "function main(): void { print(\"hi\"); }"}'
```

## MCP

:::status{of="mcp"}
:::

The console's actions are MCP tools at `https://gizstack.com/mcp` (Streamable HTTP, JSON), with
`Authorization: Bearer TOKEN`. A token acts for its person, with the person's role in each
organization, and never more. Get one at [gizstack.com/token](/token) after you sign in.

## Team Agents

A team Agent is one record: a name, its instructions, a model, a reasoning effort and the connections it
may use. Make it on the team's **Agents** page (`gizstack.com/TEAM/agents`) or with the `newAgent` action.
Every person talks to it in their own threads, and every place below runs the same loop with the same
record. None of them has a loop of its own.

Every team also has its own Agent, **Giz** (`/TEAM/agents/giz`): the Space's conversation talks with it, and it
is made the first time a member writes there (`ask` with `org` and no `agent`). It is a general agent with no
instructions of its own; like every Agent it reaches the team's Drive and Computers and makes an app with
`newProject`, whose builder then works in the app's own thread.

**In a conversation** the Agent works under the team's Policy. Reads run at once, and whatever cannot be
undone waits for a person's approval as a card in the chat. Its tools:

- The console's actions: apps, deployments, Drive, Databases and Computers.
- `run_code`: model-written JavaScript runs isolated and calls the thread's tools in one step.
- `browseInComputer`: drives the browser of a team Computer.
- `delegate`: runs a task in a child thread, `explore` (reads only) or `worker`, or hands it to another
  Agent of the team.
- The team's connections and skills.
- `remember` and `forget`: notes about the person it talks to.

`/goal TEXT` keeps it working turn after turn until it shows evidence that the goal is met. A long task
compacts itself into a handoff and goes on.

### Connections

The Agent's page connects the team to an outside service by its address. Each Agent uses only the
connections its profile grants.

| Address | Becomes |
| --- | --- |
| An OpenAPI 3 description (JSON) | Its operations are tools. `GET` runs at once; others wait for approval |
| An A2A agent card | One tool that writes to that agent |
| An MCP server (Streamable HTTP) | Its tools, from `tools/list`. `readOnlyHint` tools run at once; others wait for approval |

A connection's secret header is write-only. It goes only to that service and never reaches the model,
the chat record or a page.

### Memory and skills

- **Memory.** The Agent keeps short notes of each person, for that person only. The person sees them on the
  Agent's page and can forget any of them.
- **Skills.** The team writes skills (a name, a description and a body) on the same page. The Agent sees
  each name and description, and reads a body when a task needs it.

### Triggers

A trigger starts the Agent without a person in the chat. It runs as the person who made it, in its own
thread, and is skipped while its last run is still working. It starts in three ways:

- **Every N minutes**, at least 10.
- **A webhook.** Its secret address is shown only to its author. The request body reaches the Agent as data.
- **Run now** on the Agent's page.

```sh
curl -X POST https://gizstack.com/hooks/TRIGGER/KEY -d '{"order": 1042, "status": "late"}'
# 202 {"turn": "...", "thread": "..."}
```

### Responses API

An Agent answers as the OpenAI Responses API at `https://agent.giz.sh/v1/responses`. Its key is the
Agent's secret (Agent page, **On your sites and API**); `model` is the Agent's id. OpenAI's SDKs work with
`base_url = "https://agent.giz.sh/v1"`.

```sh
curl https://agent.giz.sh/v1/responses \
  -H "Authorization: Bearer $AGENT_SECRET" -H "Content-Type: application/json" \
  -d '{"model": "AGENT_ID", "input": "Which orders are late?", "user": "customer-42"}'
```

- `user` names the person of your service (at most 200 characters, no `:`). Each one has their own
  conversations and daily cap.
- `previous_response_id` continues a conversation.
- `stream: true` answers as Responses server-sent events.
- A turn longer than 55 seconds answers `in_progress`; read it again with `GET /v1/responses/resp_TURN`.
  `background: true` answers at once.
- `instructions` is refused: the Agent's instructions live on its page.

### On any site

```html
<script src="https://agent.giz.sh/element.js" async></script>
<giz-agent agent="AGENT_ID" key="pk_..." user="SIGNED_TOKEN"></giz-agent>
```

The Agent's page lists the origins that may show it, and its per-person and per-site daily caps.

- `user` is a person your server signed in: `ID.ISSUED.HMAC`. `ISSUED` is milliseconds since 1970, and
  `HMAC` is the hex HMAC-SHA256 of `ID.ISSUED` under the Agent's secret. It is good for 30 days.
- Without `user`, a visitor may chat only when the page allows anonymous visitors.
- A site's person is not a member of the team. Console and Computer tools refuse them, and an action that
  needs approval is denied.

### From a GizStack app

```gizlang
match (app.agent("support", conversation, question)) {
    Result.ok(a) => { conversation = a.conversation; reply(a.text); }
    Result.err(why) => { reply(why); }
}
```

`App.agent(agent, conversation, text)` asks an Agent of the app's team by slug, and waits up to about a
minute. Pass `""` to start a conversation, then the `conversation` it gives back to go on with it. The app
is an outside principal, as a site's person is, within the Agent's daily caps.

### Agent to agent

- **A2A.** An Agent's card is at `https://gizstack.com/a2a/AGENT` (also `/.well-known/agent-card.json`
  under it). JSON-RPC `message/send`, `tasks/get` and `tasks/cancel` go to the same address with
  `Authorization: Bearer TOKEN`.
- **MCP.** `/mcp` has `listAgents`, `talk` and `awaitTurn`, so an MCP client writes to a team Agent and
  waits for its answer.

## Editors

Editors run `giz lsp` from the same toolchain: diagnostics, symbols, hover with signatures
and effects, definitions and references. The [command line guide](/docs/guides/command-line#editor-setup)
shows VS Code and Neovim.

## Safe by design

- Tests, runs, live updates, builds, dependency changes and publication are separate operations.
  Each one needs its own authority.
- Publication needs a signed-in session or a token, and the organization role.
- Do not put credentials, user data or private source in a published package.