---
title: "Run a deployed Agent"
method: POST
path: "/v1/agents/run"
tags: ["Agent Operations"]
---

# Run a deployed Agent

`POST /v1/agents/run`

Execute an agent by sending the provided message to the agent service. Returns a detailed response containing the conversation messages, logs, and metadata.

## Request body

- RunRequest
  - `agent_id` string, required — Unique identifier for the agent.
  - `message` union, required — The message or command to be sent to the agent.
    - string
    - object
  - `agent_history` unknown[], nullable — List of prior messages; defaults to empty list.
    - unknown
  - `thread_id` string, nullable — Unique identifier for the chat session.
  - `hitl_decision` 'approve' | 'edit' | 'reject', nullable — Human-in-the-loop decision for the 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

---

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