feat: add support for passing custom instructions to system prompt

[homanp]

Description

Add support for passing custom instructions to the guard model

Related Issue

Fixes #1082 #1081

Checklist

• I tested my changes
• I reviewed my own code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
docs	Ready	Preview	Comment	Dec 1, 2025 8:00pm

[claude]

Pull Request Review: Add support for passing custom instructions to system prompt

Summary

This PR adds support for a system_prompt parameter across all interfaces (CLI, TypeScript SDK, Python SDK, MCP server) to allow users to customize guard behavior. The implementation is consistent, well-documented, and follows existing patterns.

✅ Strengths

Code Quality

• Consistent implementation across all platforms (CLI, SDKs, MCP)
• Clean code that follows existing patterns and conventions
• Proper parameter handling with validation and error messages
• Backwards compatible - the parameter is optional everywhere

Documentation

• Comprehensive documentation updates across all platforms
• Clear examples showing how to use the new feature
• CHANGELOG properly updated with detailed descriptions
• API documentation (OpenAPI spec) correctly updated

🔍 Findings

Code Quality & Best Practices

1. TypeScript SDK (sdk/typescript/src/index.ts)

• ✅ Proper interface design with GuardOptions extending GuardCallbacks
• ✅ Consistent parameter passing across all three input types (file, URL, text)
• ✅ Good use of conditional object building to avoid undefined values
• ⚠️ Minor: Type assertion as any on line 126 (CLI) and 152 (MCP) - consider creating proper types

// cli/src/commands/guard.ts:126
const result = await client.guard(input, options as any);

Recommendation: Define proper option types in the SDK to avoid as any assertions.

2. Python SDK (sdk/python/src/superagent_ai/client.py)

• ✅ Clean implementation following Python conventions
• ✅ Proper type hints with Optional[str]
• ✅ Consistent dictionary building pattern for request bodies
• ✅ Good code structure and readability

3. CLI (cli/src/commands/guard.ts)

• ✅ Proper flag parsing with validation
• ✅ Support for both command-line and stdin JSON input
• ✅ Good error handling with clear error messages
• ✅ Stdin JSON support allows system_prompt to override CLI flag appropriately (lines 85-87)

// cli/src/commands/guard.ts:85-87
if (inputData.system_prompt && !systemPrompt) {
  systemPrompt = inputData.system_prompt;
}

Observation: CLI flag takes precedence over stdin JSON, which is good design.

4. MCP Server (mcp/src/index.ts)

• ✅ Proper Zod schema validation
• ✅ Clear description for the parameter
• ✅ Consistent implementation with SDK usage
• ⚠️ Minor: Same as any type assertion issue (line 152)

Security Concerns

✅ No security issues identified

• Input validation is properly handled by the API
• No injection vulnerabilities introduced
• Parameter is safely passed through to the API
• No sensitive data exposure

Performance Considerations

✅ No performance concerns

• Adding an optional string parameter has negligible performance impact
• No additional API calls or processing overhead
• Proper request body construction without unnecessary allocations

Test Coverage

⚠️ Missing test coverage for the new feature

The existing test file (sdk/typescript/tests/guard.test.ts) does not include tests for the new systemPrompt parameter.

Recommendations:

1. Add test cases for systemPrompt parameter:
   • Test that systemPrompt is properly passed to the API
   • Test guard behavior with custom system prompts
   • Test that the parameter is optional

Example test structure:

it("guard accepts systemPrompt option", async () => {
  const client = createClient({ apiBaseUrl, apiKey });
  const result = await client.guard("test input", {
    systemPrompt: "Focus on detecting prompt injection"
  });
  expect(result).toBeDefined();
  // Add assertions based on expected behavior
});

2. Consider adding tests for Python SDK as well
3. Add CLI integration tests for the --system-prompt flag

Potential Bugs or Issues

1. Type Safety (Minor)

Location: cli/src/commands/guard.ts:126, mcp/src/index.ts:152

Using as any bypasses TypeScript's type checking. While this works, it reduces type safety.

Recommendation:

// In sdk/typescript/src/index.ts, export GuardOptions properly
export interface GuardOptions extends GuardCallbacks {
  systemPrompt?: string;
}

// Then in CLI and MCP, import and use the type
import type { GuardOptions } from "superagent-ai";
const options: GuardOptions = {};

2. Documentation Encoding Issue (Minor)

Location: docs/content/docs/cli.mdx:393, 406

There appear to be encoding issues in the documentation:

=� BLOCKED: [reasoning]  // Should be an emoji
=� Superagent Guard blocked...  // Encoding corruption

Recommendation: Ensure proper UTF-8 encoding for emoji characters in documentation.

API Design Considerations

✅ Well-designed API extension

• Parameter naming is consistent (system_prompt in API/JSON, systemPrompt in TypeScript, system_prompt in Python)
• Optional parameter doesn't break existing code
• Clear and descriptive parameter name
• Follows existing patterns in the codebase

📝 Recommendations

High Priority

1. Add test coverage for the new systemPrompt parameter across all SDKs
2. Fix documentation encoding issues for emoji characters

Medium Priority

3. Improve type safety by removing as any assertions and properly typing options
4. Document behavior when system_prompt conflicts with default guard behavior (if applicable)

Low Priority

5. Consider adding validation for system_prompt length limits (if any exist on the API side)
6. Consider adding examples in README files showing real-world use cases

✅ Approval Recommendation

Status: Approved with minor suggestions

This is a solid implementation that:

• ✅ Solves the stated problem (issues [Feature]: Split up requests to decrease latency #1082, [Feature]: Expose system prompt to user #1081)
• ✅ Maintains code quality and consistency
• ✅ Includes comprehensive documentation
• ✅ Introduces no security or performance concerns
• ⚠️ Could benefit from additional test coverage

The identified issues are minor and don't block merging. The missing tests and type safety improvements can be addressed in follow-up PRs if needed.

📊 Change Statistics

• 21 files changed
• 380 additions, 187 deletions
• Affects: CLI, TypeScript SDK, Python SDK, MCP Server, and documentation

Great work on maintaining consistency across all interfaces! 🎉