---
orphan: true
---

# Create agent workflow binding

Bind an agent task template to a workflow node. Successful creation only saves the binding and does not create plans or execution tasks.

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

## Before you call

The example below uses:

- `$AI_STUDIO_API_KEY`: Actual personal access token.
- `$WORKSPACE_ID`: Target workspace ID.
- `$WORKFLOW_ID`: The workflow ID to be bound.
- `$TEMPLATE_ID`: Agent task template ID to use.

## Request example

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/agent-workflow-bindings" -H "X-API-Key: $AI_STUDIO_API_KEY" -H "X-Workspace-ID: $WORKSPACE_ID" -H 'Content-Type: application/json' -d '{"workflow_id":"'$WORKFLOW_ID'","node_id":"summary","agent_task_template_id":"'$TEMPLATE_ID'"}'
```

## Request body

| Parameters | Type | Is it required | Description |
| --- | --- | --- | --- |
| `workflow_id` | string | Yes | Workflow ID. |
| `node_id` | string | Yes | Workflow node ID. |
| `agent_task_template_id` | string | Yes | Agent task template ID. |
| `workflow_version_id` | string | No | Workflow version ID. |
| `input_mapping` | object | No | Input mapping. |
| `output_mapping` | object | No | Output mapping. |
| `failure_mapping` | object | No | Failure handling mapping. |
| `status` | string | No | Binding status. |
| `labels` | object | No | Tag key-value pair. |
| `annotations` | object | No | Annotation key-value pair. |

## Successful response

Returns `201` and a new binding on success.

```json
{"code": 0, "data": {"id": "binding_01", "workflow_id": "wf_01", "node_id": "summary", "agent_task_template_id": "template_01"}}
```

The response fields are as follows.

| Field | Type | Description |
| --- | --- | --- |
| `code` | integer | `0` on success. |
| `data.id` | string | New binding ID. |
| `data.workflow_id` | string | Workflow ID. |
| `data.agent_task_template_id` | string | Association template ID. |

## Error response

```json
{"code": 4, "message": "agent workflow binding already exists"}
```

### Common HTTP errors

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

* - HTTP status code
  - error code
  - Common causes
  - Recommended actions
* - `400`
  - `2`
  - The binding field is invalid.
  - Check workflow, node and template identification.
* - `409`
  - `4`
  - The same workflow node is already bound.
  - Query or update existing bindings.
```