Generate agent candidate solutions¶

Submit a complete candidate configuration of the agent, and the service will verify and save the candidate version.

POST https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/agent-builder/candidates

Preparation before calling¶

First Query the available resources for intelligent agent construction to obtain the resource list. Prepare a personal access token and target workspace ID that has access to the target workspace.

The example below uses:

$AI_STUDIO_API_KEY: The actual personal access token, passed through the X-API-Key Header.
$WORKSPACE_ID: Target workspace ID, passed through the X-Workspace-ID Header and also as workspace_id in the path.

candidate should include the agent identification, name, model, and referenced tools, skills, knowledge bases, or channels. The reference must be found in resources or within the resolvable scope of the workspace. When creating a candidate, use candidate.agent_id, not candidate.id.

Request example¶

curl -X POST "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/agent-builder/candidates" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "mode": "create",
    "conversation_id": "<CONVERSATION_ID>",
    "raw_advice": "Create an agent that answers product questions.",
    "resources": {
      "models": [],
      "tools": [],
      "skills": [],
      "knowledge_bases": []
    },
    "candidate": {
      "agent_id": "<AGENT_ID>",
      "name": "Product Assistant",
      "description": "Answers product questions.",
      "model_name": "<MODEL_NAME>",
      "tool_names": [],
      "skill_names": [],
      "knowledge_base_names": [],
      "catalog_files": [],
      "channel_bindings": [],
      "agent_md": "# Product Assistant",
      "change_reason": "Initial creation"
    }
  }'

Path parameters¶

Parameters	Type	Is it required	Description
`workspace_id`	string	Yes	Workspace ID.

Request body¶

Parameters	Type	Is it required	Description
`mode`	string	Yes	Build mode; create new agents using `create`.
`conversation_id`	string	Yes	The session ID to which this build belongs.
`raw_advice`	string	Yes	The original request for this creation or modification.
`resources`	object	Yes	Resource collection returned by Query available resources for agent construction.
`candidate`	object	Yes	Complete candidate agent configuration.
`candidate.agent_id`	string	Yes	New candidate agent ID.
`candidate.name`	string	Yes	Agent name.
`candidate.description`	string	Yes	Agent description.
`candidate.model_name`	string	Yes	Available model name from `resources.models`.
`candidate.tool_names`	string[]	Yes	Selected tool names; pass empty array if none.
`candidate.skill_names`	string[]	Yes	Selected skill names; pass empty array if none.
`candidate.knowledge_base_names`	string[]	Yes	Selected knowledge base names; pass empty array if none.
`candidate.catalog_files`	array	Yes	Catalog files referenced by candidate; pass empty array if none.
`candidate.channel_bindings`	array	Yes	Candidate channel bindings; pass empty array if none.
`candidate.agent_md`	string	Yes	Editable agent Markdown body.
`candidate.change_reason`	string	Yes	Reason for candidate change.
`task_id`	string	No	The associated task ID.
`source_agent_id`	string	Required for revision mode	Source agent ID.
`source_agent_workspace_id`	string	No	Source agent workspace.
`source_version`	string	Revision mode required	Source version.

Successful response¶

Returns 200 on success. Just because a candidate has been generated does not mean that it has become the current runnable version.

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

The response fields are as follows.

Field	Type	Description
`code`	integer	`0` on success.
`data.workspace_id`	string	The workspace and agent identification to which the candidate belongs.
`data.agent_id`	string	The workspace and agent identification to which the candidate belongs.
`data.candidate_version`	string	Candidate version for subsequent regeneration, confirmation or cancellation.
`data.load_version`	string	Used to query the version of the loaded agent configuration after successful confirmation.
`data.source_digest`	string	Current candidate content summary; subsequent write operations must return this value.
`data.mode`	string	Build mode and candidate status.
`data.status`	string	Build mode and candidate status.
`data.display`	object	Presentation-oriented content candidates, validation diagnostics, and resolved resource references.
`data.diagnostics`	array	Presentation-oriented content candidates, validation diagnostics, and resolved resource references.
`data.resolved_refs`	object	Presentation-oriented content candidates, validation diagnostics, and resolved resource references.
`data.package_summary`	object	Summary of candidate package files; returned when available.

Error response¶

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

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`2`（`INVALID_ARGUMENT`）	The request contains unknown fields, required fields are missing, and the candidate configuration or resource reference is invalid.	Based on error message and `diagnostics` fix request.
`401`	`6`（`UNAUTHENTICATED`）	Lack of valid identity credentials.	Check API Key.
`403`	`5`（`PERMISSION_DENIED`）	The current identity does not have permission to create or modify candidates.	Check workspace and source agent authorizations.
`409`	`4`（`ALREADY_EXISTS`）	There are parallel authoring contexts or candidate conflicts for the same agent.	Resubmit after reading the current candidate.
`413`	`14`（`RESOURCE_EXHAUSTED`）	`resources` exceeds the allowed size of the interface.	Reduce the resource list and try again.
`500`	`1`（`INTERNAL`）	Candidate build failed.	Try again later; contact support if it continues to fail.
`503`	`15`（`UNAVAILABLE`）	Agent construction or authorization services are temporarily unavailable.	Try again later.

Follow-up operations¶

Use the version and summary from the response Confirm agent candidate solutions.

Last updated on Sep 3, 2026