docs(agent-protocol): document public API types for agent authors#140
Merged
raffaelschneider merged 7 commits intomainfrom Mar 14, 2026
Merged
docs(agent-protocol): document public API types for agent authors#140raffaelschneider merged 7 commits intomainfrom
raffaelschneider merged 7 commits intomainfrom
Conversation
Add comprehensive documentation to key agent-protocol types: - AgentPool: connection pooling and load balancing - Decision: agent response types (Allow, Block, Redirect, Challenge) - AgentHandlerV2: trait for implementing agent handlers - GrpcAgentServerV2/UdsAgentServerV2: transport server types Includes usage examples, error handling guidance, and feature explanations to help agent authors understand the protocol API. Resolves #114
Address review feedback from @raffaelschneider: - protocol.rs: use std::collections::HashMap instead of non-existent crate re-export - pool.rs: fix field name to connections_per_agent (not max_), use add_agent() and send_request_headers() (correct method names) - server.rs: use AgentCapabilities::new() builder + with_event(), AgentResponse::block() named constructor, server.run() not serve(), merge disconnected doc blocks, fix imports - uds_server.rs: server.run() not serve(), remove inaccurate "hot reload" and "graceful shutdown" claims
- Fix add_agent example to use endpoint string instead of agent_connection object - Fix send_request_headers to include all 3 required parameters: agent_id, correlation_id, event - Merge duplicate doc summaries on AgentPool into one cohesive block
- Fix duplicate doc block on AgentPool - Improve example documentation clarity
- Fix send_request_headers signature (3 params: agent_id, correlation_id, event) - Fix add_agent parameter documentation (use string endpoint, not object) - Merge duplicate AgentPool doc blocks into single coherent block - Fix field name: max_connections_per_agent → connections_per_agent - Update method names: add_grpc_agent/add_uds_agent → add_agent - Update method names: process_request → send_request_headers
- Fix AgentHandlerV2 example: import AgentResponse from crate root (protocol.rs), not from v2 (streaming.rs), which has different method signatures. Mark as no_run since it defines a type inline. - Mark AgentPool, GrpcAgentServerV2, UdsAgentServerV2 examples as ignore since they reference fictional types (MyAgent) and use await outside async context. - Remove unused AgentHandlerV2 import from GrpcAgentServerV2 example.
4 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Continuation of #137 by @xvchris, with doc test fixes applied.
Decision,AgentPool,AgentHandlerV2,GrpcAgentServerV2,UdsAgentServerV2cargo test --docAgentResponseimport inAgentHandlerV2example (use crate root, notv2::)ignoreResolves #114, supersedes #137.
Test plan
cargo test --doc -p zentinel-agent-protocolpassescargo test --lib -p zentinel-agent-protocolpassescargo clippycleancargo fmt --checkclean