Agent Security Strategy | Alephant Documentation

AIvis Agents are designed for enterprise environments where users may ask an Agent to search private knowledge, reason over sensitive context, and call approved tools. The security strategy is to keep Agents powerful without letting them bypass product authorization, tenant boundaries, credential handling, or audit policy.

AIvis Agent Privacy-Preserving Security Architecture

The diagram shows the key security boundaries for Agent execution: user requests enter the trusted AIvis API boundary, are bound to authenticated identity, workspace, Agent configuration, and request ID, and only minimum required context is passed to runtime services. Knowledge retrieval, tool calls, and model calls each pass through their own controls; usage and audit telemetry stores facts without copying full prompts, model responses, reasoning traces, raw tool parameters, or secrets.

Security objectives

Objective	AIvis strategy
Prevent confidential data leakage	Agents receive only scoped context and approved tools. Prompts cannot expand document, connector, workspace, or tool access.
Keep execution attributable	Agent runs, tool calls, and usage records are tied to trusted server-side user, workspace, Agent, and request context.
Minimize stored sensitive content	Operational telemetry should store usage facts and identifiers, not full prompts, responses, reasoning traces, or tool parameters.
Fail closed on ambiguity	Missing, stale, forged, expired, deleted, or ambiguous runtime identity should deny access instead of falling back to a previous user or broad service account.
Separate credentials from prompts	Model, connector, and tool credentials stay in managed configuration and are never treated as prompt text.

Agent authority model

An Agent is not an administrator, a database client, or a connector credential owner. It is an execution plan produced from a user request, Agent configuration, retrieved context, and allowed tools.

AIvis should enforce authorization in services that own the resource:

Knowledge retrieval is scoped by workspace, connector, document visibility, document sets, groups, and source-system mappings.
Tool calls are checked against the active user, workspace, Agent configuration, deployment policy, and tool allowlist.
Model access is controlled by administrator-managed provider configuration and model availability.
State-changing actions are authorized server-side before execution.
User prompts and Agent instructions cannot grant new tools, broaden document scope, impersonate another user, or override tenant boundaries.

Confidential information boundaries

Boundary	Protected behavior
Prompt and response content	Do not use chat content as an authorization source. Avoid storing full prompt, response, reasoning, or tool-argument payloads in operational telemetry.
Retrieved knowledge	Return only chunks that pass retrieval-time authorization for the current user, workspace, Agent, and document scope.
Tool parameters	Validate against schemas and policy before execution. Avoid logging raw parameters when they may contain customer data, secrets, or record identifiers.
Credentials	Store secrets in managed configuration. Do not paste credentials into Agent instructions, examples, OpenAPI descriptions, or MCP server metadata.
Error output	Return bounded user-facing errors. Do not expose stack traces, local paths, internal hostnames, raw secret values, or unrestricted logs.

Trusted identity path

Agent execution should rely on identity supplied by trusted AIvis services, not by browser-controlled headers or user-provided parameters. A secure deployment should:

Establish the authenticated user and workspace at the API boundary.
Bind the Agent run to a server-side request ID, conversation ID, Agent ID, and workspace ID.
Pass only the minimum required execution context to runtime services.
Strip or ignore user-forged identity headers.
Verify runtime source identity through deployment-controlled service registration or network metadata.
Deny the run or tool call when identity mapping is missing, stale, expired, deleted, duplicated, or otherwise ambiguous.

This prevents an Agent task from inheriting a previous user’s context, impersonating another workspace, or being attributed to a broad shared service identity.

Tool and action controls

Agents should only call tools that have been deliberately enabled. Before a tool is made available to an Agent, review:

Review item	Why it matters
Owner and purpose	Every tool needs a business owner and a clear allowed use case.
Input schema	Strong schemas reduce prompt-driven parameter injection and accidental overreach.
Permission check	The service that owns the resource must validate the active user, workspace, Agent, and policy.
Credential scope	Use least-privilege credentials. Prefer read-only credentials unless writes are required.
Side effects	Mark tools that send messages, create records, update systems, or trigger payments as high impact.
Audit record	Store enough metadata to investigate who initiated the action, when it ran, what tool was called, and whether it succeeded.

High-impact tools should be rolled out with a small allowlist first, tested with both allowed and denied paths, and reviewed after production use.

Telemetry without content capture

Enterprise administrators often need usage and cost visibility, but that should not require copying sensitive prompts or responses into analytics tables. AIvis telemetry should prefer lightweight facts:

Request or span identifier.
Timestamp and execution path.
User, workspace, Agent, and persona identifiers or snapshots.
Model and provider identifiers.
Token counts, duration, status, and cost snapshots.
Tool name and outcome when needed for audit, without raw secret values or full customer payloads.

Avoid storing:

Full prompts.
Full model responses.
Reasoning traces.
Raw tool parameters.
Connector credential values.
Access tokens or API keys.

If a user is deleted, historical aggregate usage can remain for operational accounting, but user-facing reports should not reveal personal data that has been removed from the identity system.

Fail-closed examples

Scenario	Expected behavior
A request lacks authenticated user context.	Deny Agent execution or tool attribution.
A browser supplies runtime identity headers.	Ignore or strip them; use only trusted server-side context.
Runtime source identity cannot be verified.	Deny the run instead of using a shared default identity.
Multiple runtime mappings match one source.	Deny until the ambiguity is resolved.
A tool references another tenant or workspace.	Deny at the service that owns the target resource.
A user asks the Agent to reveal connector credentials.	Do not expose managed secrets; return a bounded refusal or error.
A connector permission sync is incomplete.	Do not assume broad access; restrict retrieval until permissions are verified.

Enterprise rollout checklist

Assign an owner to every production Agent.
Document each Agent’s allowed knowledge, models, tools, and side effects.
Confirm that prompts cannot add tools or override document permissions.
Test denied retrieval for at least one document outside the user’s scope.
Test denied tool execution for a user who lacks permission.
Verify that Agent telemetry excludes full prompts, responses, reasoning traces, and raw tool parameters.
Verify that logs are searchable by request ID without exposing secrets.
Review high-impact tools before enabling them for broad user groups.
Confirm retention, backup, and deletion behavior with the organization’s data policy.