mirror of
https://github.com/harivansh-afk/sandbox-agent.git
synced 2026-04-15 07:04:48 +00:00
docs: merge universal schema and coverage matrix into session-transcript-schema
This commit is contained in:
Nathan Flurry
parent
8c90cb36df
commit
c0c3ef6c93
5 changed files with 81 additions and 112 deletions
|
|
@ -40,10 +40,10 @@ Universal schema guidance:
|
|||
- Never use synthetic data or mocked responses in tests.
|
||||
- Never manually write agent types; always use generated types in `resources/agent-schemas/`. If types are broken, fix the generated types.
|
||||
- The universal schema must provide consistent behavior across providers; avoid requiring frontend/client logic to special-case agents.
|
||||
- The UI must reflect every field in AgentCapabilities; keep it in sync with `docs/agent-compatibility.mdx` and `agent_capabilities_for`.
|
||||
- The UI must reflect every field in AgentCapabilities; keep it in sync with `docs/session-transcript-schema.mdx` and `agent_capabilities_for`.
|
||||
- When parsing agent data, if something is unexpected or does not match the schema, bail out and surface the error rather than trying to continue with partial parsing.
|
||||
- When defining the universal schema, choose the option most compatible with native agent APIs, and add synthetics to fill gaps for other agents.
|
||||
- Use `docs/universal-schema.mdx` as the source of truth for universal schema terminology and keep it updated alongside schema changes.
|
||||
- Use `docs/session-transcript-schema.mdx` as the source of truth for schema terminology and keep it updated alongside schema changes.
|
||||
- On parse failures, emit an `agent.unparsed` event (source=daemon, synthetic=true) and treat it as a test failure. Preserve raw payloads when `include_raw=true`.
|
||||
- Track subagent support in `docs/conversion.md`. For now, normalize subagent activity into normal message/tool flow, but revisit explicit subagent modeling later.
|
||||
- Keep the FAQ in `README.md` and `frontend/packages/website/src/components/FAQ.tsx` in sync. When adding or modifying FAQ entries, update both files.
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@
|
|||
|
||||
- **Any coding agent**: Universal API to interact with all agents with full feature coverage
|
||||
- **Server or SDK mode**: Run as an HTTP server or with the TypeScript SDK
|
||||
- **Universal session schema**: [Universal schema](https://sandboxagent.dev/docs/universal-schema) to store agent transcripts
|
||||
- **Universal session schema**: [Session transcript schema](https://sandboxagent.dev/docs/session-transcript-schema) to store agent transcripts
|
||||
- **Supports your sandbox provider**: Daytona, E2B, Vercel Sandboxes, and more
|
||||
- **Lightweight, portable Rust binary**: Install anywhere with 1 curl command
|
||||
- **Automatic agent installation**: Agents are installed on-demand when first used
|
||||
|
|
@ -160,9 +160,9 @@ Debug sessions and events with the [Inspector UI](https://inspect.sandboxagent.d
|
|||
|
||||
[Explore API](https://sandboxagent.dev/docs/api-reference) — [View Specification](https://github.com/rivet-dev/sandbox-agent/blob/main/docs/openapi.json)
|
||||
|
||||
### Universal Schema
|
||||
### Session Transcript Schema
|
||||
|
||||
All events follow a [universal schema](https://sandboxagent.dev/docs/universal-schema) that normalizes differences between agents.
|
||||
All events follow a [session transcript schema](https://sandboxagent.dev/docs/session-transcript-schema) that normalizes differences between agents.
|
||||
|
||||
### Tip: Extract credentials
|
||||
|
||||
|
|
|
|||
|
|
@ -1,102 +0,0 @@
|
|||
---
|
||||
title: "Session Event Coverage"
|
||||
description: "What appears in your session transcript for each agent."
|
||||
icon: "table"
|
||||
---
|
||||
|
||||
Each coding agent outputs events in its own native format. The sandbox-agent converts these into a [universal event schema](/docs/universal-schema), giving you a consistent session transcript regardless of which agent you use.
|
||||
|
||||
This page shows which agent capabilities appear in the universal event stream. All agents retain their full native capabilities—this only reflects what's normalized into the universal schema.
|
||||
|
||||
## Coverage Matrix
|
||||
|
||||
| Feature | Claude | Codex | OpenCode | Amp |
|
||||
|--------------------|:------:|:-----:|:------------:|:------------:|
|
||||
| Stability | Stable | Stable| Experimental | Experimental |
|
||||
| Text Messages | ✓ | ✓ | ✓ | ✓ |
|
||||
| Tool Calls | ✓ | ✓ | ✓ | ✓ |
|
||||
| Tool Results | ✓ | ✓ | ✓ | ✓ |
|
||||
| Questions (HITL) | ✓ | | ✓ | |
|
||||
| Permissions (HITL) | ✓ | ✓ | ✓ | - |
|
||||
| Images | - | ✓ | ✓ | - |
|
||||
| File Attachments | - | ✓ | ✓ | - |
|
||||
| Session Lifecycle | - | ✓ | ✓ | - |
|
||||
| Error Events | - | ✓ | ✓ | ✓ |
|
||||
| Reasoning/Thinking | - | ✓ | - | - |
|
||||
| Command Execution | - | ✓ | - | - |
|
||||
| File Changes | - | ✓ | - | - |
|
||||
| MCP Tools | - | ✓ | - | - |
|
||||
| Streaming Deltas | ✓ | ✓ | ✓ | - |
|
||||
|
||||
Agents: [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) · [Codex](https://github.com/openai/codex) · [OpenCode](https://github.com/opencode-ai/opencode) · [Amp](https://ampcode.com)
|
||||
|
||||
- ✓ = Appears in session events
|
||||
- \- = Agent supports natively, schema conversion coming soon
|
||||
- (blank) = Not supported by agent
|
||||
|
||||
## Feature Descriptions
|
||||
|
||||
### Text Messages
|
||||
|
||||
Basic message exchange between user and assistant.
|
||||
|
||||
### Tool Calls & Results
|
||||
|
||||
Visibility into tool invocations (file reads, command execution, etc.) and their results. When not natively supported, tool activity is embedded in message content.
|
||||
|
||||
### Questions (HITL)
|
||||
|
||||
Interactive questions the agent asks the user. Emits `question.requested` and `question.resolved` events.
|
||||
|
||||
### Permissions (HITL)
|
||||
|
||||
Permission requests for sensitive operations. Emits `permission.requested` and `permission.resolved` events.
|
||||
|
||||
### Images
|
||||
|
||||
Support for image attachments in messages.
|
||||
|
||||
### File Attachments
|
||||
|
||||
Support for file attachments in messages.
|
||||
|
||||
### Session Lifecycle
|
||||
|
||||
Native `session.started` and `session.ended` events. When not supported, the daemon emits synthetic lifecycle events.
|
||||
|
||||
### Error Events
|
||||
|
||||
Structured error events for runtime failures.
|
||||
|
||||
### Reasoning/Thinking
|
||||
|
||||
Extended thinking or reasoning content with visibility controls.
|
||||
|
||||
### Command Execution
|
||||
|
||||
Detailed command execution events with stdout/stderr.
|
||||
|
||||
### File Changes
|
||||
|
||||
Structured file modification events with diffs.
|
||||
|
||||
### MCP Tools
|
||||
|
||||
Model Context Protocol tool support.
|
||||
|
||||
### Streaming Deltas
|
||||
|
||||
Native streaming of content deltas. When not supported, the daemon emits a single synthetic delta before `item.completed`.
|
||||
|
||||
## Synthetic Events
|
||||
|
||||
For features not natively supported, the daemon generates synthetic events to maintain a consistent event stream. Synthetic events have:
|
||||
|
||||
- `source: "daemon"`
|
||||
- `synthetic: true`
|
||||
|
||||
This lets you build UIs that work with any agent without special-casing each provider.
|
||||
|
||||
## Request Support
|
||||
|
||||
Want support for another agent? [Open an issue](https://github.com/rivet-dev/sandbox-agent/issues/new) to request it.
|
||||
|
|
@ -62,8 +62,7 @@
|
|||
"pages": [
|
||||
"cli",
|
||||
"inspector",
|
||||
"universal-schema",
|
||||
"agent-compatibility",
|
||||
"session-transcript-schema",
|
||||
"cors",
|
||||
{
|
||||
"group": "AI",
|
||||
|
|
|
|||
|
|
@ -1,13 +1,85 @@
|
|||
---
|
||||
title: "Universal Schema"
|
||||
description: "Reference for the universal event and item schema."
|
||||
title: "Session Transcript Schema"
|
||||
description: "Universal event schema for session transcripts across all agents."
|
||||
icon: "brackets-curly"
|
||||
---
|
||||
|
||||
The universal schema normalizes events from all supported agents (Claude Code, Codex, OpenCode, Amp) into a consistent format. This lets you build UIs and persistence layers that work with any agent without special-casing.
|
||||
Each coding agent outputs events in its own native format. The sandbox-agent converts these into a universal event schema, giving you a consistent session transcript regardless of which agent you use.
|
||||
|
||||
The schema is defined in [OpenAPI format](https://github.com/rivet-dev/sandbox-agent/blob/main/docs/openapi.json). See the [HTTP API Reference](/api-reference) for endpoint documentation.
|
||||
|
||||
## Coverage Matrix
|
||||
|
||||
This table shows which agent capabilities appear in the universal event stream. All agents retain their full native capabilities—this only reflects what's normalized into the schema.
|
||||
|
||||
| Feature | Claude | Codex | OpenCode | Amp |
|
||||
|--------------------|:------:|:-----:|:------------:|:------------:|
|
||||
| Stability | Stable | Stable| Experimental | Experimental |
|
||||
| Text Messages | ✓ | ✓ | ✓ | ✓ |
|
||||
| Tool Calls | ✓ | ✓ | ✓ | ✓ |
|
||||
| Tool Results | ✓ | ✓ | ✓ | ✓ |
|
||||
| Questions (HITL) | ✓ | | ✓ | |
|
||||
| Permissions (HITL) | ✓ | ✓ | ✓ | - |
|
||||
| Images | - | ✓ | ✓ | - |
|
||||
| File Attachments | - | ✓ | ✓ | - |
|
||||
| Session Lifecycle | - | ✓ | ✓ | - |
|
||||
| Error Events | - | ✓ | ✓ | ✓ |
|
||||
| Reasoning/Thinking | - | ✓ | - | - |
|
||||
| Command Execution | - | ✓ | - | - |
|
||||
| File Changes | - | ✓ | - | - |
|
||||
| MCP Tools | - | ✓ | - | - |
|
||||
| Streaming Deltas | ✓ | ✓ | ✓ | - |
|
||||
|
||||
Agents: [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) · [Codex](https://github.com/openai/codex) · [OpenCode](https://github.com/opencode-ai/opencode) · [Amp](https://ampcode.com)
|
||||
|
||||
- ✓ = Appears in session events
|
||||
- \- = Agent supports natively, schema conversion coming soon
|
||||
- (blank) = Not supported by agent
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Text Messages">
|
||||
Basic message exchange between user and assistant.
|
||||
</Accordion>
|
||||
<Accordion title="Tool Calls & Results">
|
||||
Visibility into tool invocations (file reads, command execution, etc.) and their results. When not natively supported, tool activity is embedded in message content.
|
||||
</Accordion>
|
||||
<Accordion title="Questions (HITL)">
|
||||
Interactive questions the agent asks the user. Emits `question.requested` and `question.resolved` events.
|
||||
</Accordion>
|
||||
<Accordion title="Permissions (HITL)">
|
||||
Permission requests for sensitive operations. Emits `permission.requested` and `permission.resolved` events.
|
||||
</Accordion>
|
||||
<Accordion title="Images">
|
||||
Support for image attachments in messages.
|
||||
</Accordion>
|
||||
<Accordion title="File Attachments">
|
||||
Support for file attachments in messages.
|
||||
</Accordion>
|
||||
<Accordion title="Session Lifecycle">
|
||||
Native `session.started` and `session.ended` events. When not supported, the daemon emits synthetic lifecycle events.
|
||||
</Accordion>
|
||||
<Accordion title="Error Events">
|
||||
Structured error events for runtime failures.
|
||||
</Accordion>
|
||||
<Accordion title="Reasoning/Thinking">
|
||||
Extended thinking or reasoning content with visibility controls.
|
||||
</Accordion>
|
||||
<Accordion title="Command Execution">
|
||||
Detailed command execution events with stdout/stderr.
|
||||
</Accordion>
|
||||
<Accordion title="File Changes">
|
||||
Structured file modification events with diffs.
|
||||
</Accordion>
|
||||
<Accordion title="MCP Tools">
|
||||
Model Context Protocol tool support.
|
||||
</Accordion>
|
||||
<Accordion title="Streaming Deltas">
|
||||
Native streaming of content deltas. When not supported, the daemon emits a single synthetic delta before `item.completed`.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Want support for another agent? [Open an issue](https://github.com/rivet-dev/sandbox-agent/issues/new) to request it.
|
||||
|
||||
## UniversalEvent
|
||||
|
||||
Every event from the API is wrapped in a `UniversalEvent` envelope.
|
||||
Loading…
Add table
Add a link
Reference in a new issue