Get started
OpenAgent Developer Documentation
This handbook is for developers taking on OpenAgent for the first time. It covers the complete lifecycle: creating a draft on the website, implementing the Program in an isolated Workspace, validating it through WebChat, publishing it, and putting it online. Follow the Quick Start in order; no prior knowledge of the platform's internal services is required.
Recommended path
In the version workspace on the website, click Build With Local Agent, copy the complete trusted prompt, and pass it unchanged to your local AI. The prompt is already bound to the current Agent and version. The local AI will follow the platform Skill and use the verified CLI to create a development Workspace.
What you will have when you finish
- An OpenAgent owned by your current account and a draft version that you can continue editing.
- An isolated development Workspace in the
activestate, with its project directory fixed at/oasn. - An Agent Program that runs in Workspace WebChat and has been tested for normal, boundary, and failure scenarios.
- A complete Agent Card, MOM, model capabilities, CPU/Memory allocation, and pricing configuration.
- A published version that you explicitly put online with Go Online, then formally acceptance-test from a real client after installing it in ChatGPT, Claude, or WorkBuddy from the public Agent page.
Development lifecycle
Create an Agent and its first draft
Sign in to the website, open Developer, and click Create. The current implementation creates the Agent and its first draft version in one operation, then opens the version workspace.Hand the version context to your local AI
In the version workspace, click Build With Local Agent and copy the complete trusted prompt. Do not change the Skill URL, operation type, or bound IDs.Create a Workspace and implement the Program
The local AI uses the CLI to complete browser sign-in and create the Workspace. After it reachesstatus=active, runworkspace connectto bind an existing local public key and verify real SSH authentication. Use the returned SSH, SCP, and WebChat information only whenssh_binding_status=boundandssh_verified=true.Complete presentation and billing configuration
Return to the version workspace to configure the Agent Card, MOM, model capabilities, CPU/Memory under Resources, and cost-plus pricing, then save the draft.Validate, publish, and go online
Finish development testing in WebChat before publishing. A successfully published version is Offline by default. Click Go Online, open its details from the public Agent link in the publish result (or by searching the exact name in the public Agents list), install it through Use in ChatGPT/Claude/WorkBuddy, and complete one formal invocation from the actual client.
Three IDs you must not confuse
| Identifier | What it represents | When it is needed | Reliable source |
|---|---|---|---|
agent_id | The long-lived identity of an Agent | Viewing Agent details and binding context in the trusted prompt | Agent details on the website; the complete prompt generated by Build With Local Agent |
agent_version_id | A specific draft/version | Creating a development Workspace and binding this build | The version workspace URL; the trusted prompt |
workspace_id | One isolated development environment | Checking status after a creation timeout and identifying the current Workspace | The CLI creation result or a WORKSPACE_TIMEOUT error |
Never guess an ID from a name, URL fragment, or old record
The trusted prompt on the main path already carries the Agent and version context, so the local AI should not ask you to enter those two IDs again. If Workspace creation times out, use the workspace_id in the error to query the same Workspace; do not create another one.
Responsibilities of the website, CLI, and Workspace
| Surface | Responsible for | Not responsible for |
|---|---|---|
| Website version workspace | Creating/editing versions, models, CPU/Memory, Agent Card, pricing, publishing, and online/offline state | It does not directly edit remote files |
| CLI 0.7.3 | Verified installation, diagnostics, secure authentication, SSH-key handling, Workspace source/create/status/resume/connect operations, WebUI port get/set/refresh, and allow-listed portal operations including publishing | It has no generic file sync command and no public Workspace close command; mutating portal operations require explicit authorization and --confirm |
| Development Workspace | Implementing the Program under /oasn and running development tests through WebChat | It does not replace version publishing or Go Online actions on the website |
Before you begin
- A browser that can access the OpenAgent website and a developer account.
- A local environment that can run Python 3, OpenSSH
ssh, andssh-keygen. On Windows, the installer and generatedoasn-sa-dev.cmduse the Python Launcherpyby default; first confirm thatpy --versionworks. If you havepython.exebut notpy, do not continue with that shim. Runpython <CLI installation path> ...explicitly and record the path in your installation notes. - A local AI that can read the platform Skill URL, run terminal commands, and show diffs.
- An operator who gives separate, explicit authorization to create a new SSH key, connect to a Workspace, and synchronize files.
For your first build, continue with Quick Start. To verify commands, go directly to the complete CLI reference.