Sókrates Wiki

Pydantic-AI Agent Integration Architecture

3 min read

Pydantic-AI Agent Integration Architecture

Summary

This architectural decision defines how specialized pydantic-ai agents are integrated into the Sokrates stack. Rather than embedding agent logic directly within the Eidos API or Hermes skills, agents reside in a standalone workspace package and are invoked by Hermes through a custom plugin using the standard delegate_task pattern.

Details

The integration of pydantic-ai agents serves as a bridge between the existing GraphModel specifications in Eidos and the emerging Hyle ontological patterns. The primary goal of these agents is to exercise the Eidos Domain Specific Language (DSL) against the live Neo4j graph to validate that the system’s reasoning and data retrieval capabilities work as intended.

Architectural Decision: The “Option B” Approach

During the design phase, three primary integration patterns were considered:

  1. Inside Eidos (Option A): Exposing agents as MCP tools directly from the Eidos service.
  2. Standalone Package (Option B): Creating a dedicated package (e.g., agents/ or hyle/) in the monorepo for agent definitions.
  3. Hermes Skills (Option C): Embedding agent logic within Hermes markdown skill files.

The project adopted Option B. This approach maintains a clean separation of concerns: Eidos remains the knowledge and data layer, while the agent package handles orchestration and reasoning logic. This prevents Eidos from becoming bloated with orchestration code and ensures that agent logic is testable, typed, and version-controlled as standard Python code.

Hermes Plugin Implementation

To facilitate the invocation of these agents without forking the Hermes Agent source code, the system utilizes the Hermes plugin API. This ensures forward compatibility with upstream Hermes releases.

The integration follows this structure:

  • Plugin Directory: ~/.hermes/plugins/sokrates/
  • Manifest: A plugin.yaml file defines the plugin metadata.
  • Registration: An __init__.py file contains a register(ctx) function. This function uses ctx.register_tool() to add a custom tool (e.g., delegate_to_specialist) to the Hermes environment.
  • Execution: When Hermes invokes the delegation tool, the plugin spawns the pydantic-ai agent in-process or as a sub-process. The agent then communicates with Eidos over HTTP or MCP to query the graph.

Technical Constraints and Patterns

  • Communication: Agents must interact with Eidos via its public API or MCP server, not by direct database access. This preserves the security boundary where only Eidos holds database credentials.
  • Deployment: The deployment of the Hermes plugin and the agent package is managed via NixOS modules, which ensure the plugin is correctly placed in the hermes user’s plugin directory and that all Python dependencies are available.
  • Model Selection: For testing and validation of the DSL, the system routes inference through OpenRouter (current production models: z-ai/glm-5-turbo primary, minimax/minimax-m2.7 fallback). The target production model for on-premises DGX Spark deployments is Gemma 4 31B Dense.

Graph View

Backlinks