AGW · Put agents to work in your workspace on AGW

Custom agents

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

Define an agent for your task

In AGW, you can combine a model, instructions, and tools into a reusable agent. It assesses the task and context, selects available tools to act, and uses the results to continue its work.

For example, create a documentation reviewer that reads material, identifies unclear passages, and suggests revisions. Add the appropriate tools and permissions when it needs to edit files directly.

Agentflow

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

Arrange defined steps into a workflow

Agentflow means Agent Workflow. Agents reason and act; Agentflow routes work and executes predefined steps. Connect nodes on the canvas to define what happens first, who receives each result, and where human confirmation is required.

For example, an organizing agent decides which information to retain, and a reviewing agent checks for omissions and unclear wording. Agentflow sets the sequence: organize, review, then request human confirmation.

Development setup

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

Prerequisites: .NET 10 SDK, Node.js 24, pnpm 12.5.1 (pinned by packageManager in src/clients/package.json), and Git. Docker Buildx is needed only for container images. These application commands run in the AGW repository; the documentation site does not depend on this toolchain.

Backend

git clone https://github.com/zxyao145/agw.git
cd agw
git config core.hooksPath .githooks
dotnet restore Agw.slnx
dotnet tool restore
dotnet run --project src/server/Agw.Standalone.Host

Initialize at http://localhost:30816/setup. Replace dotnet run with dotnet watch for hot reload.

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.

Shared context across agents

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

Let agents build on each other’s work

Use different agents to analyze requirements, write code, and review results. When you switch targets within the same conversation in a Project, AGW supplies the receiving agent with new public text from the other targets, reducing the need to copy background information and progress updates.

For example, let Coding make a change, switch to Review to assess it using the discussion so far, then switch back to Coding to address the feedback.

Standalone and Docker

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

Standalone provides management pages, conversations, and scheduled jobs in one Server. It suits a local trial or a single host. Defaults use SQLite for storage and run tasks in the Server process, without a separate database service.

Use the Docker image, or build a Portable Server for your operating system and processor. Both include Web. Start with local access, then configure directory mounts and remote access as needed.

Local Docker trial

docker run -d --name agw \
 --restart unless-stopped \
 -p 127.0.0.1:30816:8080 \
 -v agw-data:/data \
 ghcr.io/zxyao145/agw:latest

Open http://localhost:30816/setup and initialize. Through a Docker port mapping, the container does not see a loopback source address, so Setup asks for the one-time Setup Code; find “Agw remote setup code” in the startup log with docker logs agw. The image includes static Web assets, so the browser connects directly to Server. latest is convenient for evaluation; use a fixed release tag for a maintained deployment.

What is AGW?

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

AGW is a self-hosted agent workspace for individuals and small engineering teams. It can also serve as an agent gateway. A shared interface brings together custom agents and external agents such as Claude Code, Codex, and Pi, with conversations and execution records organized around projects.

AGW Desktop chat: select a Project and Agent, then enter a message.

Core concepts

Concept	Purpose
Model Provider	Connect a provider and model into a usable model configuration
Agent	Configure instructions, a model, and capabilities, or connect an external agent
Project	A task space containing working directories, context, and conversations
Chat	Start interactive execution, inspect messages and tool activity, and answer human input requests
Agentflow	Connect nodes into an executable workflow
Job	Trigger an agent or agentflow once, at an interval, or on a Cron schedule

See Core concepts for the distinctions and how they work together.

Core concepts

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

In AGW, models provide reasoning, agents organize instructions and capabilities, and Projects provide a workspace. Use Chat to interact with an agent, Agentflows to orchestrate steps, and Jobs to schedule execution.

Models and Model Providers

Model configuration has three layers:

Concept	What it describes
Provider	The model service protocol, endpoint, and authentication
Model	The model identifier, context window, maximum output, and other specifications
Model Provider	A link between a model and the service providing it, selectable by an agent

For example, you can link the same model to different Providers, then choose the actual connection for an agent. See Model providers for configuration.

Architecture and module boundaries

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

Prerequisite: a working source setup. Identify the business owner of a use case before tracing cross-module capabilities through Contracts.

Backend organization

AGW is a modular monolith. Agw.Host supplies shared hosting; Control Plane, Data Plane, and Standalone compose the modules they need. Business modules follow Api → Application → Domain ← Infrastructure, creating only necessary layers.

flowchart LR
 API[Api] --> APP[Application]
 APP --> DOMAIN[Domain]
 INFRA[Infrastructure] --> DOMAIN

