AI Agent Tool Calling Security: Build a Safe Action Gateway

An AI avatar should never receive broad access to enterprise systems simply because it can understand a request. Put a governed action gateway between the conversational model and every operational API. The model may propose a typed action; deterministic software must authenticate the actor, validate the parameters, apply policy, obtain any required approval, execute with minimum privilege and return an auditable receipt.

This boundary matters when an avatar moves from answering “When is my flight?” to changing a booking, from explaining a bank product to initiating a transfer, or from describing a government service to submitting an application. A natural conversation can be probabilistic. A consequential action cannot be.

Tool calling is not the same as API access

In tool calling, a language model produces a structured proposal such as check_booking(reference) or prepare_address_change(customer_id, new_address). Application code decides whether that proposal corresponds to an approved function and whether to run it. The model should not hold unrestricted API credentials, construct arbitrary URLs or send free-form commands to production systems.

This is also different from retrieval-augmented generation. RAG retrieves authorised information so that an avatar can produce a grounded answer. A tool can create, update, submit, cancel or pay. The permission-aware RAG architecture for private avatars is therefore one input to an action system, not its authorisation layer.

The distinction is practical. A retrieved document may contain an instruction that was never meant for the model. A user may phrase an ambiguous request. A model may infer the wrong parameter. None of those events should be sufficient to bypass a downstream control.

Classify actions before designing tools

Create an action catalogue and assign every proposed tool to one of four classes:

1. Read: retrieve a balance, status, timetable or approved record without changing it.
2. Prepare: calculate a quote, populate a form or assemble a request that has not yet been committed.
3. Commit: change an address, create a case, submit an application or confirm a booking.
4. Restricted: move money, disclose specially protected data, make an eligibility or clinical decision, delete a record or perform another high-consequence operation.

Do not assume that “read” means harmless. A read tool can expose another person's data, reveal a security answer or enumerate records. Risk depends on the data, the actor and the context as well as the HTTP verb.

For each action, record the business owner, permitted users, required identity assurance, data fields, downstream system, maximum scope, confirmation rule, rate limit, audit record, recovery method and whether a human must complete it. If the organisation cannot complete this row, the tool is not ready for production.

Build a seven-gate action path

1. A narrow tool registry

Expose only specific business capabilities. Prefer get_case_status over query_database, and prepare_appointment_request over call_http_endpoint. Each tool needs an owner, version, structured input schema, output schema, action class and retirement date.

The OWASP guidance on excessive agency identifies excessive functionality, permissions and autonomy as root causes of damaging agent actions. It recommends minimising tools and permissions, avoiding open-ended extensions, executing in the user's context and requiring approval for high-impact actions.

2. Schema validation and normalisation

Treat model output as untrusted input. Reject missing, extra, malformed and out-of-range fields. Resolve dates, currencies, account identifiers and locale-specific formats in deterministic code. Never allow a model-generated string to become a database query, shell command or destination URL without a purpose-built parser and allow-list.

Document the gateway and its downstream contracts. The UK National Cyber Security Centre's guidance for securing HTTP APIs recommends threat modelling, comprehensive endpoint documentation, standard specifications such as OpenAPI, version management and negative as well as positive testing.

3. Identity binding

Bind the proposed action to the authenticated user, the avatar session and the calling workload. These are three identities, not one. The browser token should not simply be handed to the model, and a shared service account should not silently turn every visitor into an administrator.

The AI avatar SSO reference architecture explains how to keep user, workload and session identity separate. Where the existing identity platform supports it, a gateway can exchange a user-facing token for a short-lived, audience-restricted downstream token. OAuth 2.0 Token Exchange defines a standard protocol for impersonation and delegation, but the exact trust model and policy remain deployment decisions.

4. Deterministic policy

Policy must sit outside the language model. Evaluate role, customer relationship, jurisdiction, channel, device, transaction limit, time, risk signals and action class using normal authorisation controls. Deny by default. A persuasive explanation from the model is not evidence that an exception should be granted.

Re-check policy at execution time. An approval or account state can change between the start of a conversation and the final request. The downstream system should also enforce its own permissions; the gateway is not a reason to remove existing controls.

5. Approval and exact confirmation

For a consequential action, generate the confirmation summary from validated parameters—not from the model's prose. Show or speak the exact beneficiary, amount, record, effective date and consequence. Give the user a clear opportunity to correct or cancel it. Step up authentication when policy requires stronger evidence.

Voice confirmation alone may be unsuitable in noisy public spaces or for high-risk tasks. Offer an authenticated screen, mobile approval, staff hand-off or another accessible channel. The existing banking transaction-boundary framework shows how informational assistance, preparation and execution can be deliberately separated.

