User guide on AGW

Model providers

Fri, 25 Sep 2026 00:00:00 +0000

Before a custom agent can answer, AGW needs to know which model to use, where to send requests, and how to authenticate. Prepare the API endpoint, model ID, and API key supplied by your model service.

This page covers model configuration in AGW. To use an existing command-line setup, see External agents.

Three configuration objects

A Provider describes the endpoint and authentication. A Model describes a model and its limits. A Model Provider links the two for agent selection. Creating a Model alone does not establish a connection.

Create a custom agent

Fri, 25 Sep 2026 00:00:00 +0000

An agent is a reusable assistant configuration. Its model interprets requests, its instructions define the task, and its tools determine which operations it can perform. For example, create separate agents for explaining code and reviewing documentation, then select one in Chat.

Start with a working Model Provider. This page covers custom agents run by AGW; see External agents for Claude Code, Codex, and Pi.

Create an agent

Open Agents and click Create. Keep Agent Type set to System (a custom agent) and enter a Display Name that describes its responsibility.
Select a Model Provider. In Instructions, describe the task, input, and expected output. Create stays disabled until the Display Name and Model Provider are set.
Configure capabilities as needed in the Tools, Skills, MCP Tool Server, Integrations, and Environment Variables tabs. File capabilities require a correct Project workspace.
Save, confirm the agent is enabled, and run a small task in Chat.

For example, start with a “Code explainer” that answers questions, then add read-only file capabilities after verifying the model. Instructions cannot grant tool access beyond execution permissions.

Connect external agents

Fri, 25 Sep 2026 00:00:00 +0000

When you connect an external agent, tools such as Claude Code, Codex, or Pi perform the actual work. AGW provides a shared interface for configuration, conversations, and workflows, so you can keep using familiar tools while managing how you use them in AGW.

Prerequisites: the matching CLI is installed on the execution node and works under the Server’s account and environment. Installing it on a browser machine is insufficient; container execution needs the CLI inside the container.

Chat and execution history

Fri, 25 Sep 2026 00:00:00 +0000

Chat is where you send tasks to an agent or agentflow and inspect the results. Keep related questions in one conversation to retain the discussion and tool activity; start another conversation for a different topic.

Connect to the intended Server and prepare a working agent or agentflow. For an initial setup, follow Your first conversation.

An interaction

Open Chat and select the Project: in Desktop, use the project tabs at the top of the window; in Web, use the dropdown at the top of the left sidebar. Then choose the execution target in the selector at the top-left of the message box.
Enter the task, optionally attach images, and press Ctrl/Shift+Enter or click the send button. Enter alone inserts a new line.
Read streamed output and tool activity. Handle approval or user input requests in the conversation.
Review the conversation history and final execution state.

Web, Desktop, and Mobile accept text plus JPEG, PNG, GIF, or WebP images. Paste images in Web and Desktop; choose them from the photo library on Mobile. A message may contain up to five images, each at most 5 MB and at most 10 MB combined. Image understanding also depends on the model.

Projects, files, and workspaces

Fri, 25 Sep 2026 00:00:00 +0000

A Project keeps a task’s directories, background information, and conversations together. For a code repository, you might create separate conversations for code exploration and troubleshooting while using the same workspace.

The account running AGW Server must be able to access these directories. Saving a Project creates a missing primary directory automatically; additional directories must already exist, use an absolute or ~ path, and not duplicate another directory. With a remote Server, enter a path on that host. With Docker, enter the path inside the container.

Agentflow

Fri, 25 Sep 2026 00:00:00 +0000

Agentflow means Agent Workflow: a workflow that connects several processing steps. One agent might prepare material, another review it, and a person approve the result. The canvas shows the steps, their inputs and outputs, and their order.

Verify each agent independently before connecting it. Start with one path from input to output, then add branches and approvals once it works.

Build the first flow

Open the Agentflows editor and start with its single Input node.
Add an Agent node, select a verified agent, and connect Input to Agent.
Add and connect Output, save, then select the Agentflow in Chat and run it.
After the basic path works, introduce HumanGate, branches, or parallel nodes.

The editor canvas has Undo and Redo buttons at its top right, also available as Cmd/Ctrl+Z, Cmd/Ctrl+Shift+Z, or Ctrl+Y. Drag the dividers to resize the node palette and Inspector. With unsaved edits, the dialog shows Unsaved changes and asks Discard unsaved changes? before closing; unsaved drafts are not kept after the dialog closes.

Scheduled jobs

Fri, 25 Sep 2026 00:00:00 +0000

A Job runs an agent or agentflow at a scheduled time, such as for a routine check or recurring summary. Save its instructions, Project, and schedule; Server starts the task when due and records each outcome.

First verify the same task manually in Chat, including its model, tools, and directories. Server must stay running. In split deployments, Control Plane schedules the work and Data Plane executes it.

Configure a job

Create a Job, choose its Project in Project ID, and choose the Agent or Agentflow to run in Agent ID. A job without a target still saves, but fails at run time and enters retries.
Write its prompt, choose a Trigger Type, and enter the run time or trigger value.
To change the name, failure retries, or enabled state, click Advanced at the bottom of the dialog and use Job Name, Max Retry Count, and Enabled. Max Retry Count defaults to 3 and new jobs are enabled; a blank Job Name is generated automatically.
Test a future one-time job first. After Job logs and project execution records look right, create a separate recurring job. A successful one-time job pauses and disables itself; switching it to a recurring trigger or enabling it again does not make it run.

