---
title: "Create agent response"
method: POST
path: "/agents/responses"
tags: ["agents"]
---

# Create agent response

`POST /agents/responses`

Create a new agent response. Supports synchronous, streaming, and background execution modes.

## Request body

- AgentCreateResponseRequest
  - `namespace` string, required — Smithery namespace for tool discovery
  - `input` union — Input text or array of messages
    - string
    - AgentInputItem[]
      - union
        - AgentUserMessage
          - `type` 'message', required
          - `role` 'user', required
          - `content` union, required
            - AgentInputTextContent[]
              - …
            - string — Simple text content
        - AgentSystemMessage
          - `type` 'message', required
          - `role` 'system', required
          - `content` union, required
            - AgentInputTextContent[]
              - …
            - string — Simple text content
  - `model` string, nullable — Model to use
  - `previous_response_id` string, nullable — Previous response ID for multi-turn
  - `temperature` number, nullable — Temperature for generation
  - `top_p` number, nullable — Top-p sampling
  - `max_output_tokens` number, nullable — Maximum output tokens
  - `max_tool_calls` number, nullable — Maximum tool calls before stopping
  - `stream` boolean — Enable streaming response
  - `background` boolean — Run in background for long-running tasks
  - `instructions` string, nullable — Additional system instructions
  - `metadata` object, nullable — Request metadata

## Response `200`

Response created

- AgentResponse
  - `id` string, required — Response ID
  - `object` 'response', required
  - `created_at` integer, required — Unix timestamp of creation
  - `completed_at` integer, nullable, required — Unix timestamp of completion
  - `status` 'queued' | 'in_progress' | 'completed' | 'failed' | 'incomplete', required
  - `model` string, required — Model used
  - `output` AgentOutputItem[], required — Output items
    - union
      - AgentAssistantMessage
        - `id` string, required — Message ID
        - `type` 'message', required
        - `role` 'assistant', required
        - `content` AgentOutputTextContent[], required
          - `type` 'output_text', required
          - `text` string, required — The output text
        - `status` 'in_progress' | 'completed' | 'incomplete', required
      - AgentFunctionCall
        - `id` string, required — Function call ID
        - `type` 'function_call', required
        - `call_id` string, required — Tool call ID
        - `name` string, required — Function name
        - `arguments` string, required — JSON-encoded arguments
        - `status` 'in_progress' | 'completed' | 'incomplete', required
  - `usage` AgentUsage, required
    - `input_tokens` integer, required — Input tokens used
    - `output_tokens` integer, required — Output tokens generated
    - `total_tokens` integer, required — Total tokens
  - `error` object, nullable, required — Error details if failed
    - `code` string, required
    - `message` string, required
  - `background` boolean, required — Whether running in background
  - `instructions` string, nullable, required — System instructions used
  - `previous_response_id` string, nullable, required — Previous response ID
  - `metadata` object, nullable, required — Request metadata

## Other responses

- `400` — Validation error
- `500` — Server error

## Changes

- **2026-02-02** `3739e781a93e` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/smithery-ai/apis/smithery-platform-api/changes/agents/responses/post.md)

---

[API](https://skmtc.dev/smithery-ai/apis/smithery-platform-api.md) · [All operations](https://skmtc.dev/smithery-ai/apis/smithery-platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/smithery-ai/apis/smithery-platform-api/revisions/9d53933ba12e?raw)