# Generate agent candidate solutions

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

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

## Preparation before calling

First [Query the available resources for intelligent agent construction](list-authoring-resources.md) 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

```bash
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](list-authoring-resources.md). |
| `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.

```json
{
  "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

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

### Common HTTP errors

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - 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](commit-candidate.md).