Build a Single Agent

A Single Agent is one of the two Agent Business Capability types. Choose it when one bounded model-backed reasoning unit can deliver the promised result. Choose a Workflow DAG when the capability needs explicit multi-step orchestration, branching, or structured intermediate results.

1. Open the definition editor

Open the Agent Business in the creator console, then select Capability. A Single Agent has one authoritative v1 Definition. Business identity, visibility, pricing, Offers, and Publications live in their own workspaces and are not duplicated in this editor.

2. Configure the five areas

The editor keeps the runtime contract in five focused areas:

1. Instructions contains the system instructions and user message template. Template variables such as {{topic}} should match fields in the input Schema.
2. Contract defines input and output JSON Schemas used for validation, documentation, and machine clients.
3. Model selects Completion or Chat, the provider and model, sampling settings, and execution limits.
4. Tools pins Tool ID, type, version, endpoint, and an optional server-managed credential reference. Never paste an API key, password, Cookie, Authorization Header, or token into the Definition.
5. Preview accepts a JSON Object and displays only the sanitized result and trace summary.

The built-in provider requires no provider credential reference. External providers and Tools may reference secrets held by the platform, but the browser never reads or stores their raw values.

3. Save Draft

Choose Save Draft to persist the editable Definition. Saving uses the base Revision loaded by the editor. If another editor saves first, the console preserves your local changes and reports the conflict so you can reload and reconcile deliberately.

A legacy configuration may be adapted in memory when first opened. The console marks that state explicitly and does not persist the v1 Definition until you choose Save Draft.

Saving does not change production behavior and does not create a Release.

4. Preview unsaved changes

Enter an Object that matches the input Contract, then choose Preview definition. Preview executes the Definition currently visible in the browser, including unsaved changes. It does not save, publish, or activate anything.

The response shows a bounded result plus status, duration, provider, model, interaction mode, and execution ID. Provider errors, credentials, authentication headers, and private configuration are not exposed.

5. Create Release

Create Release is enabled only when the Definition matches the saved Draft. Save or discard local edits first, then choose Create Release to create and activate an immutable Capability Release.

Every Release digest covers the executable Definition, including model configuration, limits, Schemas, and Tool references. A Workflow Agent node pins both the selected Single Agent Release ID and its SHA-256 digest. A later Single Agent Release never changes an existing Workflow silently.

Control and runtime endpoints

The creator console uses the canonical control endpoints:

GET   https://api.agentaab.com/api/app/{business-slug}/single-agent/
PATCH https://api.agentaab.com/api/app/{business-slug}/single-agent/
POST  https://api.agentaab.com/api/app/{business-slug}/single-agent/preview/

Published callers invoke the active Release through the Completion or Chat runtime route:

POST https://api.agentaab.com/api/app/{business-slug}/completion-messages
POST https://api.agentaab.com/api/app/{business-slug}/chat-messages

The older /prompt/ control path remains a compatibility alias. New integrations should use /single-agent/. See the Runtime Client guide for public authentication and error handling.

Troubleshooting

Create Release is disabled

The Definition has unsaved changes or a legacy adaptation is still pending. Choose Save Draft and wait for confirmation before creating the Release.

Save reports a newer Draft

Another save won the optimistic-concurrency check. Your browser retains its local Definition. Copy it if needed, reload the newer Revision, and reconcile intentionally.

Production still runs the previous behavior

Save Draft and Preview do not replace production. Confirm that a new Capability Release was created and activated.

A Workflow cannot select the Single Agent

Workflow Agent nodes can pin only an accessible active Release with a resolvable digest and supported runtime configuration. Mutable Drafts are not valid targets.