Agent Runtime Architecture | Alephant Documentation

AIvis agents can use model output, knowledge retrieval, and approved actions. The runtime boundary is designed so that agent execution does not become an independent authority over users, documents, credentials, or tools.

This diagram shows the secure interactions among the browser, AIvis control plane, Agent runtime, Tool Gateway, knowledge retrieval, model providers, and external applications. The core posture is that runtime services receive minimum context and credential references, while data access, tool calls, credential injection, and high-impact action approval remain controlled by AIvis services.

For the enterprise policy view, see Agent Security Strategy.

Runtime trust boundary

Boundary	Security behavior
Browser to AIvis API	Browser sessions authenticate to AIvis Web and API. Runtime services are not a browser-facing interface.
AIvis API to Agent Runtime	AIvis API sends only the execution context needed for an approved run.
Agent Runtime to Tool Bridge	Tool calls go through an authorized bridge instead of direct database or connector access.
Tool Bridge to AIvis services	AIvis services enforce tool availability, user context, workspace context, and policy.

Runtime inputs

An Agent run can include:

The active user and workspace context.
The selected Agent and its configured instructions.
The allowed model and generation settings.
Retrieved knowledge chunks already scoped by AIvis.
Tool definitions that are enabled for the Agent.
Run metadata such as request ID, conversation ID, and trace context.

The runtime should treat these values as execution inputs, not as global authority. Any action that reads data, writes state, calls an integration, or reaches a connector should still pass through service-side authorization.

Tool access

Agent tools should be treated as deployment capabilities, not prompt instructions. Administrators decide which actions, connectors, and integrations are enabled. At runtime, AIvis should pass tool calls through authorization checks tied to the active user, workspace, agent, and configured tool set.

Control	Required behavior
Tool inventory	Each tool should have an owner, purpose, input schema, output expectation, and availability scope.
Tool allowlist	Agents should receive only the tools they are allowed to call.
Argument validation	Tool inputs should be validated before execution.
Permission check	A tool call should be denied when the user, Agent, workspace, or deployment policy does not allow it.
Result handling	Tool results should be returned with enough context for audit without exposing secrets or raw infrastructure details.

Credential handling

Model credentials, connector credentials, API tokens, and integration secrets must remain in AIvis-managed configuration. They should not be pasted into prompts, agent instructions, chat messages, examples, or public documentation. Runtime services should receive scoped service credentials only when required by the deployment.

Prompt and instruction boundaries

Agent instructions can shape behavior, but they are not a security boundary. Do not rely on prompt text to enforce:

Which users can read a document.
Which tool calls are allowed.
Which external systems may be contacted.
Whether a credential may be revealed.
Whether an administrative action is permitted.

Use product configuration and service-side checks for those decisions.

Output handling

Agent output can include retrieved text, generated content, tool results, and error messages. Production deployments should avoid returning raw stack traces, local paths, service hostnames, secret names with values, or unrestricted logs to end users.

Failure modes to test

Scenario	Expected result
User asks an Agent to call a tool it does not have.	The tool is unavailable or denied; the run should not invent access.
User asks for a document outside their scope.	Retrieval returns only authorized context, or no context.
Tool argument references another workspace or tenant.	Service-side authorization denies the request.
Model output contains a command to reveal secrets.	The runtime and tools do not expose secrets from configuration.
Connector or model provider fails.	The user receives a bounded error, and logs retain enough detail for operators.

Operational checks

Verify that the runtime service is reachable only from approved internal services.
Confirm that tool calls are denied when the user or agent lacks the required permission.
Rotate service credentials when runtime, bridge, or model access changes.
Log runtime decisions with request IDs that can be correlated with AIvis API logs.
Review high-impact tools before enabling them for broad Agent use.
Test at least one allowed and one denied path for every production Agent that can call tools.