Agent Metadata

Every Orbit agent includes a metadata file (ai-tools.json) that describes its identity, capabilities, configuration, and compliance requirements.

This metadata ensures that agents are interoperable across Orbit Console and Hosted platforms, while remaining secure and auditable.

Why Metadata Matters

• Discovery – Agents can be listed, searched, and filtered in the Agent Registry.
• Standardization – Provides a common format for describing agent inputs, tools, and configuration.
• Security – Defines authentication, rate limits, and compliance requirements.
• Execution – Tells Orbit how to invoke the agent, check health, and support chat or tool interfaces.

Core Sections

Below is a breakdown of the major sections of an ai-tools.json file.

Identity

Capabilities

Defines what the agent can do, including supported interfaces (e.g. chat) and tools.

Each tool has:

• name – unique identifier.
• description – summary of the tool’s purpose.
• inputSchema – JSON Schema for validating inputs.

Example:

"capabilities": {
  "interfaces": ["chat"],
  "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"]
      }
    }
  ]
}

Endpoints

Defines how Orbit invokes and monitors the agent.

Configuration

Specifies defaults for chat models, prompts, formats, and runtime behavior.

Key fields include:

• defaultPayload – baseline model config (model name, temperature, max tokens).
• systemPrompt – instruction given to the agent.
• supportedFormats – response types (e.g. JSON, text).
• streaming – whether responses can be streamed.

Example:

"configuration": {
  "chat": {
    "defaultPayload": {
      "model": "billing-agent-v1",
      "temperature": 0.3,
      "max_tokens": 1500,
      "messages": [
        { "role": "system", "content": "{{system}}" },
        { "role": "user", "content": "{{message}}" }
      ]
    },
    "systemPrompt": "You are a specialized billing agent assistant...",
    "supportedFormats": ["json", "text"],
    "streaming": true
  }
}

Compliance & Security

Defines policies that agents must follow in order to operate in Orbit.

• Compliance
  • orbitContract – whether the agent follows Orbit’s contract/protocol.
  • hmacRequired – whether HMAC signing is required.
• Security
  • requiresAuth – true if authentication is mandatory.
  • rateLimits – request limits per minute/hour.

Example:

"meta": {
  "compliance": {
    "orbitContract": true,
    "hmacRequired": true
  },
  "security": {
    "requiresAuth": true,
    "rateLimits": {
      "perMinute": 60,
      "perHour": 1000
    }
  }
}

Example: Billing Agent Metadata

Here’s a complete example for a Billing Agent:

{
  "name": "billing-agent",
  "type": "agent",
  "version": "0.1.0",
  "description": "Handles billing and invoice operations",
  "capabilities": { ... },
  "invoke": { "path": "/invoke", "method": "POST" },
  "health": { "path": "/health" },
  "configuration": { ... },
  "meta": { ... }
}

Best Practices

• Always include versioning to track schema evolution.
• Keep systemPrompt secure and domain-specific.
• Use JSON Schema for all tool inputs to guarantee validation.
• Apply rate limits to prevent misuse or denial of service.
• Test health endpoints regularly for uptime compliance.

Related Pages

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