Initial commit
This commit is contained in:
Zhongwei Li
302
agents/api.analyzer/README.md
Normal file
302
agents/api.analyzer/README.md
Normal file
@@ -0,0 +1,302 @@
|
||||
# api.analyzer Agent
|
||||
|
||||
## Purpose
|
||||
|
||||
**api.analyzer** is a specialized agent that analyzes API specifications for backward compatibility and breaking changes between versions.
|
||||
|
||||
This agent provides detailed compatibility reports, identifies breaking vs non-breaking changes, and suggests migration paths for consumers when breaking changes are unavoidable.
|
||||
|
||||
## Behavior
|
||||
|
||||
- **Reasoning Mode**: `oneshot` – The agent executes once without retries, as compatibility analysis is deterministic
|
||||
- **Capabilities**:
|
||||
- Detect breaking changes between API versions
|
||||
- Generate detailed compatibility reports
|
||||
- Identify removed or modified endpoints
|
||||
- Suggest migration paths for breaking changes
|
||||
- Validate API evolution best practices
|
||||
|
||||
## Skills Used
|
||||
|
||||
The agent has access to the following skills:
|
||||
|
||||
| Skill | Purpose |
|
||||
|-------|---------|
|
||||
| `api.compatibility` | Compares two API spec versions and detects breaking changes |
|
||||
| `api.validate` | Validates individual specs for well-formedness |
|
||||
|
||||
## Workflow Pattern
|
||||
|
||||
The agent follows this straightforward pattern:
|
||||
|
||||
```
|
||||
1. Load old and new API specifications
|
||||
2. Run comprehensive compatibility analysis
|
||||
3. Categorize changes as breaking or non-breaking
|
||||
4. Generate detailed report with migration recommendations
|
||||
5. Return results (no retry needed)
|
||||
```
|
||||
|
||||
## Manifest Fields (Quick Reference)
|
||||
|
||||
```yaml
|
||||
name: api.analyzer
|
||||
version: 0.1.0
|
||||
reasoning_mode: oneshot
|
||||
skills_available:
|
||||
- api.compatibility
|
||||
- api.validate
|
||||
status: draft
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
This agent is invoked through a command or workflow:
|
||||
|
||||
### Via Slash Command
|
||||
|
||||
```bash
|
||||
# Assuming /api-compatibility command is registered to use this agent
|
||||
/api-compatibility specs/user-service-v1.yaml specs/user-service-v2.yaml
|
||||
```
|
||||
|
||||
### Via Workflow
|
||||
|
||||
Include the agent in a workflow YAML:
|
||||
|
||||
```yaml
|
||||
# workflows/check_api_compatibility.yaml
|
||||
steps:
|
||||
- agent: api.analyzer
|
||||
input:
|
||||
old_spec_path: "specs/user-service-v1.0.0.yaml"
|
||||
new_spec_path: "specs/user-service-v2.0.0.yaml"
|
||||
fail_on_breaking: true
|
||||
```
|
||||
|
||||
## Context Requirements
|
||||
|
||||
The agent expects the following context:
|
||||
|
||||
| Field | Type | Description | Example |
|
||||
|-------|------|-------------|---------|
|
||||
| `old_spec_path` | string | Path to the previous/old API specification | `"specs/api-v1.0.0.yaml"` |
|
||||
| `new_spec_path` | string | Path to the new/updated API specification | `"specs/api-v2.0.0.yaml"` |
|
||||
| `fail_on_breaking` | boolean | Whether to fail (exit non-zero) if breaking changes detected | `true` or `false` |
|
||||
|
||||
## Example Task
|
||||
|
||||
**Input**:
|
||||
```
|
||||
"Compare user-service v1.0.0 with v2.0.0 for breaking changes"
|
||||
```
|
||||
|
||||
**Agent execution**:
|
||||
|
||||
1. **Load both specifications**:
|
||||
- Old: `specs/user-service-v1.0.0.openapi.yaml`
|
||||
- New: `specs/user-service-v2.0.0.openapi.yaml`
|
||||
|
||||
2. **Analyze endpoint changes**:
|
||||
- ✅ **Added**: `GET /users/{id}/preferences` (non-breaking)
|
||||
- ❌ **Removed**: `DELETE /users/{id}/avatar` (breaking)
|
||||
- ⚠️ **Modified**: `POST /users` now requires additional field `email_verified` (breaking)
|
||||
|
||||
3. **Check for breaking schema changes**:
|
||||
- ❌ Removed property: `User.phoneNumber` (breaking)
|
||||
- ✅ Added optional property: `User.preferences` (non-breaking)
|
||||
- ❌ Changed property type: `User.age` from `integer` to `string` (breaking)
|
||||
|
||||
4. **Identify parameter or response format changes**:
|
||||
- ❌ Query parameter `filter` changed from optional to required in `GET /users` (breaking)
|
||||
- ✅ Response includes new optional field `User.last_login` (non-breaking)
|
||||
|
||||
5. **Generate compatibility report**:
|
||||
```json
|
||||
{
|
||||
"compatible": false,
|
||||
"breaking_changes": [
|
||||
{
|
||||
"type": "endpoint_removed",
|
||||
"endpoint": "DELETE /users/{id}/avatar",
|
||||
"severity": "high",
|
||||
"migration": "Use PUT /users/{id} with avatar=null instead"
|
||||
},
|
||||
{
|
||||
"type": "required_field_added",
|
||||
"location": "POST /users request body",
|
||||
"field": "email_verified",
|
||||
"severity": "high",
|
||||
"migration": "Clients must now provide email_verified field"
|
||||
},
|
||||
{
|
||||
"type": "property_removed",
|
||||
"schema": "User",
|
||||
"property": "phoneNumber",
|
||||
"severity": "medium",
|
||||
"migration": "Use new phone_contacts array instead"
|
||||
},
|
||||
{
|
||||
"type": "type_changed",
|
||||
"schema": "User",
|
||||
"property": "age",
|
||||
"old_type": "integer",
|
||||
"new_type": "string",
|
||||
"severity": "high",
|
||||
"migration": "Convert age to string format"
|
||||
}
|
||||
],
|
||||
"non_breaking_changes": [
|
||||
{
|
||||
"type": "endpoint_added",
|
||||
"endpoint": "GET /users/{id}/preferences"
|
||||
},
|
||||
{
|
||||
"type": "optional_field_added",
|
||||
"schema": "User",
|
||||
"property": "preferences"
|
||||
},
|
||||
{
|
||||
"type": "response_field_added",
|
||||
"endpoint": "GET /users/{id}",
|
||||
"field": "last_login"
|
||||
}
|
||||
],
|
||||
"change_summary": {
|
||||
"breaking": 4,
|
||||
"additions": 2,
|
||||
"modifications": 2,
|
||||
"removals": 2
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
6. **Provide migration recommendations**:
|
||||
```markdown
|
||||
## Migration Guide: v1.0.0 → v2.0.0
|
||||
|
||||
### Breaking Changes
|
||||
|
||||
1. **Removed endpoint: DELETE /users/{id}/avatar**
|
||||
- **Impact**: High - Clients using this endpoint will fail
|
||||
- **Migration**: Use PUT /users/{id} with avatar=null instead
|
||||
- **Effort**: Low
|
||||
|
||||
2. **New required field: email_verified in POST /users**
|
||||
- **Impact**: High - All user creation requests must include this field
|
||||
- **Migration**: Update client code to provide email_verified boolean
|
||||
- **Effort**: Medium
|
||||
|
||||
3. **Property removed: User.phoneNumber**
|
||||
- **Impact**: Medium - Clients reading this field will get undefined
|
||||
- **Migration**: Use User.phone_contacts array instead
|
||||
- **Effort**: Medium
|
||||
|
||||
4. **Type changed: User.age (integer → string)**
|
||||
- **Impact**: High - Type mismatch will cause deserialization errors
|
||||
- **Migration**: Update models to use string type and convert existing data
|
||||
- **Effort**: High
|
||||
|
||||
### Recommended Approach
|
||||
1. Implement migration layer for 2 versions
|
||||
2. Communicate breaking changes to consumers 30 days in advance
|
||||
3. Provide backward-compatible endpoints during transition period
|
||||
4. Monitor usage of deprecated endpoints
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Timeout | Behavior |
|
||||
|----------|---------|----------|
|
||||
| Spec load failure | N/A | Return error with file path details |
|
||||
| Comparison failure | N/A | Return partial analysis with error context |
|
||||
| Timeout | 120 seconds | Fails after 2 minutes |
|
||||
|
||||
### On Success
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"outputs": {
|
||||
"compatibility_report": {
|
||||
"compatible": false,
|
||||
"breaking_changes": [...],
|
||||
"non_breaking_changes": [...],
|
||||
"change_summary": {...}
|
||||
},
|
||||
"migration_recommendations": "...",
|
||||
"api_diff_visualization": "..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### On Failure
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "failed",
|
||||
"error_details": {
|
||||
"error": "Failed to load old spec",
|
||||
"file_path": "specs/user-service-v1.0.0.yaml",
|
||||
"details": "File not found"
|
||||
},
|
||||
"partial_analysis": null,
|
||||
"suggested_fixes": [
|
||||
"Verify file path exists",
|
||||
"Check file permissions"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Use Cases
|
||||
|
||||
### 1. Pre-Release Validation
|
||||
|
||||
Run before releasing a new API version to ensure backward compatibility:
|
||||
|
||||
```yaml
|
||||
# workflows/validate_release.yaml
|
||||
steps:
|
||||
- agent: api.analyzer
|
||||
input:
|
||||
old_spec_path: "specs/production/api-v1.yaml"
|
||||
new_spec_path: "specs/staging/api-v2.yaml"
|
||||
fail_on_breaking: true
|
||||
```
|
||||
|
||||
### 2. Continuous Integration
|
||||
|
||||
Integrate into CI/CD to prevent accidental breaking changes:
|
||||
|
||||
```yaml
|
||||
# .github/workflows/api-check.yml
|
||||
- name: Check API Compatibility
|
||||
run: |
|
||||
# Agent runs via workflow.compose
|
||||
python skills/workflow.compose/workflow_compose.py \
|
||||
workflows/check_api_compatibility.yaml
|
||||
```
|
||||
|
||||
### 3. Documentation Generation
|
||||
|
||||
Generate migration guides automatically:
|
||||
|
||||
```bash
|
||||
# Use agent output to create migration documentation
|
||||
/api-compatibility old.yaml new.yaml > migration-guide.md
|
||||
```
|
||||
|
||||
## Status
|
||||
|
||||
**Draft** – This agent is under development and not yet marked active in the registry.
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Agents Overview](../../docs/betty-architecture.md#layer-2-agents-reasoning-layer) – Understanding agents in Betty's architecture
|
||||
- [Agent Schema Reference](../../docs/agent-schema-reference.md) – Agent manifest fields and structure
|
||||
- [api.compatibility SKILL.md](../../skills/api.compatibility/SKILL.md) – Underlying compatibility check skill
|
||||
- [API-Driven Development](../../docs/api-driven-development.md) – Full API workflow including compatibility checks
|
||||
|
||||
## Version History
|
||||
|
||||
- **0.1.0** (Oct 2025) – Initial draft implementation with oneshot analysis pattern
|
||||
Reference in New Issue
Block a user