Create agent

http
POST /projects/{project_reference}/agents

Create agent. Requires project.agents.write.

Servers

json
[
  {
    "url": "https://api.veryfront.com"
  }
]

Authentication

json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyAuth": []
  }
]
json
{
  "bearerAuth": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "JWT or API Key",
    "description": "Use a JWT bearer token or a Veryfront API key in the `Authorization` header."
  },
  "apiKeyAuth": {
    "type": "apiKey",
    "in": "header",
    "name": "X-API-Key",
    "description": "Alternative API key header for `vf_<prefix>_<secret>` tokens."
  }
}

Parameters

NameLocationRequiredDescription
project_referencepathYesProject slug, UUID, or domain that identifies the project.
source_target_kindqueryNo
target_branch_idqueryNo

Parameter contracts

json
[
  {
    "schema": {
      "$ref": "#/components/schemas/ProjectReference"
    },
    "required": true,
    "description": "Project slug, UUID, or domain that identifies the project.",
    "name": "project_reference",
    "in": "path"
  },
  {
    "schema": {
      "type": "string"
    },
    "required": false,
    "name": "source_target_kind",
    "in": "query"
  },
  {
    "schema": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "required": false,
    "name": "target_branch_id",
    "in": "query"
  }
]

Request body

json
{
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[a-zA-Z0-9_-]+$"
          },
          "name": {
            "type": "string",
            "minLength": 1
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "model": {
            "type": [
              "string",
              "null"
            ]
          },
          "system_prompt": {
            "type": "string",
            "minLength": 1
          },
          "thinking": {
            "type": "object",
            "properties": {
              "enabled": {
                "type": "boolean"
              },
              "budget_tokens": {
                "type": "number",
                "exclusiveMinimum": 0
              }
            },
            "required": [
              "enabled"
            ],
            "additionalProperties": false
          },
          "temperature": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "maximum": 2
          },
          "max_steps": {
            "type": [
              "integer",
              "null"
            ],
            "exclusiveMinimum": 0
          },
          "allowed_models": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            }
          },
          "skill_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            }
          },
          "skill_selection": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "omitted",
                  "explicit"
                ]
              },
              "skill_ids": {
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1
                },
                "default": []
              }
            },
            "required": [
              "kind"
            ]
          },
          "skills": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              },
              {
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128
                },
                "maxItems": 500
              },
              {
                "type": "object",
                "additionalProperties": {
                  "type": "boolean"
                }
              }
            ]
          },
          "all_tools_enabled": {
            "type": "boolean"
          },
          "tool_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            },
            "description": "Project tools, platform tools, and integration catalog tools returned by get_integration. Use exact names from the agent tool references search."
          },
          "tools": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128
                },
                "maxItems": 500
              },
              {
                "type": "object",
                "additionalProperties": {
                  "type": "boolean"
                }
              }
            ],
            "description": "Callable host-tool selector. Use false to disable all host tools, including skill and delegation tools. An empty array or map selects no project tools but preserves legacy runtime essentials. Provider-native tools use provider_tool_ids."
          },
          "tool_loading": {
            "type": "string",
            "enum": [
              "eager",
              "deferred"
            ]
          },
          "tool_result_context": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "object",
                "properties": {
                  "max_inline_bytes": {
                    "type": "integer",
                    "exclusiveMinimum": 0,
                    "maximum": 1048576
                  },
                  "preview_bytes": {
                    "type": "integer",
                    "exclusiveMinimum": 0,
                    "maximum": 1048576
                  },
                  "max_section_bytes": {
                    "type": "integer",
                    "minimum": 4,
                    "maximum": 1048576
                  },
                  "max_stored_results": {
                    "type": "integer",
                    "exclusiveMinimum": 0,
                    "maximum": 1024
                  }
                },
                "additionalProperties": false
              }
            ]
          },
          "knowledge": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "string",
                "minLength": 1,
                "maxLength": 4096
              },
              {
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 4096
                },
                "maxItems": 1024
              },
              {
                "type": "object",
                "additionalProperties": {
                  "type": "boolean"
                }
              }
            ]
          },
          "provider_tool_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            },
            "description": "Provider-native model tools only. Never put tool references from tool_ids here."
          },
          "suggestions": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "anyOf": [
                {
                  "type": "string",
                  "minLength": 1
                },
                {
                  "type": "object",
                  "properties": {
                    "title": {
                      "type": "string",
                      "minLength": 1
                    },
                    "prompt": {
                      "type": "string",
                      "minLength": 1
                    }
                  },
                  "required": [
                    "title",
                    "prompt"
                  ],
                  "additionalProperties": false
                }
              ]
            }
          },
          "avatar": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "seed": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              },
              "archetype": {
                "type": "string",
                "enum": [
                  "upright",
                  "slumped",
                  "alert",
                  "profile",
                  "leaning",
                  "crouched",
                  "tall",
                  "spread",
                  "happy",
                  "sad",
                  "angry",
                  "surprised",
                  "sleepy",
                  "curious"
                ]
              },
              "texture": {
                "type": "string",
                "pattern": "^(?:[0-9]|none)$"
              },
              "color": {
                "type": "string",
                "pattern": "^#[0-9a-fA-F]{6}$"
              },
              "shape": {
                "type": "string",
                "enum": [
                  "snircle",
                  "circle",
                  "square"
                ]
              },
              "matrix": {
                "type": "string",
                "pattern": "^[012]{16}$"
              }
            }
          },
          "avatar_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "security_enabled": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "name",
          "system_prompt"
        ]
      }
    }
  }
}

