Regenerate agent candidate solutions¶

Generate new editable candidate versions based on existing candidates and coverage fields.

HTTP
POST $CLOUDSIGMA_API_BASE/workspaces/{workspace_id}/agent-builder/candidates/{agent_id}/candidate-versions/{candidate_version}/repropose

Before you call this API¶

Configure the regional API endpoint and authentication, and select the target workspace.

First generate the agent candidate solution to obtain the candidate version and source_digest.

Set the operation-specific values used in the request:

$WORKSPACE_ID: Target workspace ID, passed through the X-Workspace-ID header and also as workspace_id in the path.
$AGENT_ID: Agent ID, as agent_id in the path.
$CANDIDATE_VERSION: The current release candidate, as candidate_version in the path.
$SOURCE_DIGEST: Digest from the current candidate response for source_digest in the request body.

Request¶

Input examples

Shell
curl -X POST "$CLOUDSIGMA_API_BASE/workspaces/$WORKSPACE_ID/agent-builder/candidates/$AGENT_ID/candidate-versions/$CANDIDATE_VERSION/repropose" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "source_digest": "'"$SOURCE_DIGEST"'",
    "overrides": {
      "agent_md": "<UPDATED_AGENT_MD>"
    }
  }'

Parameter reference

Path parameters

Parameters	Type	Is it required	Description
`workspace_id`	string	Yes	Workspace ID.
`agent_id`	string	Yes	Agent ID.
`candidate_version`	string	Yes	The current release candidate.

Request body

Parameters	Type	Is it required	Description
`source_digest`	string	Yes	The digest in the current candidate response, used for concurrent verification.
`overrides`	object	Yes	Candidate fields to overwrite.

Successful response¶

Returns 200 on success. data is a new release candidate; the original candidate does not automatically become a loaded release because the request is accepted.

Response example

JSON
{
  "code": 0,
  "data": {
    "workspace_id": "ws_01",
    "agent_id": "agent_01",
    "candidate_version": "cand_02",
    "load_version": "v1",
    "source_digest": "sha256:<HEX_DIGEST>",
    "mode": "revise",
    "status": "valid",
    "display": {
      "agent_name": "产品助手"
    },
    "diagnostics": []
  }
}

Field reference

The response fields are as follows.

Field	Type	Description
`code`	integer	`0` on success.
`data.candidate_version`	string	The new release candidate and its summary; used when confirming or canceling.
`data.source_digest`	string	The new release candidate and its summary; used when confirming or canceling.
`data.load_version`	string	The loaded version used after the candidate is confirmed.
`data.status`	string	Candidate status, display content, diagnostics, and resolved resource references.
`data.display`	object	Candidate status, display content, diagnostics, and resolved resource references.
`data.diagnostics`	array	Candidate status, display content, diagnostics, and resolved resource references.
`data.resolved_refs`	object	Candidate status, display content, diagnostics, and resolved resource references.

Error response¶

Response example

JSON
{
  "code": 4,
  "message": "<错误信息>"
}

Field reference

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`2`（`INVALID_ARGUMENT`）	The coverage field is unknown, the type is invalid, or the requested field is incomplete.	Only submit fields supported by `overrides`.
`401`	`6`（`UNAUTHENTICATED`）	Lack of valid identity credentials.	Check API Key.
`403`	`5`（`PERMISSION_DENIED`）	The current identity does not have permission to revise the candidate.	Check workspace and agent authorizations.
`404`	`3`（`NOT_FOUND`）	Release candidate does not exist.	Check for release candidates.
`409`	`4`（`ALREADY_EXISTS`）	`source_digest` has expired, the candidate has been replaced, or there is a concurrent authoring conflict.	Generate again after reading the latest candidate.
`500`	`1`（`INTERNAL`）	Candidate build failed.	Try again later.
`503`	`15`（`UNAVAILABLE`）	Agent construction or authorization services are temporarily unavailable.	Try again later.

Follow-up operations¶

After checking the new candidate, Confirm agent candidate solutions, or Cancel the agent candidate plan.

Last updated on Sep 15, 2026