Skip to main content

Agent Tools

The agent can call built-in tools, and you control which are enabled and how risky ones are gated.

Image generation & editing​

Enable generation and editing (via the Azure OpenAI Images API) by adding a single image offering to your model offering catalog (model_offerings.jsonc) -- author it with the in-app Model Settings screen, chatwalaau models add, or by hand. gpt-image-2 is the suggested model:

{
  "id": "image",
  "provider": "azure-openai",
  "operations": ["image"],
  "model_ref": "gpt-image-2",
  "api_version": "2025-04-01-preview"
}
  • generate_image -- create images from text with configurable size, quality, format, background, and count (1-4)
  • edit_image -- modify existing session images from a text prompt
  • Canvas Mask Editor -- click Edit on any generated image, draw over the region to change (brush S/M/L, eraser, undo/redo), enter a prompt, and only the masked area is edited
  • Images render inline and persist across reloads

With no image offering, the image tools are simply not available (the app starts normally); add the offering to turn them on.

Customize image output​

Use the Image button next to the model controls to set per-session defaults for Size, Quality, Format, Compression (JPEG/WebP only), and Background. The choice is remembered per chat and applied as the default for the next image; the model can still override a field when a request needs a specific one.

You can also set instance-wide defaults on the image offering's optional image_defaults block (applied when neither the picker nor the model provides a value). The Model Settings Image card has inputs for each:

{
  "id": "image",
  "provider": "azure-openai",
  "operations": ["image"],
  "model_ref": "gpt-image-2",
  "api_version": "2025-04-01-preview",
  "image_defaults": {
    "size": "auto",          // auto | 1024x1024 | 1024x1536 | 1536x1024
    "quality": "auto",       // auto | low | medium | high
    "format": "png",         // png | jpeg | webp
    "compression": null,     // 0-100; JPEG/WebP only; null = API default
    "background": "auto"     // auto | transparent | opaque
  }
}

If your image model requires a newer Images API preview, set the offering's api_version to the version your Azure deployment supports.

Weather​

Rich weather card widgets powered by Open-Meteo (free, no API key). The agent geocodes a city and fetches current conditions or a 7-day forecast on demand.

Coding tools​

File operations and shell execution, restricted to a workspace directory:

CODING_ENABLED=true
CODING_WORKSPACE_DIR=C:\path\to\workspace
# CODING_FILE_READ_MAX_BYTES=1048576   # 1 MiB default

file_read caps output at CODING_FILE_READ_MAX_BYTES; when the cap or a line limit is hit, the response ends with a [TRUNCATED BY BYTES: ...] / [TRUNCATED BY LIMIT: ...] marker telling the agent how to paginate with offset=N.

Tool approval​

Destructive coding tools pause for an inline Approve / Reject / Approve for this session decision. Read-only tools (file_read, file_glob, file_grep) never require approval. Each approval card shows a round counter (round N / MAX).

# auto (default) -> gate bash_execute + file_write
# always         -> gate every non-read-only tool
# skip           -> disable approval (autonomous)
TOOL_APPROVAL_MODE=auto
TOOL_APPROVAL_REQUIRE_LIST=bash_execute,file_write
TOOL_APPROVAL_TIMEOUT_SEC=300
# How many times per turn you can be asked to decide (default 33).
# "Approve for this session" rounds do NOT count against this.
TOOL_APPROVAL_MAX_ITERATIONS=33
# Absolute backstop counting every round (incl. session-approved ones) so a
# runaway agent always stops. Must be >= TOOL_APPROVAL_MAX_ITERATIONS.
TOOL_APPROVAL_ABSOLUTE_MAX_ITERATIONS=200

With TOOL_APPROVAL_MODE=skip, the SPA shows a persistent "Tool approval is DISABLED" banner. Headless lanes (OpenAI API, the chatwalaau chat CLI, DevUI) auto-approve every request and log a WARNING per auto-approval.

Approve for this session. Checking "approve all X calls in this session" on a card and approving it grants that tool for the rest of the chat. Those auto-approved rounds are free -- they do not count toward TOOL_APPROVAL_MAX_ITERATIONS, so the round counter freezes and a long blanket-approved run no longer stops early. When several cards for the same tool are showing at once, that one decision also collapses the other displayed cards of that tool. Microsoft Teams behaves the same way (the Adaptive Card shows the counter and "Allow Session" cascades).

Conversation compaction​

Long sessions are compacted in memory before each model call (the on-disk session JSON is never altered) so the agent keeps responding instead of failing at the context-window limit:

# none | sliding-window (default) | selective-tool-call | tool-result
COMPACTION_STRATEGY=sliding-window
COMPACTION_KEEP_LAST_GROUPS=4
COMPACTION_PRESERVE_SYSTEM=true

Background Responses​

For long-running operations (e.g. o3/o4-mini reasoning), toggle the BG button (left of the context indicator). The ChatInput border turns blue, and continuation tokens are auto-saved to the session for page-reload resumption. No environment variable needed.

Background and Agent Skills cannot be combined

While BG is on, Agent Skills are not available for that turn — the skill tools are not offered to the model, and the toggle's tooltip says so before you send.

A background response is produced server-side and resumed later by id, which cannot complete a skill's tool call: such a turn used to fail outright with No tool call found for function call id call_.... Making the two exclusive removes that failure. Function tools, MCP tools and web search are unaffected.

Prompt Templates​

Save and reuse prompts from the chat interface (stored as JSON files):

TEMPLATES_DIR=.templates

Open the + menu -> Use template, or click the FileText icon on any user message to save it as a template. Insert to Chat pastes a template into the input for editing before send.

Agent Skills​

Portable domain-knowledge packages following the Agent Skills specification, loaded on demand:

SKILLS_DIR=.skills
.skills/
  my-skill/
    SKILL.md       # required: instructions + metadata
    scripts/       # optional: executable code
    references/    # optional: documentation
    assets/        # optional: templates, resources

Skills use progressive disclosure (~100 tokens per skill when idle) to keep context-window usage low.

One SKILL.md per skill

A skill folder is a boundary. If you put another SKILL.md in a subfolder of a skill, it is not discovered as a second skill -- everything below a skill folder belongs to that skill. Use sibling folders (or one grouping level, .skills/<group>/<skill>/SKILL.md) when you want two separate skills.

Manage skills at runtime​

A Skills icon in the chat input controls row opens a management modal where you can enable or disable skills while the server is running -- no file edits, no restart. Skills are organized by folder group (A/B/SKILL.md shows as group A, skill B; B/SKILL.md is ungrouped). A group checkbox bulk-toggles every skill under it, and each skill shows its description as an overview.

Disabling unused skills bounds the per-turn token cost: a disabled skill leaves the advertised set entirely (and disabling every skill removes the skill tooling too). Save shows a confirmation, then a brief rebuilding indicator while the agents are reconstructed; the next message advertises only the skills you kept.

The selection is in-memory only -- a restart re-enables every skill -- and skill files on disk are never modified. The management endpoints (GET / PUT /api/skills) are auth-gated; localhost stays zero-config. (This is the Skills counterpart of the MCP Tool Management modal.)

Reload (footer + empty state) re-reads SKILL.md from your skills directory and rebuilds the agents -- so a skill folder you added or removed on disk is picked up without a restart. Reload asks for confirmation and shows the same blocking indicator. The icon is always shown when the endpoint is reachable, so even with no skills yet you get an empty state with your skills directory and a Reload button. A skill found on disk but not loaded yet (added since the last build) appears with a disabled toggle and a "Reload to apply" hint until you reload.