github / github/copilot-sdk

Feature Request: Session Export and Replay for Agent Debugging

Open
#1,586 0 comments 1 reaction 0 assignees View on GitHub
enhancement
Dominant language
Java
Stars
10.5k
Forks
1.5k
Avg merge
1d 14h
Merged PRs (30d)
129

Description

**Title**

Feature Request: Session Export and Replay for Agent Debugging

## Description

### Problem

When building agents with the Copilot SDK, debugging complex multi-turn conversations can be difficult.

Developers often encounter situations where:

* An agent behaves unexpectedly after several turns.
* A tool invocation produces an incorrect result.
* Context accumulation affects later responses.
* Bugs only appear after a specific sequence of interactions.

Currently, reproducing these issues typically requires manually recreating the entire conversation flow.

### Proposed Solution

Add session export and replay capabilities to the Copilot SDK.

#### Session Export

Allow developers to export a session including:

* User messages
* Assistant messages
* Tool calls
* Tool results
* MCP interactions
* Session metadata
* Model configuration

Example:

```json
{
"sessionId": "...",
"messages": [...],
"toolCalls": [...],
"metadata": {...}
}
```

#### Session Replay

Provide APIs to replay exported sessions for debugging and testing.

Example:

```typescript
const session = await sdk.loadSession("./session.json");

await session.replay();
```

#### Optional Features

* Replay until a specific turn
* Step-by-step execution
* Compare outputs across SDK versions
* Compare outputs across models
* Deterministic replay mode

### Use Cases

#### Agent Development

Reproduce user-reported failures without requiring users to recreate conversations.

#### Regression Testing

Verify that SDK upgrades do not change agent behavior unexpectedly.

#### Tool Debugging

Inspect exactly how tool calls and results affected agent decisions.

#### Benchmarking

Compare responses across different models using the same session history.

### Benefits

* Easier debugging
* Better reproducibility
* Improved regression testing
* Faster issue triage
* Better developer experience for agent builders

### Alternatives Considered

* Manual logging of messages
* Custom session serialization
* Third-party observability platforms

These approaches require significant additional implementation and are not standardized across SDK users.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the Copilot SDK's existing session handling and the proposed loadSession/replay API shown in the issue. Establish how exported messages, tool calls, MCP interactions, metadata, and model configuration should be represented, then define completion around exporting a session and replaying it for debugging or testing.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, typescript
Domain
developer-experience, testing
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.