Responses

201

Agent created

json
{
  "description": "Agent created",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AgentSource"
      }
    }
  }
}

400

Bad request

json
{
  "description": "Bad request",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/AgentProblem"
      }
    }
  }
}

401

Unauthorized

json
{
  "description": "Unauthorized",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

403

Forbidden

json
{
  "description": "Forbidden",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

404

Not found

json
{
  "description": "Not found",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

409

Conflict

json
{
  "description": "Conflict",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/AgentProblem"
      }
    }
  }
}

500

Server error

json
{
  "description": "Server error",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

503

internal: authentication state is temporarily unavailable and the request was not processed; retry shortly.

json
{
  "description": "internal: authentication state is temporarily unavailable and the request was not processed; retry shortly.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

Referenced contracts

components/parameters/ProjectReference

json
{
  "schema": {
    "$ref": "#/components/schemas/ProjectReference"
  },
  "required": true,
  "description": "Project slug, UUID, or domain that identifies the project.",
  "name": "project_reference",
  "in": "path"
}

components/schemas/ProjectReference

json
{
  "type": "string"
}

components/schemas/AgentSource

json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    },
    "model": {
      "type": [
        "string",
        "null"
      ],
      "description": "Model identifier recovered from authored source. Null means no literal identifier was recovered; an omitted model is valid. The run selects and checks its model at admission, so null is not a missing-configuration error or a verified runtime default."
    },
    "system_prompt": {
      "type": [
        "string",
        "null"
      ]
    },
    "thinking": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "budget_tokens": {
          "type": "number",
          "exclusiveMinimum": 0
        }
      },
      "required": [
        "enabled"
      ],
      "additionalProperties": false
    },
    "temperature": {
      "type": [
        "number",
        "null"
      ],
      "minimum": 0,
      "maximum": 2
    },
    "max_steps": {
      "type": [
        "integer",
        "null"
      ],
      "exclusiveMinimum": 0
    },
    "allowed_models": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Agent-level allowlist for request model overrides. Empty means no restriction by this allowlist; project and run model policies still apply. This does not identify the resolved runtime model."
    },
    "skill_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Legacy source-view skill IDs. A read with skill_resolution can include source-catalog matches; a write response can echo only authored IDs. An empty array does not prove that no skills are available, and these IDs do not verify runtime loading. Use skill_selection and skill_resolution for provenance."
    },
    "skill_selection": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "omitted",
            "explicit"
          ]
        },
        "skill_ids": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Explicit skill IDs when kind is explicit. When kind is omitted, a read lists the owner-visible source-catalog matches (legacy projection) and a write response can echo an empty list. Use skill_resolution for provenance; these IDs do not verify runtime loading."
        }
      },
      "required": [
        "kind",
        "skill_ids"
      ],
      "description": "Skill selection. kind is the authored policy: omitted selects all owner-visible skills. Use skill_resolution for resolved source-catalog matches and their evidence scope."
    },
    "skill_resolution": {
      "type": "object",
      "properties": {
        "policy": {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "all-visible"
                  ]
                },
                "source": {
                  "type": "string",
                  "enum": [
                    "omitted",
                    "true"
                  ]
                }
              },
              "required": [
                "kind",
                "source"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "none"
                  ]
                }
              },
              "required": [
                "kind"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "allowlist"
                  ]
                },
                "entries": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "required": [
                "kind",
                "entries"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "rules"
                  ]
                },
                "entries": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "pattern": {
                        "type": "string"
                      },
                      "allow": {
                        "type": "boolean"
                      }
                    },
                    "required": [
                      "pattern",
                      "allow"
                    ]
                  }
                }
              },
              "required": [
                "kind",
                "entries"
              ]
            }
          ]
        },
        "skill_ids": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "source_paths": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "unresolved_entry_indexes": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": 0
          }
        },
        "catalog_status": {
          "type": "string",
          "enum": [
            "complete",
            "partial"
          ]
        },
        "evidence_scope": {
          "type": "string",
          "enum": [
            "source_catalog"
          ]
        }
      },
      "required": [
        "policy",
        "skill_ids",
        "source_paths",
        "unresolved_entry_indexes",
        "catalog_status",
        "evidence_scope"
      ],
      "description": "Skill selector policy and owner-visible source catalog matches. Partial catalogs cannot establish that unreturned skills are absent. This does not verify run execution access."
    },
    "skills": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "maxItems": 500
        },
        {
          "type": "object",
          "additionalProperties": {
            "type": "boolean"
          }
        }
      ]
    },
    "all_tools_enabled": {
      "type": "boolean",
      "description": "Whether the authored selector allows all tools. False can still select individual tools. Read the raw tools selector and capability resolution for the selected set."
    },
    "tool_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Source-recovered explicit tool IDs. Empty when all_tools_enabled is true, when tools is false (authored deny-all), or when no explicit IDs were recovered, so an empty array alone does not mean callable host tools are disabled. This source view does not verify execution grants."
    },
    "tools": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "maxItems": 500
        },
        {
          "type": "object",
          "additionalProperties": {
            "type": "boolean"
          }
        }
      ],
      "description": "Callable host-tool selector. Use false to disable all host tools, including skill and delegation tools. An empty array or map selects no project tools but preserves legacy runtime essentials. Provider-native tools use provider_tool_ids."
    },
    "tool_loading": {
      "type": "string",
      "enum": [
        "eager",
        "deferred"
      ]
    },
    "tool_result_context": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "object",
          "properties": {
            "max_inline_bytes": {
              "type": "integer",
              "exclusiveMinimum": 0,
              "maximum": 1048576
            },
            "preview_bytes": {
              "type": "integer",
              "exclusiveMinimum": 0,
              "maximum": 1048576
            },
            "max_section_bytes": {
              "type": "integer",
              "minimum": 4,
              "maximum": 1048576
            },
            "max_stored_results": {
              "type": "integer",
              "exclusiveMinimum": 0,
              "maximum": 1024
            }
          },
          "additionalProperties": false
        }
      ]
    },
    "provider_tool_ids": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "knowledge": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4096
          },
          "maxItems": 1024
        },
        {
          "type": "object",
          "additionalProperties": {
            "type": "boolean"
          }
        }
      ]
    },
    "suggestions": {
      "type": "array",
      "items": {
        "anyOf": [
          {
            "type": "string",
            "minLength": 1
          },
          {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "minLength": 1
              },
              "prompt": {
                "type": "string",
                "minLength": 1
              }
            },
            "required": [
              "title",
              "prompt"
            ],
            "additionalProperties": false
          }
        ]
      }
    },
    "avatar": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "seed": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        "archetype": {
          "type": "string",
          "enum": [
            "upright",
            "slumped",
            "alert",
            "profile",
            "leaning",
            "crouched",
            "tall",
            "spread",
            "happy",
            "sad",
            "angry",
            "surprised",
            "sleepy",
            "curious"
          ]
        },
        "texture": {
          "type": "string",
          "pattern": "^(?:[0-9]|none)$"
        },
        "color": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "shape": {
          "type": "string",
          "enum": [
            "snircle",
            "circle",
            "square"
          ]
        },
        "matrix": {
          "type": "string",
          "pattern": "^[012]{16}$"
        }
      }
    },
    "avatar_url": {
      "type": [
        "string",
        "null"
      ],
      "format": "uri",
      "description": "Absolute URL for this agent avatar. Null when no custom avatar has been set."
    },
    "security_enabled": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Whether the agent default security guardrails are enabled."
    },
    "source_path": {
      "type": "string"
    },
    "source": {
      "type": "string"
    },
    "edit_mode": {
      "type": "string",
      "enum": [
        "structured",
        "source_only"
      ]
    },
    "source_only_reasons": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "id",
    "name",
    "description",
    "model",
    "system_prompt",
    "temperature",
    "max_steps",
    "allowed_models",
    "skill_ids",
    "skill_selection",
    "all_tools_enabled",
    "tool_ids",
    "provider_tool_ids",
    "security_enabled",
    "source_path",
    "source",
    "edit_mode",
    "source_only_reasons"
  ]
}