Layer	Responsibility	What to inspect
Api	Receive requests and return responses	Routes, inputs, and outputs
Application	Complete a business operation	Authorization, queries, transactions, and call order
Domain	Hold business data and express rules	Entities, Behaviors, and DomainServices
Infrastructure	Connect databases and external systems	Persistence and concrete adapters

Domain entities hold state. A Behavior handles rules within one Aggregate, while a DomainService handles rules that need facts beyond it. Application loads data, coordinates these calls, and persists changes. Ordinary CRUD stays in Application without creating a Behavior for every entity.

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.

Image input

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

Add visual context

Attach images when asking about a UI problem, design, or chart. For example, send an error screenshot with the steps that led to it, or ask a vision-capable model to inspect a page layout.

Ask a specific question

For example: “The Save button is obscured in this screenshot. Identify possible layout problems and tell me what else you need to know.” When comparing images, label the expected design and the current page so the agent can focus on the difference.

Install and configure Server

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

AGW needs a running Server and a client to operate it. For a first local installation, choose Desktop Full. If Server already exists, use Desktop Client or a browser. After installation, configure a model service or external agent to start a conversation.

Installation paths

Method	Best for	Key differences
Desktop Full	A local graphical workspace	Installs both the desktop client and Server; Server runs as a current-user background service
Desktop Client	Connecting to an existing Server	Installs only the desktop client, without Server; connects to a local or remote Server
Docker	Containerized self-hosting	Runs Server in a container with Web included; mounts provide persistent data and workspace access
Portable Server	Hosting directly on a machine	Runs the Server executable directly with Web included; no Docker or desktop client required
Source	Development and debugging	Build and run the backend and required clients yourself to modify code and debug modules

Desktop

Open GitHub Releases.
Select Full or Client for your platform. Windows and Ubuntu currently support x64; macOS supports x64 and arm64.
Complete initialization on the first Full launch, or connect Client to an existing Server.

Full and Client share an application identity and are mutually exclusive variants. Full installs a current-user Server daemon; closing Desktop does not stop it. Packages are currently unsigned and not notarized.

Split Control/Data Plane deployment

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

Split deployment runs management and scheduling in Control Plane and task execution in Data Plane. Use it when execution environments need separate maintenance or additional nodes. For a trial on one host, Standalone is simpler to configure.

This page assumes familiarity with containers, databases, and reverse proxies. Prepare shared PostgreSQL, Data Protection keys for decrypting credentials, and workspaces accessible to every execution node. The entry proxy must support WebSocket for conversation events.

APIs and execution protocols

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

Prerequisites: access to a development Server and a valid authenticated identity, such as an API Key or a browser session. Use current OpenAPI and owning-module Contracts for exact fields; this site does not duplicate the complete schema.

Protocol boundaries

Interface	Purpose and contract
Management JSON APIs	Bens.Results `ApiResult` envelopes, unwrapped by typed client helpers
`/api/hubs/exec`	SignalR execution commands, state, and events; mapped by Data Plane and Standalone only and accepts only the WebSocket transport. The official client connects with `skipNegotiation: true`
`/api/agents/permission-capabilities`	Query supported permissions for a target
`/api/auth/oidc/providers`	Enabled sign-in providers, used to render the sign-in buttons
`/api/auth/oidc/login`	Redirects to the provider; `client` is `web` or `desktop`
`/api/auth/desktop/exchange`	Desktop exchanges a one-time code plus its verifier for an API Key
A2A	Protocol-specific responses, mapped by Data Plane and Standalone only
`/openapi/*`	Contract entry point; served, together with the Scalar API reference, only in the Development environment by Control Plane or Standalone

Sign-in routes are served by Control Plane and Standalone. An API Key obtained by Desktop behaves like a manually created one and accesses resources as its creator.

Configuration and authentication

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

This page covers deployment settings consumed by AGW Server and logging settings in the Host template. Configure models, Agents, Projects, and integration accounts through the management UI as described in their guides. Choose your deployment mode first, then apply changes and restart the relevant Hosts.

Start with the settings relevant to your task

For an initial local setup, keep defaults and complete initialization. Before relying on the service, locate its database and data directory and follow the backup guide.

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.

Memory: preferences and project knowledge

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

Keep information worth reusing

A conversation may end while working preferences and project knowledge remain useful. AGW provides two kinds of Memory for later work.

Memory	Good for	Scope
User Memory	Personal preferences, writing conventions, lasting background	The current user, across Projects
Project Memory	Project conventions, decisions, working notes	The project’s working context

