Quickstart

This walkthrough uses a “Summary Assistant” to complete the smallest end-to-end development loop. The example only needs text input; Agents that accept attachments, expose a WebUI, or use an authorized integration follow the same development and acceptance pattern. Finish the minimum version first, then add only capabilities that the current Workspace actually exposes and that you can test.

Target outcome

The user provides a passage and the Agent returns a concise summary. If the passage is missing, the Agent gives an actionable request for the missing input. Validate the draft in WebChat, publish it, and then explicitly take it Online.

Complete the main path once

1. Sign in and create a draft

   Open the OpenAgent website, sign in, go to Developer, and click Create. The platform creates an Agent and its first draft, then opens the version workspace.

2. Set the version label

   Enter a version such as 0.1.0. It must use the N.N.N format, with one or two digits in each segment. For example, 1.0.0 and 12.3.45 are valid; v1.0.0, 1.0, and 100.0.0 are not.

3. Copy the local-build prompt

   Click Build With Local Agent and copy the entire prompt from the dialog. It contains the fixed Skill URL, operation=build, and the current agent_id and agent_version_id. Do not shorten, rewrite, or replace any value.

4. Paste it unchanged into your local AI

   The local AI must read the Skill first and use the download URL and SHA-256 bound by that Skill to install oasn-sa-dev 0.7.3. Do not substitute another CLI URL or use an unverified curl, wget, or raw platform API flow.

5. Run diagnostics and choose the Workspace source

   Run oasn-sa-dev --version and oasn-sa-dev doctor, then inspect the available sources with oasn-sa-dev workspace sources --version-id <agent_version_id>. Explicitly choose either the existing Workspace, a restorable published version, or --fresh. A recommended source is a suggestion, not authorization to choose it automatically.

6. Create and wait for the Workspace

   If there is no Workspace to reuse, run oasn-sa-dev workspace create --version-id <agent_version_id> --source-version-id <source_version_id>, or use --fresh after explicitly choosing the platform base environment. Authentication opens in the browser when required. Wait until the result reports status: "active". Creation does not bind an SSH key.

7. Bind and verify the SSH connection

   Run oasn-sa-dev workspace connect --workspace-id <workspace_id>. The CLI matches the selected public and private key, binds the public key when necessary, and performs a real BatchMode SSH probe. If no key exists, create one only after explicit approval with oasn-sa-dev ssh-key ensure --create, then rerun workspace connect. Use only the complete SSH and SCP commands returned by the successful connection result.

8. Implement the minimum Program in /oasn

   For the Summary Assistant, define the behavior precisely: read the user's passage; when content is present, return a title and three to five faithful bullet points; when it is empty, explain exactly what input is required. Do not invent the host, port, username, identity file, or remote path.

9. Run two minimum WebChat tests

   Open the returned webchat_url. First submit a representative long passage and verify that the summary is faithful. Then submit a request without the passage and verify that the Agent asks clearly for the missing input. A reply appearing in the chat is not sufficient acceptance evidence.

10. Complete and save the version configuration

    Return to the website and configure the avatar, name, description, category, and MOM; select the required LLM capabilities; and set CPU, memory, and pricing. Gross margin must be an integer from 0 to 100. Click Save Draft and confirm that no unsaved state or validation error remains.

11. Publish, then go Online

    Click Publish and wait for the Job to become succeeded and the publication to become visible. A newly published version is Offline by default. Review the version summary and click Go Online. Open the public Agent link returned by the publish result; if the page does not show it, search the public Agents catalog by the exact Agent name and verify the description and developer identity. Install it with Use in ChatGPT, or use the split-button menu for Use in Claude or Use in WorkBuddy. In the client, select the exact Agent again, submit a representative request, and inspect the final result.

What a successful Workspace connection returns

Workspace commands return JSON. Before editing remotely, verify at least the following fields in the successful workspace connect result:

{
  "workspace_id": "<workspace-id>",
  "version_id": "<agent-version-id>",
  "source_version_id": "<source-version-id-or-null>",
  "status": "active",
  "connection_status": "ready",
  "remote_project_dir": "/oasn",
  "webchat_url": "https://...",
  "webui_urls": [],
  "ssh_binding_status": "bound",
  "ssh_verified": true,
  "ssh_command": "ssh -vvv ...",
  "scp_command": "scp ...",
  "expires_at": "..."
}

active alone does not prove SSH access

Only connect after workspace connect returns ssh_binding_status: "bound" and ssh_verified: true. If creation returns WORKSPACE_TIMEOUT, preserve its workspace_id and run workspace status for that same Workspace; do not create another one. A Workspace in failed, closed, published, cleanup_pending, or close_pending is not a ready development environment.

If the Agent exposes a WebUI

The website has no WebUI-port form. Declare the complete list through CLI 0.7.3, then query the authoritative result:

oasn-sa-dev version webui-ports set --version-id <agent_version_id> --ports 7860,8765
oasn-sa-dev version webui-ports get --version-id <agent_version_id>

An active Workspace is synchronized in place; the platform does not rebuild the Sandbox and does not start the business services for you. sync_status=ready only means the declaration has synchronized. Deliver an entry from webui_urls only when proxy_status=ready, and still test the actual HTTP page. See Input, Output, and WebUI for the runtime contract.

Minimum acceptance checklist

• The version label follows N.N.N, and you are editing the intended draft.
• The local AI used the complete prompt copied from the website and did not guess or request replacement IDs.
• CLI 0.7.3 was installed only after the Skill-bound URL, size, response-header digest, and body digest were verified.
• The developer explicitly chose the Workspace source; the returned source_version_id and target version_id match that choice.
• The Workspace is active, and SSH use is backed by bound + ssh_verified=true; all connection details come from the current CLI result.
• Both normal and missing-input behavior were tested, and the result content—not merely transport success—was inspected.
• Agent Card, MOM, models, CPU, memory, and pricing all pass workspace validation.
• If a WebUI is used, the port declaration is synchronized, the proxy is ready, and the real page works through the returned URL.
• After publishing, the Agent was taken Online, installed from its public page in a real client, and invoked once. A missing public page or unusable installation is recorded as BLOCKED or NOT TESTED, not passed.

Continue with Build the Program, Development Testing, or Publish and Go Online.