components/schemas/AgentProblem

json
{
  "allOf": [
    {
      "$ref": "#/components/schemas/Problem"
    },
    {
      "type": "object",
      "properties": {
        "edit_mode": {
          "type": "string",
          "enum": [
            "structured",
            "source_only"
          ],
          "description": "Edit mode of the agent definition, on a source_only_conflict."
        },
        "source_only_reasons": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Why the agent can only be edited as raw source, on a source_only_conflict."
        },
        "source_path": {
          "type": "string",
          "description": "Source file of the agent definition, on a source_only_conflict."
        }
      }
    }
  ]
}

components/schemas/Problem

json
{
  "type": "object",
  "properties": {
    "cause": {
      "type": "string",
      "enum": [
        "schedule_concurrency_forbidden",
        "schedule_fire_in_progress",
        "schedule_run_limit_reached"
      ],
      "description": "Schedule admission refusal."
    },
    "idempotency": {
      "type": "object",
      "properties": {
        "state": {
          "type": "string",
          "enum": [
            "in_progress",
            "payload_mismatch",
            "outcome_unknown"
          ]
        },
        "operation": {
          "type": "string",
          "minLength": 1
        },
        "retryable": {
          "type": "boolean"
        },
        "retry_after_seconds": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0
        },
        "expires_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "recovery": {
          "type": "object",
          "properties": {
            "available": {
              "type": "boolean"
            },
            "description": {
              "type": "string"
            },
            "resource_url": {
              "type": "string"
            }
          },
          "required": [
            "available",
            "description"
          ]
        }
      },
      "required": [
        "state",
        "operation",
        "retryable",
        "retry_after_seconds",
        "expires_at"
      ],
      "description": "Replay status, retry timing, and recovery lookup."
    },
    "type": {
      "type": "string",
      "description": "URI reference identifying the problem type",
      "example": "https://api.veryfront.com/errors/validation-failed"
    },
    "title": {
      "type": "string",
      "description": "Short human-readable summary of the problem",
      "example": "Validation Failed"
    },
    "status": {
      "type": "integer",
      "minimum": 100,
      "maximum": 599,
      "description": "HTTP status code",
      "example": 400
    },
    "code": {
      "type": "string",
      "description": "Stable machine-readable error code",
      "example": "RUN_INVALID_INPUT"
    },
    "detail": {
      "type": "string",
      "description": "Human-readable explanation specific to this occurrence",
      "example": "The 'email' field must be a valid email address"
    },
    "instance": {
      "type": "string",
      "description": "URI reference identifying the specific occurrence",
      "example": "/projects/my-project/members"
    },
    "slug": {
      "type": "string",
      "description": "Stable identifier for the problem type",
      "example": "validation-failed"
    },
    "category": {
      "type": "string",
      "enum": [
        "AUTH",
        "RESOURCE",
        "VALIDATION",
        "DATABASE",
        "SUBSCRIPTION",
        "INTEGRATION",
        "INTERNAL"
      ],
      "description": "API error category",
      "example": "VALIDATION"
    },
    "suggestion": {
      "type": "string",
      "description": "Suggested action to resolve the problem",
      "example": "Check the request body and query parameters against the API documentation."
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "description": "Field path that caused the error",
            "example": "email"
          },
          "message": {
            "type": "string",
            "description": "Error message for this field",
            "example": "Invalid email format"
          },
          "code": {
            "type": "string",
            "description": "Error code for this field",
            "example": "INVALID_FORMAT"
          }
        },
        "required": [
          "field",
          "message"
        ]
      },
      "description": "Detailed field-level errors for validation failures"
    }
  },
  "required": [
    "type",
    "title",
    "status"
  ]
}

