Implement prompt variable processing for Agent Client Protocol by marekdkropiewnicki-dotcom · Pull Request #3 · marekdkropiewnicki-dotcom/agent-client-protocol

marekdkropiewnicki-dotcom · 2026-05-14T23:37:53Z

Prompt Variable Processing Implementation

This PR implements a comprehensive prompt variable processing system for the Agent Client Protocol (ACP), enabling dynamic content generation through template substitution.

🚀 Key Features

New Data Structures

PromptVariable: Defines named placeholders with metadata including value, description, type, and validation constraints
PromptVariableType: Enum supporting String, Number, Boolean, DateTime, Url, Email, Text, and Select (with options) types
PromptTemplateContent: New ContentBlock variant supporting {{variable_name}} syntax for variable substitution
promptVariables capability: Added to PromptCapabilities to indicate agent support for variable processing

Template Processing

substitute() method for PromptTemplateContent that replaces {{variable_name}} placeholders with actual values
Support for default values when variables are not provided
Graceful handling of missing variables (leaves placeholders unchanged)
Rich metadata support for each variable (descriptions, types, required/optional flags)

Cross-Version Compatibility

Full implementation in both ACP v1 and v2
Conversion logic between protocol versions in src/v2/conversion.rs
Backward compatibility maintained through versioning system

📁 Files Modified

Core Implementation

src/v1/content.rs - Added prompt variable types for v1 compatibility
src/v2/content.rs - Main implementation of prompt variable system
src/v1/agent.rs - Added promptVariables capability for v1
src/v2/agent.rs - Added promptVariables capability for v2
src/v2/conversion.rs - Cross-version conversion logic

Generated Schema Files

schema/schema.json - Updated stable schema
schema/schema.unstable.json - Updated unstable schema
schema/schema.v2.unstable.json - Updated v2 unstable schema
schema/meta.*.json - Updated metadata files
docs/protocol/*.mdx - Updated documentation

🧪 Testing

Added comprehensive test coverage including:

Variable creation and value resolution
Template substitution with various scenarios
Cross-version conversion validation
JSON serialization/deserialization roundtrips
275 tests passing ✅

💡 Usage Example

use agent_client_protocol_schema::v2::{PromptVariable, PromptTemplateContent, PromptVariableType};

// Create variables
let variables = vec![
    PromptVariable::new("user")
        .value("Alice")
        .description("The user's name")
        .variable_type(PromptVariableType::String)
        .required(true),
    PromptVariable::new("task")
        .value("code review")
        .variable_type(PromptVariableType::Select { 
            options: vec!["code review".to_string(), "testing".to_string()] 
        })
];

// Create template
let template = PromptTemplateContent::new(
    "Hello {{user}}, let's work on {{task}}!",
    variables
);

// Substitute variables
let result = template.substitute();
// Result: "Hello Alice, let's work on code review!"

🔧 Technical Details

Uses {{variable_name}} syntax for maximum compatibility with existing templating systems
Supports rich type system with validation constraints
Maintains protocol extensibility through _meta fields
Graceful degradation for unsupported variable types
Schema generation via Rust's JsonSchema derive macro

🎯 Protocol Integration

This implementation enables clients and agents to:

Exchange rich prompt templates with variable definitions
Validate user inputs against variable type constraints
Generate dynamic prompts with context-aware substitution
Build reusable prompt libraries with parameterized templates

Ready for review and integration into the main ACP specification! 🎉

Summary by cubic

Adds prompt variable processing with a new PromptTemplate block and variable schema. Also stabilizes the logout method and introduces experimental MCP-over-ACP messaging; v1/v2 schemas and docs updated.

New Features
- ContentBlock::PromptTemplate with {{variable_name}} substitution and a substitute() helper.
- PromptVariable and PromptVariableType (String, Number, Boolean, DateTime, Url, Email, Text, Select); defaults supported; missing variables left unchanged.
- PromptCapabilities.promptVariables to gate use in session/prompt (v1/v2 with conversion; schemas/docs regenerated).
- logout is now stable via agentCapabilities.auth.logout with new authentication docs.
- Experimental MCP-over-ACP types and methods added behind unstable_mcp_over_acp (capability: mcpCapabilities.acp), mirrored in v1 and v2.
Migration
- Agents: advertise promptVariables: true in PromptCapabilities to accept ContentBlock::PromptTemplate.
- Clients: send PromptTemplate only when the capability is advertised; otherwise use Text.
- logout: call only when agentCapabilities.auth.logout is present.
- MCP-over-ACP: enable unstable_mcp_over_acp and use only when mcpCapabilities.acp is advertised.

^{Written for commit 3b3dd37. Summary will update on new commits. Review in cubic}

Note