{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/scale-ai/json-schema/scale-ai-execute-agent-request-schema.json",
  "title": "ExecuteAgentRequest",
  "x-generated": "2026-10-27",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/scale-ai-sgp-v4-openapi.yml#/components/schemas/ExecuteAgentRequest",
  "properties": {
    "model": {
      "type": "string",
      "enum": [
        "gpt-4",
        "gpt-4-0613",
        "gpt-4-32k",
        "gpt-4-32k-0613",
        "gpt-3.5-turbo",
        "gpt-3.5-turbo-0613",
        "gpt-3.5-turbo-16k",
        "gpt-3.5-turbo-16k-0613",
        "claude-instant-1",
        "claude-instant-1.1",
        "claude-2",
        "claude-2.0"
      ],
      "title": "Model",
      "description": "The ID of the model to use for the agent. We only support the models listed here so far."
    },
    "memory_strategy": {
      "$ref": "#/$defs/MemoryStrategy",
      "description": "The memory strategy to use for the agent. A memory strategy is a way to prevent the underlying LLM's context limit from being exceeded. Each memory strategy uses a different technique to condense the input message list into a smaller payload for the underlying LLM.\n\nWe only support the Last K memory strategy right now, but will be adding new strategies soon."
    },
    "tools": {
      "items": {
        "$ref": "#/$defs/Tool"
      },
      "type": "array",
      "title": "Tools",
      "description": "The list of specs of tools that the agent can use. Each spec must contain a `name` key set to the name of the tool, a `description` key set to the description of the tool, and an `arguments` key set to a JSON Schema compliant object describing the tool arguments.\n\nThe name and description of each tool is used by the agent to decide when to use certain tools. Because some queries are complex and may require multiple tools to complete, it is important to make these descriptions as informative as possible. If a tool is not being chosen when it should, it is common practice to tune the description of the tool to make it more apparent to the agent when the tool can be used effectively.\n\n"
    },
    "messages": {
      "items": {
        "$ref": "#/$defs/Message"
      },
      "type": "array",
      "title": "Messages",
      "description": "The list of messages in the conversation.\n\nExpand each message type to see how it works and when to use it. Most conversations should begin with a single `user` message."
    },
    "model_parameters": {
      "$ref": "#/$defs/ModelParameters",
      "description": "Configuration parameters for the agent model, such as temperature, max_tokens, and stop_sequences.\n\nIf not specified, the default value are:\n- temperature: 0.2\n- max_tokens: None (limited by the model's max tokens)\n- stop_sequences: None",
      "default": {
        "temperature": 0.2
      }
    },
    "instructions": {
      "title": "Instructions",
      "description": "The initial instructions to provide to the agent.\n\nUse this to guide the agent to act in more specific ways. For example, if you have specific rules you want to restrict the agent to follow you can specify them here. For example, if I want the agent to always use certain tools before others, I can write that rule in these instructions.\n\nGood prompt engineering is crucial to getting performant results from the agent. If you are having trouble getting the agent to perform well, try writing more specific instructions here before trying more expensive techniques such as swapping in other models or finetuning the underlying LLM.",
      "default": "You are an AI assistant that helps users with their questions. You can answer questions directly or acquire information from any of the attached tools to assist you. Always answer the user's most recent query to the best of your knowledge.\n\nWhen asked about what tools are available, you must list each attached tool's name and description. When asked about what you can do, mention that in addition to your normal capabilities, you can also use the attached tools by listing their names and descriptions. You cannot use any other tools other than the ones provided to you explicitly.",
      "type": "string"
    }
  },
  "type": "object",
  "required": [
    "model",
    "tools",
    "messages"
  ],
  "$defs": {
    "AgentMessage": {
      "properties": {
        "role": {
          "type": "string",
          "const": "agent",
          "title": "Role",
          "description": "The role of the message. Must be set to 'agent'.\n\nAn agent message is a message generated by an AI agent. It is different than an assistant message in that it can either contain a direct content output or a tool request that the client application must handle.",
          "default": "agent"
        },
        "content": {
          "title": "Content",
          "description": "Text output of the agent if no more tools are needed.",
          "type": "string"
        },
        "tool_request": {
          "$ref": "#/$defs/ToolRequest",
          "description": "The tool request if the agent needs more information."
        }
      },
      "type": "object",
      "title": "Agent Message"
    },
    "AssistantMessage": {
      "properties": {
        "role": {
          "type": "string",
          "const": "assistant",
          "title": "Role",
          "description": "The role of the message. Must be set to 'assistant'.\n\nAn assistant message is a message from the AI to the client. It is different from an agent message in that it cannot contain a tool request. It is simply a direct response from the AI to the client.",
          "default": "assistant"
        },
        "content": {
          "type": "string",
          "title": "Content",
          "description": "Text response from the assistant"
        }
      },
      "type": "object",
      "required": [
        "content"
      ],
      "title": "Assistant Message"
    },
    "ImageDataSubPart": {
      "properties": {
        "type": {
          "type": "string",
          "const": "base64",
          "title": "Type",
          "description": "The type of the image data. Only base64 is supported.",
          "default": "base64"
        },
        "media_type": {
          "type": "string",
          "title": "Media Type",
          "description": "The media/mime type of the image data. For example, 'image/png'. Check providers' documentation for supported media types."
        },
        "data": {
          "type": "string",
          "title": "Data",
          "description": "The base64-encoded image data."
        },
        "detail": {
          "title": "Detail",
          "description": "Only used for OpenAI. Corresponds to OpenAI's image detail parameter.",
          "type": "string",
          "enum": [
            "low",
            "high",
            "auto"
          ]
        }
      },
      "type": "object",
      "required": [
        "media_type",
        "data"
      ],
      "title": "ImageDataSubPart"
    },
    "ImageDataUserMessageContentParts": {
      "properties": {
        "type": {
          "type": "string",
          "const": "image_data",
          "title": "Type",
          "default": "image_data"
        },
        "image_data": {
          "$ref": "#/$defs/ImageDataSubPart",
          "description": "Specifies inline image data"
        }
      },
      "type": "object",
      "required": [
        "image_data"
      ],
      "title": "ImageDataUserMessageContentParts"
    },
    "ImageUrlSubPart": {
      "properties": {
        "url": {
          "type": "string",
          "title": "Url",
          "description": "The URL of the image. Note: only OpenAI supports this."
        },
        "detail": {
          "title": "Detail",
          "description": "Only used for OpenAI. Corresponds to OpenAI's image detail parameter.",
          "type": "string",
          "enum": [
            "low",
            "high",
            "auto"
          ]
        }
      },
      "type": "object",
      "required": [
        "url"
      ],
      "title": "ImageUrlSubPart"
    },
    "ImageUrlUserMessageContentParts": {
      "properties": {
        "type": {
          "type": "string",
          "const": "image_url",
          "title": "Type",
          "default": "image_url"
        },
        "image_url": {
          "$ref": "#/$defs/ImageUrlSubPart",
          "description": "Specifies the image URL and level of detail. Only supported by OpenAI models"
        }
      },
      "type": "object",
      "required": [
        "image_url"
      ],
      "title": "ImageUrlUserMessageContentParts"
    },
    "LastKMemoryStrategy": {
      "properties": {
        "name": {
          "type": "string",
          "const": "last_k",
          "title": "Name",
          "description": "Name of the memory strategy. Must be `last_k`.\n\nThis strategy truncates the message history to the last `k` messages. It is the simplest way to prevent the model's context limit from being exceeded. However, this strategy only allows the model to have short term memory. For longer term memory, please use one of the other strategies.",
          "default": "last_k"
        },
        "params": {
          "$ref": "#/$defs/LastKMemoryStrategyParams",
          "description": "Configuration parameters for the memory strategy."
        }
      },
      "type": "object",
      "required": [
        "params"
      ],
      "title": "Last K Memory Strategy"
    },
    "LastKMemoryStrategyParams": {
      "properties": {
        "k": {
          "type": "integer",
          "minimum": 1,
          "title": "K",
          "description": "The maximum number of previous messages to remember."
        }
      },
      "type": "object",
      "required": [
        "k"
      ],
      "title": "LastKMemoryStrategyParams"
    },
    "MemoryStrategy": {
      "$ref": "#/$defs/LastKMemoryStrategy",
      "title": "MemoryStrategy"
    },
    "Message": {
      "oneOf": [
        {
          "$ref": "#/$defs/UserMessage"
        },
        {
          "$ref": "#/$defs/ToolMessage"
        },
        {
          "$ref": "#/$defs/AgentMessage"
        },
        {
          "$ref": "#/$defs/SystemMessage"
        },
        {
          "$ref": "#/$defs/AssistantMessage"
        }
      ],
      "title": "Message"
    },
    "ModelParameters": {
      "properties": {
        "temperature": {
          "title": "Temperature",
          "description": "What sampling temperature to use, between [0, 1]. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. Setting temperature=0.0 will enable fully deterministic (greedy) sampling. Temperature is ignored for OpenAI reasoning models.",
          "default": 0.2,
          "type": "number",
          "maximum": 1,
          "minimum": 0
        },
        "stop_sequences": {
          "title": "Stop Sequences",
          "description": "List of up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence.",
          "items": {
            "type": "string"
          },
          "type": "array",
          "maxItems": 4
        },
        "max_tokens": {
          "title": "Max Tokens",
          "description": "The maximum number of tokens to generate in the completion. The token count of your prompt plus max_tokens cannot exceed the model's context length. If not, specified, max_tokens will be determined based on the model used: \n| Model API family | Model API default | EGP applied default |\n| --- | --- | --- |\n| OpenAI Completions | [`16`](https://platform.openai.com/docs/api-reference/completions/create#max_tokens) | `context window - prompt size` |\n| OpenAI Chat Completions | [`context window - prompt size`](https://platform.openai.com/docs/api-reference/chat/create#max_tokens) | `context window - prompt size` |\n| LLM Engine | [`max_new_tokens`](https://github.com/scaleapi/launch-python-client/blob/207adced1c88c1c2907266fa9dd1f1ff3ec0ea5b/launch/client.py#L2910) parameter is required | `100` |\n| Anthropic Claude 2 | [`max_tokens_to_sample`](https://docs.anthropic.com/claude/reference/complete_post) parameter is required | `10000` |\n",
          "type": "integer"
        },
        "topP": {
          "title": "Topp",
          "description": "The cumulative probability cutoff for token selection. Lower values mean sampling from a smaller, more top-weighted nucleus. Available for models from Anthropic, Google, Mistral, LLM Engine, and OpenAI.",
          "type": "number"
        },
        "topK": {
          "title": "Topk",
          "description": "Sample from the k most likely next tokens at each step. Lower k focuses on higher probability tokens. Available for models from Anthropic, Google, and LLM Engine.",
          "type": "integer"
        },
        "frequency_penalty": {
          "title": "Frequency Penalty",
          "description": "Penalize tokens based on how much they have already appeared in the text. Positive values encourage the model to generate new tokens and negative values encourage the model to repeat tokens. Available for models from LLM Engine, and OpenAI",
          "type": "number"
        },
        "presence_penalty": {
          "title": "Presence Penalty",
          "description": "Penalize tokens based on if they have already appeared in the text. Positive values encourage the model to generate new tokens and negative values encourage the model to repeat tokens. Available for models from LLM Engine, and OpenAI.",
          "type": "number"
        },
        "reasoning_effort": {
          "title": "Reasoning Effort",
          "description": "The effort level for the model to reason. Available for models from OpenAI.",
          "type": "string",
          "enum": [
            "low",
            "medium",
            "high"
          ]
        }
      },
      "type": "object",
      "title": "ModelParameters"
    },
    "SystemMessage": {
      "properties": {
        "role": {
          "type": "string",
          "const": "system",
          "title": "Role",
          "description": "The role of the message. Must be set to 'system'.\n\nA system message is different from other messages in that it does not originate from a party engaged in a user/AI conversation. Instead, it is a message that is injected by either the application or system to guide the conversation. For example, a system message may be used as initial instructions for an AI entity or to tell the AI that it did not do something correctly.",
          "default": "system"
        },
        "content": {
          "type": "string",
          "title": "Content",
          "description": "Text input from the system."
        }
      },
      "type": "object",
      "required": [
        "content"
      ],
      "title": "System Message"
    },
    "TextUserMessageContentParts": {
      "properties": {
        "type": {
          "type": "string",
          "const": "text",
          "title": "Type",
          "default": "text"
        },
        "text": {
          "type": "string",
          "title": "Text"
        }
      },
      "type": "object",
      "required": [
        "text"
      ],
      "title": "TextUserMessageContentParts"
    },
    "Tool": {
      "properties": {
        "name": {
          "type": "string",
          "pattern": "^[a-zA-Z0-9_-]{1,64}$",
          "title": "Name",
          "description": "Name of the tool.\n\nA tool is a function that the _client application_ has at its disposal. The tool name is the name the client wishes the Agent to use to refer to this function when it decides if it wants the user to use the tool or not. Itmust be unique amongst the set of tools provided in a single API call."
        },
        "description": {
          "type": "string",
          "title": "Description",
          "description": "Description of the tool.\n\nBecause some queries are complex and may require multiple tools to complete, it is important to make these descriptions as informative as possible. If a tool is not being chosen when it should, it is common practice to tune the description of the tool to make it more apparent to the agent when the tool can be used effectively."
        },
        "arguments": {
          "$ref": "#/$defs/ToolArguments",
          "description": "An JSON Schema-compliant schema for the tool arguments. To describe a function that accepts no parameters, provide the value `{\"type\": \"\"object\", \"properties\": {}}`.\n\nFor more information on how to define a valid JSON Schema object, visit https://json-schema.org/understanding-json-schema/reference/object.html"
        }
      },
      "type": "object",
      "required": [
        "name",
        "description",
        "arguments"
      ],
      "title": "Tool"
    },
    "ToolArguments": {
      "properties": {
        "type": {
          "type": "string",
          "const": "object",
          "title": "Type",
          "description": "Type of argument. Currently only \"object\" is supported"
        },
        "properties": {
          "additionalProperties": {
            "$ref": "#/$defs/ToolPropertyValue"
          },
          "type": "object",
          "title": "Properties",
          "description": "An object where each key is the name of a keyword argument and each value is a schema used to validate that property. Each schema must have a type and description, but can also have a default value and examples.\n\nFor more information on how to define a valid property, visit https://json-schema.org/understanding-json-schema/reference/object.html"
        },
        "required": {
          "title": "Required",
          "description": "List of required property names.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "type": "object",
      "required": [
        "type"
      ],
      "title": "ToolArguments"
    },
    "ToolMessage": {
      "properties": {
        "role": {
          "type": "string",
          "const": "tool",
          "title": "Role",
          "description": "The role of the message. Must be set to 'tool'.\n\nA tool message is a message the client application uses to send tool output to the AI. It should contain the name of the tool and the output from the tool encoded as text.",
          "default": "tool"
        },
        "name": {
          "type": "string",
          "title": "Name",
          "description": "Name of the tool"
        },
        "content": {
          "type": "string",
          "title": "Content",
          "description": "Text output from the tool"
        }
      },
      "type": "object",
      "required": [
        "name",
        "content"
      ],
      "title": "Tool Message"
    },
    "ToolPropertyValue": {
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "string",
            "number",
            "integer",
            "boolean",
            "object",
            "array",
            "null"
          ],
          "title": "Type",
          "description": "The argument's type.\n\nThe type is used to help the Agent generate valid arguments for the tool.\n\nFor more information about types, see: https://json-schema.org/understanding-json-schema/reference/type.html#type-specific-keywords"
        },
        "description": {
          "type": "string",
          "title": "Description",
          "description": "Description of what the argument is used for.\n\nThis description is used to help the Agent generate sensible arguments for the tool. It is very important that this description is succinct, clear, and accurate."
        },
        "default": {
          "title": "Default",
          "description": "A default value for the argument if unspecified.",
          "type": "string"
        }
      },
      "type": "object",
      "required": [
        "type",
        "description"
      ],
      "title": "property"
    },
    "ToolRequest": {
      "properties": {
        "name": {
          "type": "string",
          "title": "Name",
          "description": "Name of the tool that the AI wants the client to use."
        },
        "arguments": {
          "type": "string",
          "title": "Arguments",
          "description": "Arguments to pass to the tool. The format must be a JSON Schema-compliant object serialized into a string."
        }
      },
      "type": "object",
      "required": [
        "name",
        "arguments"
      ],
      "title": "ToolRequest"
    },
    "UserMessage": {
      "properties": {
        "role": {
          "type": "string",
          "const": "user",
          "title": "Role",
          "description": "The role of the message. Must be set to 'user'.\n\nA user message is a message from the user to the AI. This should be the message used to send end user input to the AI.",
          "default": "user"
        },
        "content": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "items": {
                "$ref": "#/$defs/UserMessageContentParts"
              },
              "type": "array"
            }
          ],
          "title": "Content",
          "description": "Input from the user. Can either be text or a list of content parts. Not all models support image content parts, or multiple parts."
        }
      },
      "type": "object",
      "required": [
        "content"
      ],
      "title": "User Message"
    },
    "UserMessageContentParts": {
      "oneOf": [
        {
          "$ref": "#/$defs/TextUserMessageContentParts"
        },
        {
          "$ref": "#/$defs/ImageUrlUserMessageContentParts"
        },
        {
          "$ref": "#/$defs/ImageDataUserMessageContentParts"
        }
      ],
      "title": "UserMessageContentParts"
    }
  }
}