303 lines
8.6 KiB
Markdown
303 lines
8.6 KiB
Markdown
# 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
|