Skip to main content

​
What is implemented

OpenAgents now has a runtime-owned registry for JSON tool definitions and JSON skill definitions, exposed through Laravel and persisted in the Elixir runtime domain. This registry is not a planning artifact anymore; it is actively wired into runtime execution. Tool execution requests can resolve integration manifests by reference, and skill specs can be compiled and published into immutable release bundles with content hashes and compatibility reports. The user-facing API surface is available under authenticated Laravel routes. Tool specs are managed through /api/runtime/skills/tool-specs. Skill specs are managed through /api/runtime/skills/skill-specs. Publishing is done through /api/runtime/skills/skill-specs/{skillId}/{version}/publish, and immutable bundle retrieval is done through /api/runtime/skills/releases/{skillId}/{version}.

​
Built-in compatibility with existing integrations

The runtime registry includes built-in first-party entries so the platform works before custom registry rows are created. Today those built-ins include github.primary for coding.v1 and resend.primary for comms.v1. These built-ins are merged with database-published specs when listing registry content, and manifest resolution can use either source transparently. This means OpenAgents already has direct continuity with the coding and comms integration surface that has been developed so far. The runtime can resolve a manifest for GitHub or Resend by integration identifier without requiring callers to inline complete manifest payloads every time.

​
Manifest resolution during tool execution

Tool execution is invoked through: 
POST /api/runtime/tools/execute
The request may include either a full manifest object or a compact manifest_ref object. Runtime resolution supports references such as integration_id and validates that the resulting manifest matches the requested tool_pack. If both manifest and manifest_ref are present, explicit manifest takes precedence, while manifest_ref remains the preferred path for registry-backed execution because it keeps payloads smaller and source-of-truth metadata centralized. This behavior is what makes the registry operational instead of decorative. We are no longer treating integration metadata as static prompt text; runtime uses it directly to decide which integration manifest is active for a tool call.

​
Skill publish model and immutable releases

Skill specs are versioned and can be staged in states such as draft, validated, published, or deprecated. Publishing a skill version triggers runtime compilation into an Agent Skills bundle, computes a deterministic bundle hash, and stores a SkillRelease record with compatibility output. That release payload is immutable by version contract and can be retrieved by skill_id plus version. In practical terms, this gives OpenAgents a traceable path from authored skill JSON to an execution-ready runtime artifact. It also creates a clean seam for later marketplace and billing integration because the release object is a stable unit that can carry provenance, compatibility, and commercial metadata.

​
Example registry payloads

Tool spec upsert payloads are sent as: 
{
  "state": "validated",
  "tool_spec": {
    "tool_id": "github.custom",
    "version": 1,
    "tool_pack": "coding.v1",
    "name": "GitHub Custom",
    "description": "Custom coding skill tool",
    "execution_kind": "http",
    "integration_manifest": {
      "manifest_version": "coding.integration.v1",
      "integration_id": "github.custom",
      "provider": "github",
      "status": "active",
      "tool_pack": "coding.v1",
      "capabilities": ["get_issue", "get_pull_request"]
    }
  }
}
Skill spec upsert payloads are sent as: 
{
  "state": "validated",
  "skill_spec": {
    "skill_id": "github-coding-custom",
    "version": 1,
    "name": "GitHub Coding Custom",
    "description": "Custom coding workflow skill",
    "instructions_markdown": "Use coding tools for issue workflows.",
    "allowed_tools": [{"tool_id": "github.custom", "version": 1}]
  }
}
These examples match the currently implemented runtime contract and are accepted by the Laravel bridge controllers that proxy into runtime internal endpoints.

​
Where this should evolve next

The immediate next step is to make these routes first-class in the public OpenAPI surface so the generated API reference in this docs site reflects them directly. The behavior already exists and is stable in code, but the public spec generation currently lags because these controllers are not yet fully described with OpenAPI attributes. Until that sync lands, this page and the runtime contract docs in the openagents repository are the canonical reference for registry operations.