Is there any documentation on the ResponseInputItemParam type from the OpenAI SDK (which has an alias TResponseInputItem in the Agents SDK)? I need to know what keys are valid.
#ResponseInputItemParam documentation
acoustic steppe
surreal sparrowBOT
Hi @acoustic steppe. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
The knowledge sources do not mention a type named ResponseInputItemParam or its alias TResponseInputItem in the OpenAI SDK or Agents SDK. However, based on the OpenAI API documentation for the Responses endpoint, the structure for input items (which may correspond to what you’re asking about) is described in detail.
For the createResponse endpoint, input items are provided as an array of objects, each representing a message or content item. The most common structure is an "Input message", which looks like this:
{
"role": "user" | "assistant" | "system" | "developer",
"content": [
{
"type": "input_text",
"text": "Your input here"
},
{
"type": "input_image",
"image_url": "<https://...",>
"file_id": null,
"detail": "auto" | "low" | "high"
},
{
"type": "input_file",
"file_id": "file-...",
"filename": "example.txt",
"file_data": "base64-encoded-content"
}
// ...other input item types
]
}
- The top-level object must have a role and a content array.
- Each item in content must have a type key (e.g., input_text, input_image, input_file) and the corresponding required fields for that type.
For example, a simple text input would be:
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "Tell me a story."
}
]
}
Other valid keys depend on the type of input item (e.g., input_image requires detail and optionally image_url or file_id).
If you are using the OpenAI Node SDK, the types for these objects are not explicitly named ResponseInputItemParam in the documentation, but the structure above matches what is accepted by the API. For more details, see the OpenAI API reference for Responses > createResponse.
If you need the exact TypeScript type, the SDK recently improved type exports for response input items, so you may now find OpenAI.Responses.ResponseInput or similar types exported in the latest SDK versions, as discussed in this GitHub issue.
If you need more specific details or a direct type definition, please refer to the SDK source or the API reference, as the knowledge sources do not provide a type named ResponseInputItemParam or TResponseInputItem directly.
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
acoustic steppe
@surreal sparrow That sounds about right but with the Assistants API I was also able to include metadata; If I try and do the same with the Agents SDK though it errors. Are there not any other fields besides "role" and "content"? I am using the Agents SDK for Python.
surreal sparrowBOT
Let me check the knowledge base for you again. One moment! :books:
Based on the available knowledge sources, the Assistants API allows you to include a metadata field when creating a message, which can store up to 16 key-value pairs for structured information (API reference – createMessage). The relevant part of the schema is:
"metadata": {
"type": "object",
"description": "Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.",
"additionalProperties": {"type": "string"},
"nullable": True
}
However, for the Agents SDK (Python), the knowledge sources do not mention support for a metadata field or any fields beyond "role" and "content" in the input items (TResponseInputItem/ResponseInputItemParam). The documented valid keys for input items in the context of the Agents SDK are "role" and "content" only. Attempting to include metadata with the Agents SDK results in an error, as you have observed.
In summary:
- Assistants API: Supports metadata on messages.
- Agents SDK: Only "role" and "content" are valid; metadata is not supported according to the available documentation.
If you need metadata-like functionality with the Agents SDK, you may need to manage it separately in your application logic, as the SDK itself does not support it at this time (Forum post: Agents SDK threads).
If you need further confirmation or updates, you may want to check the Agents SDK documentation or the repository for the latest changes.
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
acoustic steppe
@surreal sparrow What would I use the "developer" role for?
surreal sparrowBOT
Let me check the knowledge base for you again. One moment! :books:
The "developer" role is used to provide instructions to the model that define the system's rules and business logic. These instructions are prioritized ahead of "user" messages, meaning they take precedence when the model determines how to respond. You can think of "developer" messages as similar to a function definition in programming, while "user" messages are like the arguments to that function. This allows you, as the application developer, to control the model's behavior more strictly, ensuring that your rules are followed even if the user provides conflicting instructions Message roles and instruction following.
For example, you might use a "developer" message to instruct the model to always respond in a certain style or to enforce specific business logic, regardless of what the user asks.
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
acoustic steppe
@surreal sparrow So what is the difference between "developer" and "system"
surreal sparrowBOT
Let me check the knowledge base for you again. One moment! :books:
The knowledge sources indicate that both "developer" and "system" roles are used to provide instructions to the model, but there is a distinction in their usage and priority:
-
developer: Messages with this role are instructions provided by the application developer. They are prioritized ahead of "user" messages and are intended to define the system's rules and business logic. The "developer" role is the preferred way to provide high-authority instructions, especially with newer models (o1 and later) Message roles and instruction following.
-
system: Messages with this role are also used to provide instructions that the model should follow, regardless of user input. However, with o1 models and newer, it is recommended to use "developer" messages instead of "system" messages for this purpose. "system" messages are still supported for backward compatibility and may be used with older models Chat API reference.
In summary:
- Use "developer" for high-priority, developer-defined instructions (especially with newer models).
- Use "system" for system-level instructions, but prefer "developer" for new implementations.
The OpenAI model spec describes how models give different levels of priority to messages with different roles, with "developer" taking precedence over "user" and "assistant" roles Message roles and instruction following.