6. Controlled execution

Use a connector with the minimum scopes needed for that single tool. Apply timeouts, rate limits, destination allow-lists and payload limits. For commit operations, create an idempotency key so a retry cannot repeat a transfer, booking or submission. Record a correlation identifier that follows the request through the gateway and downstream service.

Do not tell the user an action succeeded because the model expected it to succeed. The avatar should confirm completion only after the authoritative system returns a verified result. “I have prepared your request” and “your request was submitted” are different states.

7. Receipt, audit and recovery

Return a structured receipt containing the action, actor, policy decision, approval evidence, tool and schema version, timestamps, downstream reference and outcome. Avoid logging raw conversation content or credentials by default. Security teams need enough evidence to reconstruct a decision without creating a second store of sensitive customer data.

Design partial failure explicitly. If one step succeeds and the next fails, either compensate safely, place the case into a known review queue or tell the user what did and did not happen. A model should not invent a rollback. The local-first observability model can monitor these state transitions without exporting conversation content.

Keep prompts and business data away from credentials

A user utterance, retrieved document or tool response can contain hostile instructions. Separate data from control: tool descriptions come from a signed, versioned registry; credentials live in a managed secret or identity service; and only the gateway can invoke connectors. The model receives the minimum result required for the next conversational turn.

Filter tool outputs as carefully as inputs. A CRM note or web result can contain text that tries to influence the next action. Mark the source, constrain the fields returned and do not automatically make new tools available because a tool response mentions them.

Where the gateway belongs in a private deployment

For an on-premise or sovereign implementation, the action gateway, policy engine, credentials, tool registry and audit records can be placed inside the customer's environment. Speech recognition, the language model and avatar rendering may also run there when the scoped architecture and available GPUs support it. External calls then become named exceptions rather than hidden dependencies.

That does not mean every deployment should be fully customer-hosted. A public-cloud avatar may be appropriate for low-risk public information, while the action gateway and systems of record remain private. A private-cloud pattern can simplify elastic media and model capacity. The important control is the explicit boundary: which content reaches the conversational service, which tool calls cross it, where identity is resolved and where the final action is authorised.

Local hosting does not make a tool safe. It can improve data control and reduce third-party paths, but excessive permissions, ambiguous actions and weak recovery remain dangerous inside a data centre.

What enterprise integration evidence should prove

Yepic's Abu Dhabi Aviation and Oracle enterprise-avatar project demonstrates the less glamorous work that real integration requires: separate development and production environments, API and iframe integration, permission-aware queries, browser and WebRTC testing, captions, microphone behaviour, cybersecurity support and ongoing maintenance.

That project is relevant evidence for enterprise integration, not a claim that Yepic has already deployed this exact autonomous action-gateway pattern on customer-hosted infrastructure. Yepic can scope cloud, private-cloud and customer-hosted avatar architectures, including deployment on customer GPUs, as a custom implementation. The tool catalogue, identity model, downstream permissions and approval rules must still be designed for the buyer's systems and risks.

Twelve production acceptance tests

1. Ask for an action that is not in the registry and confirm a hard denial.
2. Inject extra fields, malformed identifiers and out-of-range values.
3. Attempt to act on another user's account or case.
4. Place hostile instructions in a retrieved document and tool response.
5. Replay a previous confirmation after identity, policy or data changes.
6. Interrupt the avatar between preparation and commitment.
7. Retry a commit after a timeout and prove idempotent behaviour.
8. Return success from the gateway while the downstream service rejects the action.
9. Fail the second step of a multi-system workflow and verify recovery.
10. Rotate or revoke a connector credential during an active session.
11. Prove that logs reconstruct the decision without storing secrets or unnecessary speech.
12. Disable a tool version and confirm it cannot be called by an old prompt or session.

The NIST Generative AI Profile treats risk management as a lifecycle activity aligned to the organisation's context and tolerance. For an action-enabled avatar, that means testing the entire chain—from speech and intent to policy, execution, receipt and recovery—not merely the model's ability to select a function.

Start with one reversible action

A sensible pilot begins with a narrow, reversible action whose authoritative result is easy to verify. Build the registry and seven gates around it, run the negative tests, and measure denials, approval abandonment, downstream errors, duplicate prevention and human hand-offs. Add another tool only when its permissions, failure modes and owner are equally clear.

The result is not an avatar with unlimited agency. It is a useful conversational interface whose ability to act is deliberately smaller, more observable and more accountable than the systems behind it.