Skip to content
Core ConceptsCLI ReferenceAPI Reference
AGH RuntimeAPI Reference

Tools

AGH Tools HTTP endpoints.

Audience
Operators running durable agent work
Focus
API Reference guidance shaped for scanability, day-two clarity, and operator context.

List session-callable registry tools

GET/api/sessions/{id}/tools

Path Parameters

id*string

Session id

Query Parameters

workspace_id?string

Effective workspace id

workspace?string

Effective workspace reference

agent_name?string

Effective agent name

Response Body

application/json

application/json

application/json

curl -X GET "https://loading/api/sessions/string/tools"
{
  "tools": [
    {
      "availability": {
        "authorized": true,
        "available": true,
        "conflicted": true,
        "enabled": true,
        "executable": true,
        "reason_codes": [
          "approval_canceled"
        ],
        "registered": true
      },
      "decision": {
        "agent_policy_result": "string",
        "approval_required": true,
        "availability_result": "string",
        "callable": true,
        "hook_result": "string",
        "reason_codes": [
          "approval_canceled"
        ],
        "registry_policy_result": "string",
        "session_policy_result": "string",
        "source_policy_result": "string",
        "system_permission_mode": "string",
        "visible_to_operator": true,
        "visible_to_session": true
      },
      "descriptor": {
        "backend": {
          "extension_id": "string",
          "handler": "string",
          "kind": "native_go",
          "mcp_server": "string",
          "mcp_tool": "string",
          "native_name": "string",
          "requires_capabilities": [
            "string"
          ]
        },
        "concurrency_safe": true,
        "description": "string",
        "destructive": true,
        "display_title": "string",
        "input_schema": null,
        "max_result_bytes": 0,
        "open_world": true,
        "output_schema": null,
        "read_only": true,
        "requires_interaction": true,
        "risk": "read",
        "search_hints": [
          "string"
        ],
        "source": {
          "kind": "builtin",
          "owner": "string",
          "raw_server_name": "string",
          "raw_tool_name": "string",
          "resource_id": "string",
          "resource_version": "string",
          "scope": "string",
          "workspace_id": "string"
        },
        "tags": [
          "string"
        ],
        "tool_id": "string",
        "toolsets": [
          "string"
        ],
        "visibility": "internal"
      }
    }
  ]
}
{
  "error": {
    "code": "tool_not_found",
    "details": {
      "property1": null,
      "property2": null
    },
    "layer": "string",
    "message": "string",
    "reason_codes": [
      "approval_canceled"
    ],
    "tool_id": "string"
  }
}
{
  "error": "string"
}
Empty

Search session-callable registry tools

POST/api/sessions/{id}/tools/search

Path Parameters

id*string

Session id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://loading/api/sessions/string/tools/search" \  -H "Content-Type: application/json" \  -d '{    "query": "string"  }'
{
  "tools": [
    {
      "availability": {
        "authorized": true,
        "available": true,
        "conflicted": true,
        "enabled": true,
        "executable": true,
        "reason_codes": [
          "approval_canceled"
        ],
        "registered": true
      },
      "decision": {
        "agent_policy_result": "string",
        "approval_required": true,
        "availability_result": "string",
        "callable": true,
        "hook_result": "string",
        "reason_codes": [
          "approval_canceled"
        ],
        "registry_policy_result": "string",
        "session_policy_result": "string",
        "source_policy_result": "string",
        "system_permission_mode": "string",
        "visible_to_operator": true,
        "visible_to_session": true
      },
      "descriptor": {
        "backend": {
          "extension_id": "string",
          "handler": "string",
          "kind": "native_go",
          "mcp_server": "string",
          "mcp_tool": "string",
          "native_name": "string",
          "requires_capabilities": [
            "string"
          ]
        },
        "concurrency_safe": true,
        "description": "string",
        "destructive": true,
        "display_title": "string",
        "input_schema": null,
        "max_result_bytes": 0,
        "open_world": true,
        "output_schema": null,
        "read_only": true,
        "requires_interaction": true,
        "risk": "read",
        "search_hints": [
          "string"
        ],
        "source": {
          "kind": "builtin",
          "owner": "string",
          "raw_server_name": "string",
          "raw_tool_name": "string",
          "resource_id": "string",
          "resource_version": "string",
          "scope": "string",
          "workspace_id": "string"
        },
        "tags": [
          "string"
        ],
        "tool_id": "string",
        "toolsets": [
          "string"
        ],
        "visibility": "internal"
      }
    }
  ]
}
{
  "error": {
    "code": "tool_not_found",
    "details": {
      "property1": null,
      "property2": null
    },
    "layer": "string",
    "message": "string",
    "reason_codes": [
      "approval_canceled"
    ],
    "tool_id": "string"
  }
}
{
  "error": {
    "code": "tool_not_found",
    "details": {
      "property1": null,
      "property2": null
    },
    "layer": "string",
    "message": "string",
    "reason_codes": [
      "approval_canceled"
    ],
    "tool_id": "string"
  }
}
{
  "error": "string"
}
Empty

