Skip to Content
OperationsCapability Changes

Capability Changes

The agent loads capability.yaml only at startup. To change a capability, edit the file, validate it, and restart the agent. The commands below stop the running agent only if validation succeeds, so a broken file never takes a working agent offline.

Run the commands on this page, including validate, as an administrator: the service runs as root (LocalSystem on Windows), and the spool and identity directories and the secret files must be owned by that user.

Apply a change to an existing service

Edit the file registered with the service, then run:

CAPABILITY_FILE=/absolute/path/capability.yaml
 
onprest-agent validate --config "$CAPABILITY_FILE" &&
  onprest-agent service stop &&
  onprest-agent service start &&
  onprest-agent service status

Validation runs while the current agent stays online. If it fails, nothing else runs; fix the file using the message it printed (and the log path it names, if any). See Troubleshooting.

If you add a capability, also add it to the callers’ API keys and restart the gateway; see API Keys.

Install a new service

CAPABILITY_FILE=/absolute/path/capability.yaml
 
onprest-agent validate --config "$CAPABILITY_FILE" &&
  onprest-agent service install --config "$CAPABILITY_FILE" &&
  onprest-agent service start &&
  onprest-agent service status

service install registers the agent with systemd, launchd, or Windows Service. It does not enable start on boot.

Check the result

After the restart, check that the gateway sees the new definition:

GATEWAY_URL=https://gateway.example.com
ONPREST_API_KEY=replace-with-plaintext-api-key
CAPABILITY_NAME=get_customer
CAPABILITY_ARGS='{"customer_id":1}'
 
curl --fail-with-body -sS "$GATEWAY_URL/healthz"
curl --fail-with-body -sS \
  -H "Authorization: Bearer $ONPREST_API_KEY" \
  "$GATEWAY_URL/openapi.json"
curl --fail-with-body -sS \
  -X POST "$GATEWAY_URL/api/v1/capabilities/$CAPABILITY_NAME" \
  -H "Authorization: Bearer $ONPREST_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$CAPABILITY_ARGS"
curl --fail-with-body -sS \
  -X POST "$GATEWAY_URL/mcp" \
  -H "Authorization: Bearer $ONPREST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"$CAPABILITY_NAME\",\"arguments\":$CAPABILITY_ARGS}}"

/healthz should report agent_connected: true, and OpenAPI should show the new contract. An MCP tool error still returns HTTP 200 with isError: true, so read the body, not just curl’s exit code.

If the agent was restarted without validation and fails at startup, it stays offline and the gateway keeps reporting agent_connected: false until a valid file is in place. Download links from before the restart no longer work.

DeploymentUncertain Outcomes