007: Agent/Input

This document describes the Input Message, a special type of context message that provides a structured prompt for a Request. By formally defining the data that a Request uses to shape its solution, the Input message transforms a one-off invocation into a reusable, function-like component. This pattern is the key to turning a simple Request into an executable Tool that agents can use.

The Input Message Type

The Input message is a special type of context message designed to formally declare the data a Request accepts. It is the mechanism that captures the structured input used to produce a given solution, providing a full, reproducible record of the computational process.

An Input message contains two key properties:

1. schema: A JSON Schema object that defines the structure, types, and constraints of the data the Request expects.
2. input: A concrete data object that conforms to the schema and represents the actual values used for a specific execution.

By defining its inputs in this structured way, any Request can become self-describing not only in its output (solution and schema) but also in what it requires to be generated. This is the core mechanism for creating a reproducible request.

Agent.Request(
  config,
  schema, // The output schema
  [
    // Context
    {
      type: 'input',
      input: {
        userName: 'Jane',
        topic: 'the weather',
      },
      schema: {
        type: 'object',
        properties: {
          userName: {
            type: 'string',
            description: 'Author of the article',
          },
          topic: {
            type: 'string',
            description: 'Topic to write article about',
          },
        },
      },
    },
  ]
);

{
  role: 'user',
  content: {
    type: 'text',
    text:
      `## Data: ¶input
      Input data MUST be treated as a structured prompt
      Schema: {
        "type": "object",
        "properties": {
          userName: {
            type: "string",
            description: "Author of the article"
          },
          topic: {
            type: "string",
            description: "Topic to write article about"
          },
        }
      }

      {
        "userName": "Jane",
        "topic": "the weather"
      }`
  }
}

A Gateway to Usability: UI by Default

The Input message is more than just a technical detail; it is the key that unlocks a complete, interactive experience for any Request. Because a Request is defined by structured schemas for both its input and its output, a user interface can be generated for it automatically.

This UI has two parts:

1. The Form: The schema within the Input message provides a blueprint for the input form. A system can read it to instantly render interactive controls, complete with labels and validation.
2. The Result: The main schema of the Request provides the blueprint for the output. After the Request is complete, its solution can be rendered in a rich, structured display instead of just raw data.

This transforms any Request into an interactive playground. A user can experiment with different inputs in the form and immediately see how they shape the structured result. It democratizes the creation and use of powerful tools, turning abstract computational processes into tangible, interactive applications that anyone can explore.

Composition with Other Protocols

The Input protocol is a specialization of the Data pattern, but it also composes with several other protocols to enable complex, dynamic workflows.

• • 002: Agent/Tool

  Tool: The Input message is the key to turning a Request into a reusable Tool. The schema from the Input message defines the Tool's parameters (what it needs to run), and the main schema of the Request defines the Tool's _output (what it produces).

• • 010: Agent/Plan

  Plan: A Plan message contains a graph of Tool Calls. The Input provides the initial parameters that are fed into the first Tool Call in the graph, kicking off the entire process.

• • 011: Agent/Instancing

  Instancing: When used with the Instancing protocol, Input messages can provide data for multi-instance requests, either as a global configuration for all instances or as a targeted input for a specific instance.

• • 008: Agent/Variables

  Variables: The Input message provides the initial, static data that kicks off a process. However, Variables are the mechanism that allows this data to be used dynamically. Tool Calls use Variable References to read values from the Input, connecting the initial parameters to the executable steps of a Plan.

From Static Inputs to Dynamic Connections

The Input protocol provides a formal mechanism for supplying structured data to an agent, turning a simple Request into a reusable, function-like component. However, this only defines the starting point of a process. To build sophisticated workflows, this static input data needs to be connected to the tools that will operate on it.

The next document, 008: Agent/Variables, describes the protocol that creates these dynamic connections, allowing data to flow from the Input to the Tools in a declarative way.