List operator-visible registry tools

GET/api/tools

Query Parameters

workspace_id?string

Effective workspace id

workspace?string

Effective workspace reference

session_id?string

Effective session id

agent_name?string

Effective agent name

Response Body

application/json

application/json

application/json

curl -X GET "https://loading/api/tools"
{
  "tools": [
    {
      "availability": {
        "authorized": true,
        "available": true,
        "conflicted": true,
        "enabled": true,
        "executable": true,
        "reason_codes": [
          "approval_canceled"
        ],
        "registered": true
      },
      "decision": {
        "agent_policy_result": "string",
        "approval_required": true,
        "availability_result": "string",
        "callable": true,
        "hook_result": "string",
        "reason_codes": [
          "approval_canceled"
        ],
        "registry_policy_result": "string",
        "session_policy_result": "string",
        "source_policy_result": "string",
        "system_permission_mode": "string",
        "visible_to_operator": true,
        "visible_to_session": true
      },
      "descriptor": {
        "backend": {
          "extension_id": "string",
          "handler": "string",
          "kind": "native_go",
          "mcp_server": "string",
          "mcp_tool": "string",
          "native_name": "string",
          "requires_capabilities": [
            "string"
          ]
        },
        "concurrency_safe": true,
        "description": "string",
        "destructive": true,
        "display_title": "string",
        "input_schema": null,
        "max_result_bytes": 0,
        "open_world": true,
        "output_schema": null,
        "read_only": true,
        "requires_interaction": true,
        "risk": "read",
        "search_hints": [
          "string"
        ],
        "source": {
          "kind": "builtin",
          "owner": "string",
          "raw_server_name": "string",
          "raw_tool_name": "string",
          "resource_id": "string",
          "resource_version": "string",
          "scope": "string",
          "workspace_id": "string"
        },
        "tags": [
          "string"
        ],
        "tool_id": "string",
        "toolsets": [
          "string"
        ],
        "visibility": "internal"
      }
    }
  ]
}
{
  "error": {
    "code": "tool_not_found",
    "details": {
      "property1": null,
      "property2": null
    },
    "layer": "string",
    "message": "string",
    "reason_codes": [
      "approval_canceled"
    ],
    "tool_id": "string"
  }
}
{
  "error": "string"
}
Empty

Search operator-visible registry tools

POST/api/tools/search

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://loading/api/tools/search" \  -H "Content-Type: application/json" \  -d '{    "query": "string"  }'
{
  "tools": [
    {
      "availability": {
        "authorized": true,
        "available": true,
        "conflicted": true,
        "enabled": true,
        "executable": true,
        "reason_codes": [
          "approval_canceled"
        ],
        "registered": true
      },
      "decision": {
        "agent_policy_result": "string",
        "approval_required": true,
        "availability_result": "string",
        "callable": true,
        "hook_result": "string",
        "reason_codes": [
          "approval_canceled"
        ],
        "registry_policy_result": "string",
        "session_policy_result": "string",
        "source_policy_result": "string",
        "system_permission_mode": "string",
        "visible_to_operator": true,
        "visible_to_session": true
      },
      "descriptor": {
        "backend": {
          "extension_id": "string",
          "handler": "string",
          "kind": "native_go",
          "mcp_server": "string",
          "mcp_tool": "string",
          "native_name": "string",
          "requires_capabilities": [
            "string"
          ]
        },
        "concurrency_safe": true,
        "description": "string",
        "destructive": true,
        "display_title": "string",
        "input_schema": null,
        "max_result_bytes": 0,
        "open_world": true,
        "output_schema": null,
        "read_only": true,
        "requires_interaction": true,
        "risk": "read",
        "search_hints": [
          "string"
        ],
        "source": {
          "kind": "builtin",
          "owner": "string",
          "raw_server_name": "string",
          "raw_tool_name": "string",
          "resource_id": "string",
          "resource_version": "string",
          "scope": "string",
          "workspace_id": "string"
        },
        "tags": [
          "string"
        ],
        "tool_id": "string",
        "toolsets": [
          "string"
        ],
        "visibility": "internal"
      }
    }
  ]
}
{
  "error": {
    "code": "tool_not_found",
    "details": {
      "property1": null,
      "property2": null
    },
    "layer": "string",
    "message": "string",
    "reason_codes": [
      "approval_canceled"
    ],
    "tool_id": "string"
  }
}
{
  "error": {
    "code": "tool_not_found",
    "details": {
      "property1": null,
      "property2": null
    },
    "layer": "string",
    "message": "string",
    "reason_codes": [
      "approval_canceled"
    ],
    "tool_id": "string"
  }
}
{
  "error": "string"
}
Empty