Configure the appropriate Memory capability on an Agent or Project, then ask the agent to save information and check or update it in later conversations. Memory needs deliberate maintenance; it does not automatically retain and inject every chat message forever. User Memory is isolated by user. Project Memory scope also depends on the project and storage choice; filesystem memory is shared when workspaces are shared. External agents (Claude Code, Codex, Pi) only receive existing User Memory entries (up to 50) as read-only context. They get no memory tools, so they cannot save or update memory, and Project Memory configured on the Agent or Project does not apply to them.

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.

Data, backups, and upgrades

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

A complete backup includes AGW configuration and records, encryption keys, and project files. Copying only the installation directory or code repository can leave out data needed to restore the service.

Locate the actual database, data directory, and Project workspaces first. Use the defaults below as a guide and confirm them against the running configuration.

What to preserve

AgwDataDir defaults to ~/agw; Docker uses /data. Paths expand ~; other relative paths resolve from the process working directory. The default SQLite database file is <AgwDataDir>/database/agw.db, or /data/database/agw.db in Docker.

Extend tools and integrations

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

Prerequisites: understand module boundaries and decide whether the capability is general-purpose or business-owned. Begin with one small, verifiable capability.

Tool extension path

Put hand-written IAgwTool, IContextualTool, and IToolBlock implementations in Agw.Tools; the global catalog scans only that assembly for hand-written tools. Business tools belong in their module’s Application/Tools, declared as attributed containers or supplied through a Skill, with DTOs in Contracts/Tools.
Reference Agw.Tools.Abstractions; add Agw.Tools.Generators as an Analyzer for attributed declarations.
Explicitly declare permissions, argument descriptions, and return types. Standalone tools and attributed containers stay stateless; session state belongs in a Provider, session, or owned storage.
Register services and generated declarations in the owning module. Choose Skill exposure or explicit global catalog inclusion.
Verify discovery, arguments, permissions, project binding, and error mapping.

The generator emits metadata, JSON Schema, and direct invocation delegates. Do not add runtime reflection scanning as a fallback. Skill tools come from two members: IAgentSkillRegistration.Tools supplies hand-written IProjectScopedAgwTool instances, and ToolTypes supplies attributed container types generated through IAgwToolSet<T>. They bind to a Project during execution. Registering a generated module does not automatically expose every tool globally.

Plan and Execute modes

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

Plan before taking action

Before changing code or starting a complex task, ask an agent to assess the situation and propose an approach. Configure the Mode ToolBlock on a custom agent or a Project to give custom agents Plan and Execute modes; on a Project, every custom agent running in that Project receives it.

Mode	Useful for	Tool behavior
Plan	Inspecting the situation, analyzing problems, proposing an approach	Only tools explicitly allowed in Plan are available
Execute	Carrying out an agreed approach	Configured tools remain subject to permissions and approval rules

Example: revising documentation

In Plan, ask: “Read the documentation and identify unclear terms and missing examples. Propose changes first.” Review the scope, then switch to Execute and ask the agent to apply the agreed changes. Inspect the diff to confirm that facts and limits were preserved.

Start your first conversation

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

Prerequisites: initialization is complete, the management UI is accessible, and you have model provider credentials. This path creates a custom agent and does not require an external CLI.

1. Set up a model connection

Open model management and configure the three items below. The form layout may vary by client, but the information is the same.

Setting	What to prepare	Purpose
Provider	The service’s protocol, API endpoint, and API key	Where AGW sends requests and how it authenticates
Model	The exact model ID, context window, and maximum output length	Which model to use and its content limits
Model Provider	A link between the model and provider	The working connection an agent selects

Use the model ID supplied by the service. Model discovery may suggest 256,000 / 64,000 for context and output limits; replace these defaults with the model’s actual specifications. See Model providers for field details.

Structured responses with JSON Schema

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

Make replies readable by programs

Agents return Markdown text by default, which reads well but is awkward to parse. Configure a Response Schema on an agent and its final reply becomes a JSON object matching the JSON Schema you supply, so Jobs, Agentflows, and API callers can read named fields directly.

For example, a documentation reviewer can return an issues array whose entries contain original, problem, and suggestion. A scheduled run can then file each entry as a ticket instead of searching through prose.

Logs and troubleshooting

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

First locate the failing step: opening the page, signing in, calling a model, or using files and tools. Reproduce the problem with a small task so that each check narrows the cause.

Record the Server, Project, conversation, and time, then inspect the matching logs. In a split deployment, check Control Plane for management problems and Data Plane for execution problems.

