---
title: "Test an Agent with YAML configuration"
method: POST
path: "/v1/agents/test"
tags: ["Agent Operations"]
---

# Test an Agent with YAML configuration

`POST /v1/agents/test`

Test an agent by providing a YAML configuration (as a file or string) along with a message. The agent processes the message and returns a response without creating a persistent agent.

## Response `200`

Successful Response

- AgentResponse
  - `request_metadata` ResponseMeta
    - `request_id` string, nullable — Unique request identifier for tracing and support.
  - `response` object[], required
  - `usage` UsageStats, required
    - `credits_charged` CreditUsage[]
      - `agent_name` string, required
      - `number_of_runs` integer, required
      - `credit_consumed` integer, required
    - `total_credits_charged` integer
  - `additional_metadata` AdditionalMetadata, required
    - `thread_id` string, nullable

## Other responses

- `422` — Validation Error

## Changes

- **2026-03-15** `3517ca6a2c04` — 1 info
  - request property `message` list-of-types was widened by adding types `null` to media type `multipart/form-data`
- **2026-03-15** `d8e757a80870` — 3 info
  - request body became optional
  - the request property `message` became optional
  - request property `message` list-of-types was widened by adding types `object` to media type `multipart/form-data`
- **2026-03-15** `536abd065ab0` — 2 breaking, 6 info
  - request property `agent_history` list-of-types was narrowed by removing types `array and null` from media type `multipart/form-data`
  - the response's body type changed from no type to `object` for status `200`
  - added the new optional request property `hitl_decision`
  - the `agent_history` request property default value changed from `` to `[]`
  - …4 more
- **2026-02-11** `c9a09aaa6236` — 1 info
  - added the new optional request property `thread_id`
- **2025-12-18** `2db9e75ea330` — 1 info
  - api tag `Agent Operations` added

[Full history](https://skmtc.dev/svahnar/apis/svahnar-apis/changes/v1/agents/test/post.md)

---

[API](https://skmtc.dev/svahnar/apis/svahnar-apis.md) · [All operations](https://skmtc.dev/svahnar/apis/svahnar-apis/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/svahnar/svahnar-apis/revisions/02cca47c900a/schema)