Get one operator-visible registry tool

GET/api/tools/{id}

Path Parameters

id*string

Canonical tool id

Query Parameters

workspace_id?string

Effective workspace id

workspace?string

Effective workspace reference

session_id?string

Effective session id

agent_name?string

Effective agent name

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://loading/api/tools/string"
{
  "tool": {
    "availability": {
      "authorized": true,
      "available": true,
      "conflicted": true,
      "enabled": true,
      "executable": true,
      "reason_codes": [
        "approval_canceled"
      ],
      "registered": true
    },
    "decision": {
      "agent_policy_result": "string",
      "approval_required": true,
      "availability_result": "string",
      "callable": true,
      "hook_result": "string",
      "reason_codes": [
        "approval_canceled"
      ],
      "registry_policy_result": "string",
      "session_policy_result": "string",
      "source_policy_result": "string",
      "system_permission_mode": "string",
      "visible_to_operator": true,
      "visible_to_session": true
    },
    "descriptor": {
      "backend": {
        "extension_id": "string",
        "handler": "string",
        "kind": "native_go",
        "mcp_server": "string",
        "mcp_tool": "string",
        "native_name": "string",
        "requires_capabilities": [
          "string"
        ]
      },
      "concurrency_safe": true,
      "description": "string",
      "destructive": true,
      "display_title": "string",
      "input_schema": null,
      "max_result_bytes": 0,
      "open_world": true,
      "output_schema": null,
      "read_only": true,
      "requires_interaction": true,
      "risk": "read",
      "search_hints": [
        "string"
      ],
      "source": {
        "kind": "builtin",
        "owner": "string",
        "raw_server_name": "string",
        "raw_tool_name": "string",
        "resource_id": "string",
        "resource_version": "string",
        "scope": "string",
        "workspace_id": "string"
      },
      "tags": [
        "string"
      ],
      "tool_id": "string",
      "toolsets": [
        "string"
      ],
      "visibility": "internal"
    }
  }
}
{
  "error": {
    "code": "tool_not_found",
    "details": {
      "property1": null,
      "property2": null
    },
    "layer": "string",
    "message": "string",
    "reason_codes": [
      "approval_canceled"
    ],
    "tool_id": "string"
  }
}
{
  "error": {
    "code": "tool_not_found",
    "details": {
      "property1": null,
      "property2": null
    },
    "layer": "string",
    "message": "string",
    "reason_codes": [
      "approval_canceled"
    ],
    "tool_id": "string"
  }
}
{
  "error": {
    "code": "tool_not_found",
    "details": {
      "property1": null,
      "property2": null
    },
    "layer": "string",
    "message": "string",
    "reason_codes": [
      "approval_canceled"
    ],
    "tool_id": "string"
  }
}
{
  "error": "string"
}
Empty

Mint a local single-use approval token for one tool invocation

POST/api/tools/{id}/approvals

Path Parameters

id*string

Canonical tool id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://loading/api/tools/string/approvals" \  -H "Content-Type: application/json" \  -d '{    "session_id": "string"  }'
{
  "approval": {
    "approval_token": "string",
    "expires_at": "2019-08-24T14:15:22Z",
    "input_digest": "string",
    "tool_id": "string"
  }
}
{
  "error": {
    "code": "tool_not_found",
    "details": {
      "property1": null,
      "property2": null
    },
    "layer": "string",
    "message": "string",
    "reason_codes": [
      "approval_canceled"
    ],
    "tool_id": "string"
  }
}
{
  "error": {
    "code": "tool_not_found",
    "details": {
      "property1": null,
      "property2": null
    },
    "layer": "string",
    "message": "string",
    "reason_codes": [
      "approval_canceled"
    ],
    "tool_id": "string"
  }
}
{
  "error": {
    "code": "tool_not_found",
    "details": {
      "property1": null,
      "property2": null
    },
    "layer": "string",
    "message": "string",
    "reason_codes": [
      "approval_canceled"
    ],
    "tool_id": "string"
  }
}
{
  "error": {
    "code": "tool_not_found",
    "details": {
      "property1": null,
      "property2": null
    },
    "layer": "string",
    "message": "string",
    "reason_codes": [
      "approval_canceled"
    ],
    "tool_id": "string"
  }
}
{
  "error": "string"
}
Empty

