---
title: "Fire a canonical test task for this agent"
method: POST
path: "/api/v1/agents/{agentId}/test-run"
tags: ["Agents"]
---

# Fire a canonical test task for this agent

`POST /api/v1/agents/{agentId}/test-run`

Used by wizard Step 5 and the persistent agent detail test panel. Uses the agent's primary capability and canonical test prompt.

## Path parameters

- `agentId` string, required

## Request body

- object
  - `taskType` string — Override task type (defaults to agent primary capability)
  - `prompt` string — Override prompt (defaults to canonical test prompt)

## Response `201`

Task created and enqueued for pipeline processing.

## Other responses

- `422` — Guardrail blocked — prompt injection, banned topic, prompt too long, or task type not allowed.
- `429` — Rate limit exceeded — max tasks/hour or max credits/day.

---

[API](https://skmtc.net/humbleaf/apis/agentchain-prior-api.md) · [All operations](https://skmtc.net/humbleaf/apis/agentchain-prior-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/humbleaf/agentchain-prior-api/revisions/33dd194c5572/schema)