Trigger	Example	Time semantics
Once	A future RFC 3339 timestamp, such as a UTC value ending in `Z`	Must be in the future
Interval	`00:15:00`	A positive duration in hours:minutes:seconds. The first run is 15 minutes after creation; each later run is 15 minutes after the previous successful run ends
Cron	`0 1 * * *`	Standard five fields, evaluated in UTC; daily at 01:00 UTC

Clients display local time, but Cron uses UTC. A past Once timestamp does not mean “run immediately.” If an Interval is not a positive hours:minutes:seconds duration, or a Cron value does not have five fields, an error appears below the field and the save button stays disabled. A five-field Cron with invalid field values is rejected by the Server on save with “Invalid cron trigger value”. After saving, check the next execution time in Next Run in the job list.

Tools and Skills

Fri, 25 Sep 2026 00:00:00 +0000

A Tool performs an operation, such as reading a file. A Skill supplies instructions, resources, and optional tools for a type of task. Decide what the agent needs to read or change, then select the relevant tools and guidance.

The steps below assume an existing custom agent and Project. External agents configure capabilities through their own supported mechanisms.

Add capabilities

Review the selectable tools in the Tools tab of an Agent or Project. ToolBlock cards show a description and member tools, plus an Approval badge when a call may need approval; individual tools appear in a dropdown with name, description, and category.
Manage available Skills and read their instructions and prerequisites.
Bind the tools and Skills needed for this task to the agent.
Start a new turn in the correct Project. Verify read operations before testing necessary writes.

Every tool explicitly declares AgwToolPermission. The execution pipeline checks permissions; saying “allowed” in a prompt does not bypass permission or ownership checks.

MCP servers

Fri, 25 Sep 2026 00:00:00 +0000

MCP (Model Context Protocol) lets agents use tools from another service. An MCP server describes the operations it offers; AGW connects to it and makes those tools available to a custom agent. The available operations depend on the service.

Prepare the service’s launch command or URL, transport, and required credentials. The model itself is configured separately through a Model Provider.

Connect

On the MCP Tool Servers page, click Add Server, choose stdio or http in Transport Type, and enter the command or endpoint and credentials the service requires.
Local-process servers must be launchable on the execution node; remote services must be reachable from that node.
Click Connect and list tools in the list to check connectivity; success shows “N tools available”. Make sure Enabled is on, because disabled servers are not used.
Bind the service in the MCP Tool Server tab of a custom agent or Project, then start a new turn. A run uses every server bound to the Agent and the Project.
Inspect discovered tools and validate a read-only operation.

Directories, commands, and network access belong to the actual Server/execution node. Connecting a remote Desktop does not automatically expose locally installed MCP services to the Server.

Configure integrations

Fri, 25 Sep 2026 00:00:00 +0000

Integrations let custom agents use authorized external accounts, for example to read information from GitHub. Configure several accounts for one service and choose which one an agent uses. The built-in catalog currently provides GitHub.

Prepare the required authentication details and check that the account can access the resources needed for your task.

From definition to connection

Available integrations: global catalog definitions available for configuration.
Configured integrations: accounts or service endpoints configured by the current user.
Connection: the concrete instance selected and bound; one integration can have several accounts.

On the GitHub card in Available integrations, click Configure and complete the setup required by the chosen authentication method. GitHub OAuth needs the Client ID and Client Secret of an OAuth App; register the OAuth callback URL shown in the dialog with that OAuth App.
On the catalog card, click New integration in the row for the authentication method you want, and enter a Display name and a clear Alias. After a new OAuth Connection is saved, AGW opens the authorization page automatically.
Confirm it is Ready, then bind the specific connection to an Agent or Project. Use Authorize on the connection card to authorize again and Validate to recheck the connection.
Run a read operation in a new custom-agent turn and verify the intended account is used.

Aliases are immutable after creation and unique per user. They allow only lowercase letters, digits, and single hyphens, up to 128 characters; uppercase input is converted to lowercase. Tool names follow {alias}__{operation} to distinguish accounts. A GitHub connection provides {alias}__current_user, {alias}__list_repositories, and {alias}__clone_repository, which read the current account, list visible repositories, and clone a repository into the current Project workspace.

Web, Desktop, and Mobile

Fri, 25 Sep 2026 00:00:00 +0000

Prerequisite: an initialized Server. Clients do not replace the Server-side model, file, or execution environment.

Client	Connection	Use case
Web	Session Cookie from the administrator password or a third-party account; same-origin APIs	Browser management and chat
Desktop	API Key, entered manually or issued by third-party sign-in; multiple Server profiles	Local or remote daily workspace
Mobile	API Key, entered manually or imported from a configuration generated in Web; multiple Server profiles	Conversations and project access on mobile

Connect

For Web, open the Server URL, or port 3001 during source development.
Desktop Full can use its bundled Server. In Client, open Settings → Connections & app, click + (Add remote Server), and enter Name, Server URL, and API token. A remote http:// URL requires ticking a consent box acknowledging that the API token and traffic cross the network unencrypted.
Configure Mobile with a Server URL reachable from the device and an API Key. Device localhost usually is not your development computer. Alternatively, create an API Key in Web under Settings → Server access, click Copy config, and paste it into Import Web configuration on Mobile. Deleting a Mobile profile does not revoke its API Key on the Server; revoke it in Web.
Start a short conversation and verify the target Server, Project, and history.

Desktop centers on Chat; Projects and other administration routes live in Settings. Each Server profile uses an isolated cache. Changing its URL or API Key discards the old connection’s cache so data from different Servers does not get mixed.