Invoke a registry tool through executable dispatch

POST/api/tools/{id}/invoke

Path Parameters

id*string

Canonical tool id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://loading/api/tools/string/invoke" \  -H "Content-Type: application/json" \  -d '{    "input": null  }'
{
  "duration_ms": 0,
  "events": [
    {
      "agent_name": "string",
      "approval_mode": "string",
      "correlation_id": "string",
      "decision": "string",
      "destructive": true,
      "display_title": "string",
      "duration_ms": 0,
      "error_code": "tool_not_found",
      "input_digest": "string",
      "kind": "tool.call_started",
      "open_world": true,
      "read_only": true,
      "reason_codes": [
        "approval_canceled"
      ],
      "redacted_input_fields": [
        "string"
      ],
      "result_bytes": 0,
      "result_digest": "string",
      "result_redaction_paths": [
        "string"
      ],
      "risk": "read",
      "session_id": "string",
      "source_kind": "builtin",
      "source_owner": "string",
      "tool_id": "string",
      "truncated": true,
      "workspace_id": "string"
    }
  ],
  "result": {
    "artifacts": [
      {
        "bytes": 0,
        "mime_type": "string",
        "name": "string",
        "uri": "string"
      }
    ],
    "bytes": 0,
    "content": [
      {
        "data": null,
        "metadata": {
          "property1": null,
          "property2": null
        },
        "mime_type": "string",
        "text": "string",
        "type": "string"
      }
    ],
    "duration_ms": 0,
    "metadata": {
      "property1": null,
      "property2": null
    },
    "preview": "string",
    "redactions": [
      {
        "bytes": 0,
        "path": "string",
        "reason": "approval_canceled"
      }
    ],
    "structured": null,
    "truncated": true
  },
  "status": "string",
  "tool_id": "string",
  "truncated": true
}
{
  "error": {
    "code": "tool_not_found",
    "details": {
      "property1": null,
      "property2": null
    },
    "layer": "string",
    "message": "string",
    "reason_codes": [
      "approval_canceled"
    ],
    "tool_id": "string"
  }
}
{
  "error": {
    "code": "tool_not_found",
    "details": {
      "property1": null,
      "property2": null
    },
    "layer": "string",
    "message": "string",
    "reason_codes": [
      "approval_canceled"
    ],
    "tool_id": "string"
  }
}
{
  "error": {
    "code": "tool_not_found",
    "details": {
      "property1": null,
      "property2": null
    },
    "layer": "string",
    "message": "string",
    "reason_codes": [
      "approval_canceled"
    ],
    "tool_id": "string"
  }
}
{
  "error": {
    "code": "tool_not_found",
    "details": {
      "property1": null,
      "property2": null
    },
    "layer": "string",
    "message": "string",
    "reason_codes": [
      "approval_canceled"
    ],
    "tool_id": "string"
  }
}
{
  "error": {
    "code": "tool_not_found",
    "details": {
      "property1": null,
      "property2": null
    },
    "layer": "string",
    "message": "string",
    "reason_codes": [
      "approval_canceled"
    ],
    "tool_id": "string"
  }
}
{
  "error": {
    "code": "tool_not_found",
    "details": {
      "property1": null,
      "property2": null
    },
    "layer": "string",
    "message": "string",
    "reason_codes": [
      "approval_canceled"
    ],
    "tool_id": "string"
  }
}
{
  "error": {
    "code": "tool_not_found",
    "details": {
      "property1": null,
      "property2": null
    },
    "layer": "string",
    "message": "string",
    "reason_codes": [
      "approval_canceled"
    ],
    "tool_id": "string"
  }
}
{
  "error": {
    "code": "tool_not_found",
    "details": {
      "property1": null,
      "property2": null
    },
    "layer": "string",
    "message": "string",
    "reason_codes": [
      "approval_canceled"
    ],
    "tool_id": "string"
  }
}
{
  "error": "string"
}
Empty

Skills

AGH Skills HTTP endpoints.

Toolsets

AGH Toolsets HTTP endpoints.