Diagnostic order

Symptom	Check first
UI unavailable	Listener, port, container mapping, proxy target
Setup fails	Database connection, writable directories, remote Setup Code
Login or API Key fails	Actual Server, revoked API Key, database auth state
Third-party sign-in fails	`Auth:Oidc:PublicBaseUrl`, the callback URL registered at the provider, client credentials, Server-to-provider network
No agent response	Model Provider, model ID, credentials, pending approval/input
CLI cannot start	Execution-node executable, account, environment
Files missing	Selected root, Server path, mounts, permissions
Job does not run	Enablement, future timestamp, UTC Cron, valid target, logs
Wrong state after disconnect	Conversation selection, WebSocket proxy, background execution; in InProcess mode, running conversations show Interrupted after a Server restart and do not continue

Example: the page opens but the agent does not reply

Check whether Chat is waiting for approval or information, and respond if needed.
Send a plain text question through the same model connection. If it fails, check the API endpoint, model ID, and credentials.
If text works but a tool task fails, check tool bindings, directories, and host permissions.
In split deployments, a working management page with a failed chat connection suggests checking that /api/hubs/exec routes to Data Plane and supports WebSocket.
Find the specific error in Server logs at the recorded time. Repeat the same small task after the fix.

This sequence separates model, tool, and connection failures without changing several settings at once.

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.

Testing and contribution

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

Prerequisite: dependencies are installed. Read root AGENTS.md and the relevant rules under docs/human/ before changes, and preserve unrelated local work.

Backend checks

From the repository root:

dotnet build Agw.slnx
dotnet test Agw.slnx
dotnet csharpier check .

Test projects use xUnit v3 and run on Microsoft.Testing.Platform, selected by the root global.json. Start with relevant tests when investigating a failure, such as dotnet test tests/Agw.Files.Tests. Unit and composition tests use real implementations and pure option helpers, never mocks or fake implementations. Constructing CodexAIAgent or ClaudeCodeAIAgent probes the CLI, so those tests run as real CLI tests: they are opt-in, require the executable, and stay out of the default suite.

Tool approval

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

Confirm before an operation

When an agent calls a tool, AGW can ask for confirmation according to your permission settings. Inspect the tool name and arguments before deciding whether it should proceed, particularly for file changes or command execution.

Permission mode	Ordinary write and execution tools
Always ask	Ask for confirmation on every call
Allow same arguments	After approval, reuse a matching argument grant within the current session
Full access	Automatically approve ordinary tool calls

Ordinary read-only tools generally need no execution approval. Approval requirements come from the tool’s declared permission, not whether its name or command looks harmless.

File browsing and Git change review

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

Review agent changes next to the conversation

After an agent edits code, you need to see which files changed and whether each edit is what you expected. Switch to Files in the Chat workspace to browse the Project workspace, inspect Git changes, and turn the spots that need work into line comments for the agent, all without opening a separate editor or terminal.

AGW Files view: browse Project files and Git changes on the left, view file content or a diff on the right, and comment on code lines.

Inspect changes

Turn on the Diff switch at the top of the file tree to show only files with Git changes, grouped into Staged and Unstaged. A file with both staged and unstaged edits appears once in each group. The letter next to a file name shows the change type: A added, M modified, D deleted, U untracked.

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.

Multiple clients

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

Continue on the device that fits

AGW provides Web, Desktop, and Mobile clients. Connect to the same Server with the appropriate identity to access your authorized projects and saved conversation history, choosing the device that suits the task.

Client	Useful for
Web	Management and chat in a browser without a desktop installation
Desktop	A daily workspace, multiple Server profiles, local or remote use
Mobile	Checking conversations, accessing projects, and continuing discussions on the go

The AGW Desktop chat workspace; Web and Mobile use interfaces adapted to their platforms.

The same Server versus a different Server

To continue on another device, connect to the same Server and select the same Project and conversation. Saved history is available there; recent output may need time to persist or a state check after reconnecting.

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.

Third-party account sign-in

Wed, 23 Sep 2026 00:00:00 +0000

Use an existing account to reach your own workspace

Once an operator enables identity providers on Server, the sign-in page shows “Continue with …” buttons. Authenticate with an organization account such as Keycloak, Microsoft Entra ID, or Google, or with an OAuth2 service such as GitHub, and you reach AGW without a shared administrator password.

The first sign-in with an account creates an isolated local user and prepares its default Project. From then on, its agents, projects, conversations, integration connections, and API Keys belong to that user and stay invisible to others. The administrator account is unchanged.

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.