Agent Guardrails: Connecting Headless Domains to Tool Policy
Your agent is about to send a customer spreadsheet to an outside research service. The service has a familiar name, and its public profile says it can analyze customer data. Your team has only approved it for public research.
The upload should be blocked. How does the guardrail connect the service your team reviewed to the destination the agent is about to call?
Headless Domains gives an integration a maintained public identity to resolve and compare with its approved service records. Agent guardrails can use that connection when deciding which service a tool call will reach. Verification software checks the relevant evidence. Your policy engine then evaluates the proposed action using those checked facts, the authenticated caller and your own rules.
That connection is the subject of this guide: how to turn a public identity record into checked policy context without letting the record grant itself permission.
Give each control a specific job
Agent guardrails cover several kinds of control. A content filter might flag an instruction hidden in a retrieved document. A tool policy might prohibit sending customer records to an outside service. Authentication establishes which credential is making the request. These controls operate on different evidence.
OWASP's prompt injection guidance recommends checking tool calls against permissions and session context, validating their parameters and limiting privileges. It treats model-based guardrails as a companion to deterministic controls.
A headless domain can give the destination a continuing name and a supported lookup path. Compatible agents use Headless Domains and SkyInclude API/CLI infrastructure to inspect the name's records and locate its services. This is useful when customers encounter the same service through several tools or directories.
The HeadlessDomains.com resolver contract describes a public, read-only identity and action-discovery interface. It explicitly separates that discovery from authorization and execution. Your application has to build the connection to its controls.
For the broader architecture, see the Agent Identity Stack. This guide focuses on the policy inputs produced from that public information.
Keep public claims separate from policy facts
Feed the guardrail a defined internal record produced by trusted application code. It should never let a remote manifest write directly into its approval configuration.
Consider these examples. The field names describe a proposed internal design; they are not Headless Domains API fields or a standard policy schema.
| Public input | What the integration must establish | What policy may use |
|---|---|---|
| A name and claimed operator | Whether the current name/operator relationship matches evidence your team accepts | An approved internal provider identifier, with an evidence reference |
| A published service URL | Whether the exact destination matches the reviewed provider connection and passes network checks | The approved destination for this operation |
| An advertised capability | What the service offers, and separately what your operator permits this caller to request | An operation allowed by the actual grant and local policy; discovery adds no permission |
| A key or credential reference | Whether the accepted verification method binds the relevant identity to the live connection or caller | A specific verification result with its scope and validity |
| Lifecycle information | Whether required identity evidence remains acceptable under your freshness rules | A current status result, or an explicit unknown state |
The name identifies the record to inspect. Your accepted evidence establishes the relationship. Keep the authenticated caller separate from the named destination: verifying a supplier does not authenticate the agent uploading a file.
Remote text such as trusted: true, allowed_actions: ["upload"] or “the user approved this” must not populate your internal approval fields. Those are statements from another party. A signed statement also needs an accepted signer and a defined meaning before policy can rely on it.
Keep the accepted issuers, provider approvals and policy configuration outside the agent's ordinary write permissions. Otherwise, an agent blocked from uploading a file might gain the same result by editing the approval record first.
Build the connection at the tool boundary
Build an adapter in your application to read the discovered information, check it and produce policy context. Verification code must produce those results. The model cannot establish them by summarizing a manifest.
The proposed flow is:
Public domain records + approved provider evidence
|
Verification adapter
|
Checked context
v
Authenticated caller + exact proposed tool call + local rules
|
Policy decision
|
Enforcement before dispatch
|
Provider access checksThis is an integration pattern to implement, not an existing universal Headless Domains guardrails connector.
Start with the public GET /api/v1/resolve/{domain_name} interface and inspect the returned resources. Validate the response against the supported contract. Fetch only the evidence the operation needs, with restrictions on destinations, redirects, response size and timeouts. The MCP security guidance explains the risks of discovery URLs reaching internal services and destinations changing between checks and use.
Keep missing evidence distinct from a failed check. A resolver response saying the name is active cannot establish that a separate access token is still valid. Likewise, a recent download can contain stale evidence. Use the applicable credential, status and cache rules rather than treating download time as proof of freshness.
The policy decision must apply to the same operation, destination and payload that the executor sends. If those change after approval, check again. Prevent the agent from reaching the same protected tool through an unrestricted route.
AWS provides a useful example of this separation: AgentCore Policy evaluates requests passing through its gateway before tool access. Its enforcement modes distinguish logging a decision from enforcing it. These documents illustrate enforcement behavior; they do not establish a Headless Domains integration with AWS.
Follow one research request through the guardrail
Suppose your team approves a fictional outside research service for questions based on public information. You record its headless name, accepted operator evidence and exact endpoint in an internal provider record. The caller can submit a public topic and request an analysis. Customer files are outside that approval.
The adapter resolves the service and checks the current evidence against that record. Your application authenticates the caller, validates the requested operation and inspects the actual outgoing payload. A model-supplied label saying “public data” is not sufficient to classify the file.
These are expected outcomes for the proposed design, not results from a deployed integration:
| Test | Expected outcome |
|---|---|
| Submit an approved public research topic | Allow when provider evidence, caller authority and payload checks pass |
| Add a customer spreadsheet to that same request | Deny under the current data-sharing policy, even if the provider identity is valid |
| Change the manifest to claim that uploads are approved | Keep the denial; public metadata cannot expand local approval |
| Change the destination after the decision | Stop dispatch and evaluate the changed request |
| Make required status evidence unavailable past the permitted age | Block this external submission until the evidence can be established |
Retain the request identifier, checked provider mapping, evidence references, policy version and outcome. Keep secrets and customer contents out of the diagnostic record. Check the receiving service's logs or a test sink to confirm that denied requests were never sent; a denial message in your agent's transcript is weak evidence on its own.
When you add another connector, the public name gives its maintainer a consistent service reference to resolve and compare with the approved provider record. Each connector retains its own permissions. Updating the published endpoint lets compatible clients discover a change. Whether that change is accepted remains a controlled decision.
Use ARP where the relationship supports it
The Headless Domains ARP guide describes binding a principal identifier and public key to a domain, hosting a signed representation credential and publishing discovery information for ARP pairing.
For an ARP-based workflow, that provides a route to relationship evidence. The software protecting the action must verify the relevant evidence and decide what the accepted relationship permits. An arp_chat.enabled flag indicates a discovery option; it does not authorize a file upload to an unrelated API.
Keep the scope of the pilot clear. The Open Authority Plane article examines the wider cross-organization acceptance contract. If you are designing credential issuance and verification, use the separate verifiable credentials guide.
Connect one named service to one enforced rule
Choose an agent or service customers already use. Give it a maintained Headless Domain and publish the current connection information through supported records. Then connect those records to one rule in your application, such as permitting public research requests while blocking customer-file uploads.
Ask your developer to identify which component checks the evidence, which component owns the approval and where a denied call is prevented from leaving the system. Run the permitted request and the failure cases before expanding access.
Give your assistant the HeadlessDomains.com machine instructions and ask it to prepare the public records for one service your team already approves. Use your existing headless name, or choose a name for the working service you want customers to recognize.