Create documentation and migration guide for SDK workflows #10159
Description
Description
Create comprehensive documentation for the Copilot SDK engine, including migration guide for converting existing CLI workflows to SDK mode.
Part of Epic
#10154 - Copilot SDK Integration for Advanced Agentic Workflows
Documentation Scope
1. SDK Engine Overview
New documentation page: docs/src/content/docs/reference/engines-sdk.md
Content:
- What is the SDK engine and how it differs from CLI
- When to use SDK vs CLI
- Architecture diagram
- Feature comparison table
- Performance characteristics
- Limitations and known issues
2. Session Management Guide
New documentation page: docs/src/content/docs/guides/sdk-sessions.md
Content:
- Multi-turn conversation patterns
- State persistence options
- Session restoration
- State size management
- Best practices for long-running workflows
3. Custom Tools Guide
New documentation page: docs/src/content/docs/guides/sdk-custom-tools.md
Content:
- Inline tool definition syntax
- Parameter schema specification
- Security considerations
- Tool implementation patterns
- Common tool examples
- Testing custom tools
4. Event Handling Guide
New documentation page: docs/src/content/docs/guides/sdk-events.md
Content:
- Event types reference
- Handler registration
- Real-time monitoring patterns
- Budget control with events
- Custom handler implementation
5. Multi-Agent Guide
New documentation page: docs/src/content/docs/guides/sdk-multi-agent.md
Content:
- Multi-agent architecture patterns
- Coordination strategies
- Shared context management
- Agent specialization examples
- Resource management
6. Migration Guide
New documentation page: docs/src/content/docs/guides/migrate-to-sdk.md
Content:
- Decision framework: Should I migrate?
- Step-by-step migration process
- CLI to SDK mapping table
- Example migrations
- Common pitfalls and solutions
- Rollback strategy
Migration Guide Content
Decision Framework
## Should I migrate to SDK mode?
**Migrate if you need:**
- ✅ Multi-turn conversations with context retention
- ✅ Custom inline tools with workflow-specific logic
- ✅ Real-time event handling and streaming
- ✅ Multi-agent orchestration
- ✅ Programmatic control flow (retry, branching)
- ✅ Cost-aware execution with budget controls
**Stay with CLI if:**
- ✅ Simple single-pass workflows
- ✅ No need for conversation context
- ✅ Standard MCP tools are sufficient
- ✅ Prefer battle-tested stabilityMigration Steps
## Step-by-Step Migration
### 1. Evaluate Compatibility
Run compatibility checker:
```bash
gh aw check-sdk-compatibility workflow.md2. Update Frontmatter
Before (CLI):
engine: copilot
tools:
github:
allowed: [issue_read]After (SDK):
engine:
id: copilot
mode: sdk
session:
persistent: true
max-turns: 5
tools:
github:
allowed: [issue_read]3. Convert Custom Logic to Inline Tools
If you have bash scripts doing custom logic, convert to inline tools.
4. Test in Parallel
Run both CLI and SDK versions side-by-side to compare results.
5. Monitor and Tune
Use event handlers to monitor performance and adjust configuration.
## Example Migrations
### Example 1: Simple Workflow
**Before (CLI):**
```yaml
---
engine: copilot
tools:
github:
allowed: [issue_read, add_issue_comment]
---
# Triage Issue
Read issue and add triage label.
After (SDK):
---
engine:
id: copilot
mode: sdk
tools:
github:
allowed: [issue_read, add_issue_comment]
---
# Triage Issue
Read issue and add triage label.Notes: Minimal changes needed for simple workflows.
Example 2: Multi-Stage Review
Before (CLI - not possible):
# Cannot implement multi-stage review with context retentionAfter (SDK):
---
engine:
id: copilot
mode: sdk
session:
persistent: true
max-turns: 10
tools:
github:
allowed: [issue_read, add_issue_comment]
---
# Progressive Code Review
Stage 1: Initial review of PR
Stage 2: Follow-up after developer changes
Stage 3: Final approval checkExample 3: Custom Validation
Before (CLI with bash):
---
engine: copilot
tools:
bash: ["validate.sh"]
---
# Review with Custom Validation
Review code and run ./validate.sh for custom checks.After (SDK with inline tool):
---
engine:
id: copilot
mode: sdk
tools:
inline:
- name: validate_code
description: "Run custom validation"
implementation: |
const result = await exec('./validate.sh');
return { valid: result.exitCode === 0 };
tools:
github:
allowed: [issue_read]
---
# Review with Custom Validation
Review code and use validate_code tool for custom checks.Implementation Tasks
- Create SDK engine reference documentation
- Write session management guide
- Write custom tools guide
- Write event handling guide
- Write multi-agent guide
- Create comprehensive migration guide
- Add CLI to SDK comparison tables
- Create 10+ migration examples
- Add troubleshooting section
- Update main engines documentation
- Create video walkthrough (optional)
- Review with community for feedback
Success Criteria
- Complete documentation coverage for SDK features
- Migration guide with step-by-step instructions
- At least 10 example migrations
- Troubleshooting guide for common issues
- Community review completed
- Documentation published on docs site
Documentation Structure
docs/src/content/docs/
├── reference/
│ ├── engines.md (updated)
│ └── engines-sdk.md (new)
├── guides/
│ ├── migrate-to-sdk.md (new)
│ ├── sdk-sessions.md (new)
│ ├── sdk-custom-tools.md (new)
│ ├── sdk-events.md (new)
│ └── sdk-multi-agent.md (new)
└── examples/
└── sdk-migrations/ (new)
├── simple-workflow.md
├── multi-turn-review.md
├── custom-tools.md
└── multi-agent.md
References
- SDK POC learnings from Design session state management for SDK workflows #10155
- Implementation details from Create documentation and migration guide for SDK workflows #10159
- Migration patterns from early adopters
Priority: High - Critical for adoption
Estimated Effort: 7-10 days
Dependencies: #10159 (SDK engine implementation)
Skills Required: Technical writing, SDK understanding