---
orphan: true
---

# Create agent task template

Create an agent task template for the workflow node to call. If the creation is successful, only the template will be saved and the agent task will not be executed.

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

## Before you call

Prepare your personal access token, workspace ID, and existing agent ID.

The example below uses:

- `$AI_STUDIO_API_KEY`: Actual personal access token.
- `$WORKSPACE_ID`: Target workspace ID.
- `$AGENT_ID`: The agent ID to be called by the template.

## Request example

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/agent-task-templates" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_id": "'$AGENT_ID'",
    "name": "摘要任务",
    "message_template": {"template": "请总结输入内容"}
  }'
```

## Path parameters

| Parameters | Type | Is it required | Description |
| --- | --- | --- | --- |
| `workspace_id` | string | Yes | The target workspace ID. |

## Request body

| Parameters | Type | Is it required | Description |
| --- | --- | --- | --- |
| `agent_id` | string | Yes | Target agent ID. |
| `name` | string | Yes | Template name. |
| `message_template` | object | Yes | Task message template. |
| `description` | string | No | Template description. |
| `input_schema` | object | No | Input structure definition. |
| `default_context_refs` | array | No | Default context reference. |
| `runtime_policy_ref` | string | No | Run policy reference. |
| `idempotency_policy` | object | No | Idempotent policy. |
| `output_contract` | object | No | Output contract. |
| `status` | string | No | Template status. |
| `labels` | object | No | Tag key-value pair. |
| `annotations` | object | No | Annotation key-value pair. |

## Successful response

Returns `201` and a new template on success.

```json
{"code": 0, "data": {"id": "template_01", "agent_id": "agent_01", "name": "摘要任务"}}
```

The response fields are as follows.

| Field | Type | Description |
| --- | --- | --- |
| `code` | integer | `0` on success. |
| `data.id` | string | New template ID. |
| `data.agent_id` | string | Associated agent ID. |
| `data.name` | string | Template name. |

## Error response

```json
{"code": 2, "message": "invalid agent task template"}
```

### Common HTTP errors

```{list-table}
:header-rows: 1

* - HTTP status code
  - error code
  - Common causes
  - Recommended actions
* - `400`
  - `2`
  - The request body or template reference is invalid.
  - Check agent ID and message template.
* - `409`
  - `4`
  - The template ID or workflow node association already exists.
  - Use a new identity instead or query an existing resource.
```

## Follow-up operations

Save `data.id`, and then [Create agent workflow binding](../workflow-bindings/create-workflow-binding.md).