Agent Blueprints Schema

Agent Schemas define the inputs and outputs of an agent’s tools.
They live inside the agent’s ai-tools.json file, under the capabilities.tools section.

Think of:

• Metadata = the envelope (identity, endpoints, compliance, security).
• Schema = the contract (how tools are invoked, validated, and composed).

Where Schema Lives

Each tool in ai-tools.json includes at minimum:

• name — tool identifier (e.g., invoices.list)
• description — what the tool does
• inputSchema — JSON Schema defining valid input payloads
• outputSchema (optional but encouraged) — JSON Schema describing returned data

Example:

{
  "capabilities": {
    "tools": [
      {
        "name": "invoices.list",
        "description": "List invoices by status or date",
        "inputSchema": {
          "type": "object",
          "properties": {
            "status": {
              "type": "string",
              "enum": ["pending", "paid", "overdue"]
            },
            "fromDate": { "type": "string", "format": "date" },
            "toDate": { "type": "string", "format": "date" },
            "limit": { "type": "number", "minimum": 1, "maximum": 100 }
          },
          "required": ["status"]
        }
      }
    ]
  }
}

Schema Conventions

Required vs Optional

• Use required for fields the tool cannot function without.
• Omit fields from required if defaults can be applied.

Constrained Inputs

• Use enum for controlled vocabularies (e.g., status).
• Use format for validation (date, date-time, email, uri).
• Use numeric ranges for paging/limits.

Output Schema (Optional)

Encourage downstream composition by describing responses:

{
  "name": "invoices.get",
  "inputSchema": {
    "type": "object",
    "properties": { "invoiceId": { "type": "string" } },
    "required": ["invoiceId"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "invoiceId": { "type": "string" },
      "amount": { "type": "number" },
      "status": { "type": "string", "enum": ["pending", "paid", "overdue"] },
      "dueDate": { "type": "string", "format": "date" }
    },
    "required": ["invoiceId", "amount", "status"]
  }
}

Reuse with $defs

Schemas can define reusable shapes in $defs:

{
  "$defs": {
    "Invoice": {
      "type": "object",
      "properties": {
        "invoiceId": { "type": "string" },
        "amount": { "type": "number" },
        "status": { "type": "string", "enum": ["pending", "paid", "overdue"] }
      },
      "required": ["invoiceId", "amount", "status"]
    }
  },
  "properties": {
    "invoices": {
      "type": "array",
      "items": { "$ref": "#/$defs/Invoice" }
    }
  }
}

Best Practices

• Always include name, description, and inputSchema.
• Add outputSchema where structured responses are expected.
• Use title and description inside schemas for clearer errors and UI hints.
• Validate schemas at build/CI time using a JSON Schema validator.
• Version the agent (version in metadata) when schemas change in a breaking way.
• Keep schemas minimal but expressive: enough to enforce correctness, not enough to block evolution.

How Schema Connects to Orbit Flow When an agent tool’s output matches its outputSchema, Orbit Flow can render UI components automatically (chart, table, metric, markdown). See Declarative Schema for details.

Related Pages

• Agent Metadata — overall structure of ai-tools.json
• Agent Registry — where agents are registered
• Declarative Schema — how outputs become UI