Skip to main content

Crate zentinel_agent_sdk

Crate zentinel_agent_sdk 

Source
Expand description

Zentinel Agent SDK - Build proxy agents with less boilerplate.

This crate provides a high-level SDK for building Zentinel proxy agents. It wraps the low-level protocol with ergonomic types and handles common patterns like CLI parsing, logging setup, and graceful shutdown.

§Quick Start

ⓘ
use zentinel_agent_sdk::prelude::*;

struct MyAgent;

#[async_trait]
impl Agent for MyAgent {
    async fn on_request(&self, request: &Request) -> Decision {
        if request.path_starts_with("/admin") && request.header("x-admin-token").is_none() {
            Decision::deny().with_body("Admin access required")
        } else {
            Decision::allow()
        }
    }
}

#[tokio::main]
async fn main() {
    AgentRunner::new(MyAgent)
        .with_name("my-agent")
        .run()
        .await
        .unwrap();
}

§V2 Protocol Support

The SDK supports the v2 agent protocol with gRPC and UDS transports:

ⓘ
use zentinel_agent_sdk::v2::{AgentRunnerV2, TransportConfig};

AgentRunnerV2::new(MyAgent)
    .with_name("my-agent")
    .with_uds("/tmp/my-agent.sock")
    .run()
    .await?;

§Features

  • Simplified types: Request, Response, and Decision provide ergonomic APIs
  • Fluent decision builder: Chain methods to build complex responses
  • Configuration handling: Receive config from proxy’s KDL file
  • CLI support: Built-in argument parsing with clap (optional)
  • Logging: Automatic tracing setup
  • V2 protocol: Support for gRPC and UDS transports

§Crate Features

  • cli (default): Enable CLI argument parsing with clap
  • macros (default): Enable derive macros
  • v2 (default): Enable v2 protocol support with AgentRunnerV2

Re-exports§

pub use serde;
pub use serde_json;
pub use tokio;
pub use tracing;

Modules§

decisions
Shorthand functions for common decisions.
prelude
Prelude module for convenient imports.
v2
V2 protocol runner with gRPC and UDS support.

Structs§

AgentHandler
Handler adapter that bridges the simplified Agent trait to the protocol.
AgentResponse
Agent response message
AgentRunner
Runner for Zentinel agents.
ConfigureEvent
Configure event
Decision
A builder for constructing agent decisions.
GuardrailDetection
A single guardrail detection (prompt injection attempt, PII instance, etc.)
GuardrailInspectEvent
Guardrail inspection event
GuardrailResponse
Guardrail inspection response from agent
Request
A simplified view of an HTTP request for agent processing.
RequestHeadersEvent
Request headers event
RequestMetadata
Request metadata sent to agents
Response
A simplified view of an HTTP response for agent processing.
ResponseHeadersEvent
Response headers event
RunnerConfig
Configuration for the agent runner.
TextSpan
Text span indicating location in content

Enums§

DetectionSeverity
Severity level for guardrail detections
GuardrailInspectionType
Type of guardrail inspection to perform
HeaderOp
Header modification operation
ProtocolDecision
Agent decision

Traits§

Agent
A simplified agent trait for processing HTTP traffic.
ConfigurableAgent
A configurable agent that deserializes its configuration.
ConfigurableAgentExt
Extension trait providing default on_configure for configurable agents.

Attribute Macros§

async_trait