LLM Interactions
Relevant source files
The following files were used as context for generating this wiki page:
LLM Interactions within the Nexus Orchestrator refer to the structured communication protocols and orchestration logic that enable AI agents to interface with local and remote infrastructure. Nexus serves as an autonomous infrastructure daemon, providing a "nervous system" that facilitates these interactions through a multi-layered architecture involving connectivity, orchestration, and state management.
The system bridges the "infrastructure gap" by allowing LLMs to manage environments, execute SSH connectivity, and maintain persistent state via dedicated context files. These interactions are governed by Zero Trust security principles and Open Policy Agent (OPA) logic to ensure that non-human identities operate within safe parameters.
Sources: README.md:1-12, README.md:15-18
Interaction Architecture
The interaction model is divided into four primary pillars that define how an LLM or AI agent communicates with the underlying system resources.
| Pillar | Component | Role in LLM Interaction |
|---|---|---|
| Connectivity | MCP (Model Context Protocol) | Standardized protocol for agent-infrastructure communication. |
| Orchestration | LangGraph | Manages complex workflow logic and agentic decision-making paths. |
| Context | AGENTS.md / Persistent State | Maintains the history and metadata of agents interacting with the system. |
| Governance | OPA / Zero Trust | Validates permissions and security posture for every agent request. |
Sources: README.md:14-19, context/AGENTS.md:1-5
The Communication Flow
The following diagram illustrates the lifecycle of an LLM interaction, from the initial agent request through the governance and orchestration layers to the final infrastructure execution.
This flowchart depicts the sequence of validation and execution for LLM-driven infrastructure commands.
Sources: README.md:4-9, README.md:15-19
Agent Tracking and Context
A critical aspect of LLM interactions is the Context Layer. Nexus maintains a registry of all AI agents that have interacted with the orchestrator to ensure persistent state across sessions. This is primarily managed via the AGENTS.md file, which tracks the identity and trust level of each non-human entity.
Agent Registry Schema
The system tracks the following attributes for every interacting agent:
| Field | Description | Source File |
|---|---|---|
| Agent ID | Unique identifier for the AI agent. | context/AGENTS.md |
| Description | The functional purpose or scope of the agent. | context/AGENTS.md |
| Trust Level | Security tier (e.g., restricted, elevated) defined by OPA. | context/AGENTS.md, policy/governance.rego |
Sources: context/AGENTS.md:7-11, README.md:17
Connectivity and Protocol Management
LLMs interact with Nexus using the Model Context Protocol (MCP). This protocol abstracts the complexity of SSH and environment management, providing the LLM with a standardized interface to request resources.
Sequence of an Orchestrated Interaction
When an LLM initiates a task, such as deploying a container or checking server status, the sequence follows a "local-first" execution pattern.
Sequence diagram showing the handoff between the connectivity layer (MCP) and the orchestration layer (LangGraph).
Sources: README.md:5-7, mcp_server/config.json, scripts/setup_env.sh
Governance and Security Logic
Interactions are not direct; they are mediated by a Governance Layer. This layer utilizes Open Policy Agent (OPA) to evaluate whether an agent's requested action aligns with defined security policies.
Security Implementation
- Non-Human Identities: Every LLM interaction is treated as a request from a machine identity.
- Zero Trust: No interaction is trusted by default; connectivity is established only after policy evaluation.
- Environment Isolation: The
scripts/setup_env.shensures that LLM interactions occur within sandboxed or controlled environments.
Sources: README.md:8-9, README.md:18, policy/governance.rego, scripts/setup_env.sh
Conclusion
LLM Interactions in Nexus Orchestrator are highly structured, moving beyond simple API calls to a robust "nervous system" architecture. By combining MCP for connectivity, LangGraph for orchestration, and OPA for governance, Nexus provides a secure and stateful environment for AI agents to perform complex infrastructure tasks autonomously.