Operation contract

json
{
  "operationId": "createAgent",
  "tags": [
    "agents/Agents/Agents"
  ],
  "summary": "Create agent",
  "description": "Create agent. Requires project.agents.write.",
  "parameters": [
    {
      "$ref": "#/components/parameters/ProjectReference"
    },
    {
      "schema": {
        "type": "string"
      },
      "required": false,
      "name": "source_target_kind",
      "in": "query"
    },
    {
      "schema": {
        "type": [
          "string",
          "null"
        ],
        "format": "uuid"
      },
      "required": false,
      "name": "target_branch_id",
      "in": "query"
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[a-zA-Z0-9_-]+$"
            },
            "name": {
              "type": "string",
              "minLength": 1
            },
            "description": {
              "type": [
                "string",
                "null"
              ]
            },
            "model": {
              "type": [
                "string",
                "null"
              ]
            },
            "system_prompt": {
              "type": "string",
              "minLength": 1
            },
            "thinking": {
              "type": "object",
              "properties": {
                "enabled": {
                  "type": "boolean"
                },
                "budget_tokens": {
                  "type": "number",
                  "exclusiveMinimum": 0
                }
              },
              "required": [
                "enabled"
              ],
              "additionalProperties": false
            },
            "temperature": {
              "type": [
                "number",
                "null"
              ],
              "minimum": 0,
              "maximum": 2
            },
            "max_steps": {
              "type": [
                "integer",
                "null"
              ],
              "exclusiveMinimum": 0
            },
            "allowed_models": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              }
            },
            "skill_ids": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              }
            },
            "skill_selection": {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "omitted",
                    "explicit"
                  ]
                },
                "skill_ids": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "minLength": 1
                  },
                  "default": []
                }
              },
              "required": [
                "kind"
              ]
            },
            "skills": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "maxItems": 500
                },
                {
                  "type": "object",
                  "additionalProperties": {
                    "type": "boolean"
                  }
                }
              ]
            },
            "all_tools_enabled": {
              "type": "boolean"
            },
            "tool_ids": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              },
              "description": "Project tools, platform tools, and integration catalog tools returned by get_integration. Use exact names from the agent tool references search."
            },
            "tools": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "maxItems": 500
                },
                {
                  "type": "object",
                  "additionalProperties": {
                    "type": "boolean"
                  }
                }
              ],
              "description": "Callable host-tool selector. Use false to disable all host tools, including skill and delegation tools. An empty array or map selects no project tools but preserves legacy runtime essentials. Provider-native tools use provider_tool_ids."
            },
            "tool_loading": {
              "type": "string",
              "enum": [
                "eager",
                "deferred"
              ]
            },
            "tool_result_context": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "object",
                  "properties": {
                    "max_inline_bytes": {
                      "type": "integer",
                      "exclusiveMinimum": 0,
                      "maximum": 1048576
                    },
                    "preview_bytes": {
                      "type": "integer",
                      "exclusiveMinimum": 0,
                      "maximum": 1048576
                    },
                    "max_section_bytes": {
                      "type": "integer",
                      "minimum": 4,
                      "maximum": 1048576
                    },
                    "max_stored_results": {
                      "type": "integer",
                      "exclusiveMinimum": 0,
                      "maximum": 1024
                    }
                  },
                  "additionalProperties": false
                }
              ]
            },
            "knowledge": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 4096
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 4096
                  },
                  "maxItems": 1024
                },
                {
                  "type": "object",
                  "additionalProperties": {
                    "type": "boolean"
                  }
                }
              ]
            },
            "provider_tool_ids": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              },
              "description": "Provider-native model tools only. Never put tool references from tool_ids here."
            },
            "suggestions": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "anyOf": [
                  {
                    "type": "string",
                    "minLength": 1
                  },
                  {
                    "type": "object",
                    "properties": {
                      "title": {
                        "type": "string",
                        "minLength": 1
                      },
                      "prompt": {
                        "type": "string",
                        "minLength": 1
                      }
                    },
                    "required": [
                      "title",
                      "prompt"
                    ],
                    "additionalProperties": false
                  }
                ]
              }
            },
            "avatar": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "seed": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128
                },
                "archetype": {
                  "type": "string",
                  "enum": [
                    "upright",
                    "slumped",
                    "alert",
                    "profile",
                    "leaning",
                    "crouched",
                    "tall",
                    "spread",
                    "happy",
                    "sad",
                    "angry",
                    "surprised",
                    "sleepy",
                    "curious"
                  ]
                },
                "texture": {
                  "type": "string",
                  "pattern": "^(?:[0-9]|none)$"
                },
                "color": {
                  "type": "string",
                  "pattern": "^#[0-9a-fA-F]{6}$"
                },
                "shape": {
                  "type": "string",
                  "enum": [
                    "snircle",
                    "circle",
                    "square"
                  ]
                },
                "matrix": {
                  "type": "string",
                  "pattern": "^[012]{16}$"
                }
              }
            },
            "avatar_url": {
              "type": [
                "string",
                "null"
              ],
              "format": "uri"
            },
            "security_enabled": {
              "type": "boolean"
            }
          },
          "required": [
            "id",
            "name",
            "system_prompt"
          ]
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Agent created",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AgentSource"
          }
        }
      }
    },
    "400": {
      "description": "Bad request",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/AgentProblem"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/AgentProblem"
          }
        }
      }
    },
    "500": {
      "description": "Server error",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "503": {
      "description": "internal: authentication state is temporarily unavailable and the request was not processed; retry shortly.",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    }
  },
  "x-documentation-source-tag": "Project agents",
  "x-canonical-documentation": {
    "domain": "agents",
    "resource": "Agents",
    "subgroup": "Agents",
    "name": "Create agent",
    "description": "Create agent. Requires project.agents.write.",
    "operationId": "createAgent"
  },
  "x-mint": {
    "href": "/cloud/rest/api-reference/agents-agents-agents/create-agent"
  }
}