Messages

The Agent Platform API is designed to be as simple as possible, mapping directly to the most primitive inputs and outputs of large language models. Rather than managing a complex "message history" or traditional conversation state, the API accepts a flat array of explicit input items.

Every item requires a type property to explicitly identify its structure.

Standard Messages

Standard dialogue turns map directly to the system, user, and assistant roles.

[
  {
    "type": "message",
    "role": "system",
    "content": "You are a helpful assistant."
  },
  {
    "type": "message",
    "role": "user",
    "content": "What is the weather?"
  },
  {
    "type": "message",
    "role": "assistant",
    "content": "Let me check that for you."
  }
]

Reasoning

For models that output internal reasoning before answering, you can provide previous reasoning outputs as context.

{
  "type": "reasoning",
  "content": "The user asked for the weather. I should use the weather tool."
}

Tool Calls

When the assistant invokes a tool, use the tool_call type with state set to "call". The arguments generated by the model are passed as a string in content.

{
  "type": "tool_call",
  "tool_name": "fetch_weather",
  "state": "call",
  "content": "{\"location\": \"Tokyo\"}"
}

Tool Results

After a tool has executed, its outcome is appended to the context. It uses the tool_call type with the role set to "tool". You must provide the original arguments as a string in input_args, the result as a string in output, and whether the execution was a "success" or "error".

{
  "type": "tool_call",
  "role": "tool",
  "tool_name": "fetch_weather",
  "state": "success",
  "input_args": "{\"location\": \"Tokyo\"}",
  "output": "{\"temperature\": \"22C\", \"condition\": \"Sunny\"}"
}

Metadata

All input items accept an optional metadata property (a dictionary of string keys to unknown values) to store your application-specific tracking data. This metadata is ignored by the LLM inference engine but preserved in the state.

{
  "type": "message",
  "role": "user",
  "content": "Hello",
  "metadata": {
    "user_id": "123",
    "source": "web_chat"
  }
}