Decision boundary
Vertex AI is the distribution surface. Decionis Protocol remains the execution-time decision authority. The adapter route does request normalization and response shaping only.
Use Decionis as a governed authority tool inside Vertex AI workflows without moving decision logic into the model layer. The adapter normalizes agent intent, invokes Decionis Protocol, and can return a governed verdict, Decision Dossier proof, and a short-lived signed execution token that downstream tools verify before write actions proceed.
This page documents the shareable import path for Google Cloud and Vertex AI partners.
Vertex AI is the distribution surface. Decionis Protocol remains the execution-time decision authority. The adapter route does request normalization and response shaping only.
The adapter always uses a Decionis org API key. It can now also verify an optional or required Google identity token at the adapter edge, which is the bridge toward Workload Identity Federation without moving policy logic into Vertex.
The OpenAPI artifact is intentionally thin. It describes a governed verification tool, not a second policy runtime. Keep policy versions, approvals, dossiers, and verification evidence inside Decionis surfaces.
This is the immediate shareable path for partner engineering teams.
Download or mirror this spec into a Google Cloud-controlled location if your import process prefers GCS-hosted artifacts.
https://decionis.com/openapi/decionis-vertex-extension-v1.yamlUse the API and Decision Dossier pages alongside the spec when a partner needs the adjacent contract details.
| Need | Path |
|---|---|
| API overview | /docs/api |
| Auth posture | /docs/auth |
| Decision Dossier verification | /docs/decision-dossier |
| Generic quickstart | /docs/quickstart |
| Tool bundle | https://decionis.com/google-cloud/vertex/decionis-vertex-authority-tool-bundle.json |
| Reference flow | https://decionis.com/examples/decionis-vertex-reference-flow.json |
| Standalone Agent Card | https://decionis.com/google-cloud/vertex/decionis-vertex-agent-card.json |
| A2A discovery profile | https://decionis.com/google-cloud/vertex/decionis-vertex-a2a-discovery-profile.json |
| Google identity claims map | https://decionis.com/google-cloud/vertex/decionis-vertex-identity-claims-map.json |
| Marketplace readiness | https://decionis.com/google-cloud/vertex/decionis-vertex-marketplace-readiness.json |
| PSC consumer handoff | https://decionis.com/google-cloud/vertex/decionis-vertex-psc-consumer-handoff.json |
| Trace SRE runbook | https://decionis.com/google-cloud/vertex/decionis-vertex-trace-sre-runbook.json |
| Billing and Service Control readiness | https://decionis.com/google-cloud/vertex/decionis-vertex-billing-service-control-readiness.json |
| Go-live checklist | /docs/vertex-go-live |
Use these static artifacts when a partner needs an import-ready contract and a compact reference flow.
The callable API contract for the Vertex authority surface. Import it directly or mirror it into a Google-controlled artifact location.
https://decionis.com/openapi/decionis-vertex-extension-v1.yamlA metadata wrapper that lists the Vertex authority operations, required scopes, docs links, and downstream binding posture for partner review.
https://decionis.com/google-cloud/vertex/decionis-vertex-authority-tool-bundle.jsonA compact authorize, verify, override, and drift flow for a Gemini agent that needs Decionis authority before Salesforce mutation.
https://decionis.com/examples/decionis-vertex-reference-flow.jsonThe standalone Agent Card JSON for Cloud Storage upload and Producer Portal validation.
https://decionis.com/google-cloud/vertex/decionis-vertex-agent-card.jsonA partner-friendly profile for agent discovery catalogs that need to describe Decionis authority skills without moving policy logic into the agent layer.
https://decionis.com/google-cloud/vertex/decionis-vertex-a2a-discovery-profile.jsonA reference map for turning Google identity-token claims into Decionis actor and Google context fields at the adapter edge.
https://decionis.com/google-cloud/vertex/decionis-vertex-identity-claims-map.jsonA reviewer packet that separates shipped controls, optional enterprise hardening, and explicit non-claims for Google Cloud Marketplace review.
https://decionis.com/google-cloud/vertex/decionis-vertex-marketplace-readiness.jsonA private connectivity packet for consumer project allow-listing, endpoint creation, private-path validation, and rollback posture.
https://decionis.com/google-cloud/vertex/decionis-vertex-psc-consumer-handoff.jsonAn incident response packet for following one governed action across Google trace headers, Decionis logs, dossiers, metering, token checks, overrides, and drift.
https://decionis.com/google-cloud/vertex/decionis-vertex-trace-sre-runbook.jsonA marketplace billing packet for verified_decision usage, ledger-first reconciliation, optional Service Control export, and replay operations.
https://decionis.com/google-cloud/vertex/decionis-vertex-billing-service-control-readiness.jsonThese artifacts describe the interception and authority contract only. They do not ship policy thresholds, prompt rules, or client-side decision logic.
This route is the live Vertex adapter for governed verification requests.
/v1/google-cloud/vertex/extensions/verifyAPI keyNormalize agent intent and Google context, invoke Decionis Protocol, and return a governed verdict with Decision Dossier verification links.
| Field | Meaning |
|---|---|
| org_id | Target Decionis workspace UUID. |
| decision_type | Decision family the workflow should evaluate. |
| workflow_key | Optional workflow template key when a governed pack is already selected. |
| system_of_record | Downstream system the agent intends to mutate. |
| intent | Action metadata and payload proposed by the agent. |
| google_context | Optional agent, session, project, and principal metadata captured at the adapter edge. |
Use this route inside the downstream system before it mutates state.
/v1/google-cloud/vertex/authority/execution-tokens/verifyAPI keyVerify that a Decionis execution token is signed, unexpired, scoped to the org, and bound to the expected downstream target.
| Check | Meaning |
|---|---|
| Signature | The token was signed by Decionis using the configured authority secret. |
| Expiry | The token is still inside its short-lived execution window. |
| Org scope | The token belongs to the workspace supplied by the verifier. |
| Downstream target | The token target matches the system, operation, endpoint, and resource the downstream tool is about to mutate. |
| Binding source | Optional check that the token came from protocol authorization or human override approval. |
Salesforce, ServiceNow, SAP, or any write-capable tool should verify the token and require valid=true before mutation. A token mismatch is a stop signal, not a recoverable warning.
Use these routes when Decionis escalates or holds a Vertex action and the workflow needs a controlled human handoff.
/v1/google-cloud/vertex/authority/overridesAPI keyCreate an auditable override request tied to a Decision Dossier, Google context, evidence references, agent intent, and downstream target.
/v1/google-cloud/vertex/authority/overrides/:overrideId/reviewAPI keyReview the override. Approved reviews can issue a short-lived execution token bound to the override and downstream target.
| State | Downstream behavior |
|---|---|
| PENDING | Keep the downstream write paused. The override request is now part of the protocol audit trail. |
| APPROVED | If a downstream target is supplied, Decionis returns an override-bound execution token for that target. |
| REJECTED, ESCALATED, or CANCELLED | No execution token is issued. The downstream tool stops or routes to the next review path. |
The override route does not encode policy logic in Vertex. It records the human decision, ties it to the original Decision Dossier, and only binds execution after the protocol override is approved.
Keep identity and authorization explicit at the adapter edge.
| Header | Required | Meaning |
|---|---|---|
| Authorization | Yes | Bearer org API key with decision:write, decision:*, or org:* scope. |
| x-google-identity-token | Optional or required by deployment | Google identity token used for adapter-edge identity proof. Enable or require it with the GOOGLE_CLOUD_VERTEX_OIDC_* env settings. |
| Idempotency-Key | Optional | Safe replay protection for tool retries or repeated agent calls. |
| x-cloud-trace-context or traceparent | Optional | Forward Google Cloud Trace or W3C trace context so Decionis logs and metering records can correlate the adapter call with Cloud Logging and Monitoring. |
The adapter response always includes google_identity_verified, google_identity_mode, trace_correlation, regional_posture, metering, and metering_export so partner teams can see whether Google identity proof, trace stitching, locality checks, and Google-shaped usage export were active for the request.
Keep the import sequence simple and explicit for a first partner run.
# 1. Download the Decionis OpenAPI artifact
curl -O https://decionis.com/openapi/decionis-vertex-extension-v1.yaml
# 2. Register or mirror the spec in the Google Cloud environment your import flow expects
# Example: upload the file to your controlled GCS location if your process requires it.
# 3. Configure the extension/tool to call the public Decionis adapter route:
# https://api.decionis.com/v1/google-cloud/vertex/extensions/verify
# https://api.decionis.com/v1/google-cloud/vertex/authority/enforce-and-bind
# https://api.decionis.com/v1/google-cloud/vertex/authority/execution-tokens/verify
# https://api.decionis.com/v1/google-cloud/vertex/authority/overrides
# https://api.decionis.com/v1/google-cloud/vertex/authority/overrides/<override_id>/review
# 4. Supply a Decionis org API key
# Authorization: Bearer dcy_org_xxx
# 5. If your deployment enables Google adapter-edge verification, also send:
# x-google-identity-token: <google_oidc_token>
# 6. Use the response dossier links, google_identity flags, trace_correlation,
# regional_posture, metering, metering_export, and bound_execution fields
# to gate the downstream write actionUse this sequence when a partner is wiring the Vertex adapter into a real Google Cloud or Vertex AI workflow.
| Step | What to do | Expected result |
|---|---|---|
| 1. Issue org credentials | Create or reuse a Decionis org API key with decision:write, decision:*, or org:* scope for the target workspace. | The caller can authenticate to the Vertex adapter route. |
| 2. Import the OpenAPI spec | Import or mirror the Vertex OpenAPI artifact into the Google-controlled environment your Agent Engine or ADK flow expects. | Vertex treats Decionis as a tool surface, not as a second decision runtime. |
| 3. Point the tool to Decionis | Configure the tool or extension to call https://api.decionis.com/v1/google-cloud/vertex/extensions/verify for verification or https://api.decionis.com/v1/google-cloud/vertex/authority/enforce-and-bind before downstream mutations. | All agent verification and binding calls go through the Decionis adapter route. |
| 4. Forward Google context | Send google_context with project_id, location, agent identifiers, and service account or subject metadata when available. | Decionis can record traceable Google execution context around the decision. |
| 5. Enable edge identity verification | Set GOOGLE_CLOUD_VERTEX_OIDC_* env values if you want optional or required Google identity token validation at the adapter edge. | The response shows disabled, optional, or required identity mode plus whether verification succeeded. |
| 6. Set regional posture | Configure GOOGLE_CLOUD_VERTEX_ALLOWED_LOCATIONS, GOOGLE_CLOUD_VERTEX_LOCATION_REQUIRED, and GOOGLE_CLOUD_VERTEX_SERVING_REGION when locality matters. | The response includes regional_posture and can reject disallowed or missing locations. |
| 7. Wire execution gating | Make the downstream action proceed only when execution_guidance.allowed is true and, for bound execution, a valid Decionis execution_token is present for the requested downstream target. | Vertex provides intelligence, Decionis provides authority, and the downstream system executes only when authority is proven. |
| 8. Keep proof and metering | Store dossier identifiers, verification URLs, trace_correlation, metering, and metering_export with the downstream execution record. | Every governed action keeps proof, traceability, and usage context together. |
| 9. Verify downstream tokens | Before Salesforce, ServiceNow, SAP, or another write-capable tool mutates state, call the execution token verification route with the expected downstream target. | The downstream tool executes only when Decionis returns valid=true for that exact target. |
| 10. Wire override review | When a decision escalates or holds, create a Vertex authority override request and review it through the override review route. | Approved human overrides can return an override-bound execution token; other outcomes return no token. |
These are the main runtime controls for the live adapter posture.
GOOGLE_CLOUD_VERTEX_OIDC_AUDIENCES=
GOOGLE_CLOUD_VERTEX_OIDC_ISSUERS=
GOOGLE_CLOUD_VERTEX_OIDC_HEADER_NAME=x-google-identity-token
GOOGLE_CLOUD_VERTEX_ALLOWED_LOCATIONS=
GOOGLE_CLOUD_VERTEX_LOCATION_REQUIRED=0
GOOGLE_CLOUD_VERTEX_SERVING_REGION=
GOOGLE_CLOUD_VERTEX_SERVICE_CONTROL_ENABLED=0
GOOGLE_CLOUD_VERTEX_SERVICE_CONTROL_SERVICE_NAME=
GOOGLE_CLOUD_VERTEX_SERVICE_CONTROL_METRIC_NAME=decionis.googleapis.com/verified_decision
GOOGLE_CLOUD_VERTEX_SERVICE_CONTROL_OPERATION_NAME=decionis.vertex.extensions.verifyDo not move policy logic, approval logic, or dossier issuance into Vertex. The extension stays thin by design: it gathers context, calls Decionis, and returns one governed result that downstream systems can trust.
This is the smallest useful request body for a first Vertex AI validation.
curl -X POST https://api.decionis.com/v1/google-cloud/vertex/extensions/verify \
-H "Authorization: Bearer dcy_org_xxx" \
-H "x-google-identity-token: <google_oidc_token>" \
-H "x-cloud-trace-context: 105445aa7843bc8bf206b12000100000/12345;o=1" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: vertex-verify-1" \
-d '{
"org_id": "c65f0510-bb59-48c7-9a73-f3b12338dfaa",
"decision_type": "TRANSACTION_ROUTING",
"workflow_key": "finance_transaction_routing",
"vertical_pack": "finance_transaction_routing",
"policy_version": "finance-routing-v2",
"system_of_record": "SAP",
"amount": 12500,
"risk_score": 0.18,
"intent": {
"action_type": "CREATE_VENDOR_PAYMENT",
"target_entity": "invoice",
"target_id": "INV-2048",
"payload": {
"invoice_id": "INV-2048",
"currency": "EUR"
}
},
"context": {
"region": "europe-west1",
"business_unit": "procurement"
},
"google_context": {
"agent_id": "vertex-agent-1",
"agent_session_id": "session-42",
"tool_call_id": "tool-call-7",
"project_id": "decionis-labs",
"location": "europe-west1",
"service_account_email": "vertex-agent@decionis-labs.iam.gserviceaccount.com"
}
}'A successful response returns the governed status, the underlying Protocol outcome, the current policy version, the dossier identifiers, public verification URLs, Google identity verification state, normalized trace_correlation, regional posture, the verified_decision metering envelope, optional Service Control export status, and execution guidance such as EXECUTE, ESCALATE, BLOCK, or HOLD.
curl -X POST https://api.decionis.com/v1/google-cloud/vertex/authority/enforce-and-bind \
-H "Authorization: Bearer dcy_org_xxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: vertex-refund-bind-1" \
-d '{
"org_id": "c65f0510-bb59-48c7-9a73-f3b12338dfaa",
"decision_type": "REFUND_APPROVAL",
"workflow_key": "customer_refund_agent",
"policy_version": "refund-authority-v1",
"system_of_record": "Salesforce",
"amount": 275,
"intent": {
"action_type": "CREATE_REFUND",
"target_entity": "case",
"target_id": "500xx000001"
},
"google_context": {
"agent_id": "gemini-agent-1",
"agent_session_id": "session-refund-1",
"tool_call_id": "tool-call-refund-1",
"project_id": "decionis-labs",
"location": "us-central1"
},
"downstream_target": {
"system": "Salesforce",
"operation": "CREATE_REFUND",
"endpoint": "/services/data/v61.0/sobjects/Refund__c",
"resource_type": "case",
"resource_id": "500xx000001",
"required_decision_binding": true
},
"binding_ttl_seconds": 120
}'curl -X POST https://api.decionis.com/v1/google-cloud/vertex/authority/execution-tokens/verify \
-H "Authorization: Bearer dcy_org_xxx" \
-H "Content-Type: application/json" \
-d '{
"org_id": "c65f0510-bb59-48c7-9a73-f3b12338dfaa",
"execution_token": "<execution_token_from_decionis>",
"required_binding_source": "protocol_authorization",
"downstream_target": {
"system": "Salesforce",
"operation": "CREATE_REFUND",
"endpoint": "/services/data/v61.0/sobjects/Refund__c",
"resource_type": "case",
"resource_id": "500xx000001",
"required_decision_binding": true
}
}'curl -X POST https://api.decionis.com/v1/google-cloud/vertex/authority/overrides \
-H "Authorization: Bearer dcy_org_xxx" \
-H "Content-Type: application/json" \
-d '{
"org_id": "c65f0510-bb59-48c7-9a73-f3b12338dfaa",
"dossier_id": "3fbf8ef1-d83f-454e-b5eb-f820fd1114ff",
"reason_code": "CUSTOMER_RETENTION_APPROVAL",
"override_note": "Supervisor review requested from Vertex refund workflow.",
"evidence_refs": ["gs://evidence/refund-case-500xx000001.json"],
"google_context": {
"agent_id": "gemini-agent-1",
"agent_session_id": "session-refund-1",
"tool_call_id": "tool-call-refund-1",
"project_id": "decionis-labs"
},
"intent": {
"action_type": "CREATE_REFUND",
"target_entity": "case",
"target_id": "500xx000001"
},
"downstream_target": {
"system": "Salesforce",
"operation": "CREATE_REFUND",
"resource_type": "case",
"resource_id": "500xx000001"
}
}'
curl -X POST https://api.decionis.com/v1/google-cloud/vertex/authority/overrides/<override_id>/review \
-H "Authorization: Bearer dcy_org_xxx" \
-H "Content-Type: application/json" \
-d '{
"org_id": "c65f0510-bb59-48c7-9a73-f3b12338dfaa",
"review_outcome": "APPROVE",
"review_note": "Approved for customer retention.",
"downstream_target": {
"system": "Salesforce",
"operation": "CREATE_REFUND",
"resource_type": "case",
"resource_id": "500xx000001"
},
"binding_ttl_seconds": 180
}'Use this checklist to prove the Vertex integration is working end to end after deployment.
| Check | How to validate | Success signal |
|---|---|---|
| Adapter call | Send a direct POST to /v1/google-cloud/vertex/extensions/verify before validating through Vertex itself. | HTTP 200 with status, outcome, policy_version, verification, trace_correlation, regional_posture, metering, and metering_export in the response. |
| Decision authority | Inspect the response and downstream behavior. | The downstream tool acts on execution_guidance, and the decision is backed by a Decionis dossier rather than a model-only judgment. |
| Bound execution | Call /v1/google-cloud/vertex/authority/enforce-and-bind for a downstream write target. | AUTHORIZED responses include bound_execution.issued=true and a signed execution_token. ESCALATED, BLOCKED, or HOLD responses include no token. |
| Token verification | Call /v1/google-cloud/vertex/authority/execution-tokens/verify from the downstream system with the expected target. | Valid tokens return valid=true. Wrong org, expired token, wrong binding source, or target mismatch returns valid=false with a reason code. |
| Override review | Create a Vertex authority override for an escalated or held dossier, then review it. | Approved reviews with a downstream target include override_execution.issued=true and an execution token with binding_source=human_override. |
| Decision Dossier proof | Open verification.verification_url or verification.verification_page_url from the response. | A real public verification page or API response resolves for the returned dossier. |
| Idempotency | Repeat the same request with the same Idempotency-Key. | The response stays stable and the replay path does not create a new uncontrolled action. |
| Google identity verification | When OIDC is enabled, call once with a valid token and once with a missing or invalid token. | Valid calls return google_identity_verified=true. Invalid or missing required tokens return 401. |
| Regional posture | Call once with an allowed google_context.location and once with a disallowed location when the allowlist is active. | Allowed locations return location_accepted=true. Disallowed or missing required locations return 400. |
| Metering ledger | List metering records through the org-scoped operator route after a successful verification. | A verified_decision event exists for the adapter call. |
| Service Control export | When enabled, inspect metering_export in the response and the recorded metering event. | metering_export.status is reported, or failed states are replayable without rerunning the business decision. |
| Google-native observability | Inspect Cloud Logging / Monitoring resources after live traffic reaches the adapter. | The Vertex log metrics, dashboard, and alert policies exist and begin receiving data. |
These response fields should be present on a healthy adapter call.
status
outcome
policy_version
verification
google_identity_verified
google_identity_mode
trace_correlation
regional_posture
metering
metering_export
execution_guidance
bound_execution
execution_tokenUse these routes after the first successful call to validate usage export and replay behavior.
GET https://api.decionis.com/v1/orgs/<org_id>/google-cloud/vertex/metering
POST https://api.decionis.com/v1/orgs/<org_id>/google-cloud/vertex/metering/<event_id>/replay-service-controlValidate the adapter directly first, then import the tool into Vertex, then verify Google identity and regional controls, and only after that validate Service Control export and Google-native dashboards. That order keeps control-plane failures separate from marketplace or enterprise hardening concerns.
When the adapter is already passing verification, use the dedicated go-live page for launch readiness, rollback posture, and Google-native validation steps.
/docs/vertex-go-liveWhat is already implemented versus what remains enterprise hardening.
| Area | Status | Current posture |
|---|---|---|
| Google OIDC / WIF bridge | Available now | The adapter can validate a Google identity token from x-google-identity-token, enforce audiences, and mark the response as disabled, optional, or required. |
| Cloud Logging / Monitoring-friendly telemetry | Available now | Structured request logs include Google project, location, service account or subject, policy version, verdict, trace correlation, and metering labels so Google-native observability can ingest them cleanly. |
| Alerting baseline | Available now | Terraform can provision Monitoring alert policies for identity or location failures and sustained blocked or hold decision surges so the raw metrics turn into operational response. |
| Regional posture | Available now | The adapter can require or allowlist google_context.location and returns regional_posture in the response so partner systems can verify the serving region and whether the requested location was accepted. |
| Commercial metering seed | Available now | Each adapter response includes metering.unit=verified_decision and metering.count=1, and Decionis persists the event into a metering ledger for downstream billing or service-control reporting. |
| Bound execution tokens | Available now | The authority route issues a short-lived signed execution token only for authorized decisions, and the verification route lets downstream systems prove the token before mutation. |
| Google Service Control usage export | Available now | The adapter can export the verified_decision unit to Service Control with ADC / Workload Identity while keeping the Decionis metering ledger as the reconciliation source of truth. |
| Marketplace billing readiness | Available now | The public billing readiness packet documents the verified_decision billing unit, ledger-first reconciliation, Service Control replay, and non-goals for marketplace review. |
| Private Service Connect producer path | Available now | The GKE deployment now supports an opt-in PSC producer path with an internal API service, dedicated PSC NAT subnet, and a GKE ServiceAttachment manifest. Consumer project approval and endpoint wiring remain the next enterprise networking increment. |
| Regional endpoints and CMEK | Partially available | Regional posture is live in the adapter, and Terraform can now provision KMS keys for Artifact Registry and GKE node boot disks. Broader per-service CMEK guarantees still remain deployment-specific hardening rather than a blanket product claim. |
These org-scoped routes help operators inspect and replay Google-native usage export without changing the governed decision contract.
/v1/orgs/:orgId/google-cloud/vertex/meteringAPI keyList recent Vertex metering events and Service Control export posture for an org.
/v1/orgs/:orgId/google-cloud/vertex/metering/:eventId/replay-service-controlAPI keyReplay Service Control export for a recorded Vertex metering event without rerunning the business decision.
/v1/google-cloud/vertex/authority/drift/eventsAPI keySubmit override, downstream refusal, or model-intent drift signals for Decision Dossier and Protocol correlation.
/v1/google-cloud/vertex/authority/execution-tokens/verifyAPI keyVerify that a bound execution token is valid for an exact downstream target before mutation.
/v1/google-cloud/vertex/authority/overridesAPI keyRequest a controlled human override for a Vertex authority decision.
/v1/google-cloud/vertex/authority/overrides/:overrideId/reviewAPI keyReview a Vertex authority override and optionally issue an override-bound execution token.
The governed decision should not fail just because Google-native billing or reporting had a transient problem. Replay lets operators re-export usage from the Decionis metering ledger after fixing service name, IAM, or consumer project configuration.
These are the remaining enterprise follow-ons after the current adapter path is working.
| Next step | Why it matters |
|---|---|
| CMEK-backed deployment posture | Extends the shipped KMS baseline beyond Artifact Registry and GKE boot disks when a customer deployment requires broader data-at-rest coverage. |
| Marketplace submission polish | Package customer-specific pricing copy, screenshots, contract language, and enterprise readiness evidence around the shipped runtime and review packets. |