Invoke agent tool
Invokes one high-level Verity tool through the controlled agent access layer. Use GET /agent/tools first to fetch the exact input schema for each tool.
Use response_format: "concise" for normal agent reasoning and response_format: "detailed" when the agent needs source metadata, code lists, or audit evidence. Policy search uses search_query, not a generic query field.
Write tools such as acknowledge_policy_change return 202 with approval_status: "required" unless the caller includes X-Verity-Approval: reviewed after authorized human or operator review. Read the response result_window fields before assuming a list is complete.
PHI rejections are sanitized with safe categories and counts instead of echoing raw values. Unknown-field validation errors are also sanitized, but they return generic root/path issue messages rather than raw field names. check_coverage without a state is intentionally conservative and should be routed to manual review when jurisdiction context matters.
Authorization
bearerAuth API keys are prefixed with vrt_live_ for production or vrt_test_ for testing.
Example: vrt_live_abc123xyz
In: header
Path Parameters
Agent tool ID
"check_coverage" | "validate_claim" | "find_policies" | "check_updates" | "acknowledge_policy_change"Header Parameters
Optional agent name recorded in the invocation ledger.
length <= 120Set to reviewed only after authorized review for tools that return approval_required=true.
"reviewed"Request Body
application/json
^[A-Z0-9.-]{2,20}$^[A-Z]{2}$Use concise for normal agent reasoning; use detailed only when source metadata, IDs, or audit evidence are needed.
"concise""concise" | "detailed"Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://verity.backworkai.com/api/v1/agent/tools/check_coverage" \ -H "Content-Type: application/json" \ -d '{ "code": "string" }'{
"success": true,
"data": {},
"meta": {
"request_id": "string",
"timestamp": "2019-08-24T14:15:22Z",
"tool": "string",
"actor_type": "api_client",
"actor_name": "string",
"approval_status": "not_required"
}
}{
"success": true,
"data": {},
"meta": {
"request_id": "string",
"timestamp": "2019-08-24T14:15:22Z",
"tool": "string",
"actor_type": "api_client",
"actor_name": "string",
"approval_status": "not_required"
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid query parameters",
"hint": "Check the 'code' parameter format",
"details": {}
},
"meta": {
"request_id": "req_abc123"
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid query parameters",
"hint": "Check the 'code' parameter format",
"details": {}
},
"meta": {
"request_id": "req_abc123"
}
}Last updated on