Migration
Migration
Move from the Python Maniac agents SDK to @maniac-ai/agents with compatible payloads and TypeScript-native ergonomics.
Migration
@maniac-ai/agents is a TypeScript port of the Python maniac-agents SDK. As of 0.4.0, the TS package targets feature parity on inference, runtime, observability, background dispatch, and ACP — with a few intentional differences documented below.
What stays the same
- Serialized field names — durable JSON keeps Python-compatible snake_case:
tool_calls,finish_reason,pending_approvals,root_messages,task_id, … - Streaming tool-call merge —
BaseModel.infer()accumulates partial tool-call deltas by index and parses JSON arguments once at the end - HITL pause/resume — batched
pending_approvals,RunCheckpoint, and explicitApprovalResponselists - Python REPL execution — delegated to the subprocess worker, not a Node
vm - Memory abstraction — conversation, observation, checkpoint, and background-task stores share the same
Memoryprotocol
What changes
| Python | TypeScript |
|---|---|
| Callable introspection for tools | Explicit tool({ inputSchema, handler }) |
run_agent, run_agent_stream | runAgent, runAgentStream |
Maniac.resume_checkpoint_stream | Maniac.resumeCheckpointStream |
pip install 'maniac-agents[acp]' | npm install @agentclientprotocol/sdk peer + @maniac-ai/agents/acp |
PostgresMemory adapter | SqliteMemory (@maniac-ai/agents/memory/sqlite) on Node |
maniac acp serve | npx maniac-agents-acp serve |
Method names use TypeScript casing; wire payloads keep Python names.
Topics
- From Python — step-by-step migration checklist
- Parity matrix — area-by-area status and notes
Fixtures
Stable cross-language fixtures live in packages/agents/fixtures/:
schema_roundtrip.json— messages, inference, agent resultstrace_checkpoint.json— trace sequences, HITL checkpoints, streaming tool-call chunks
Use these to validate serializers in either runtime without live provider calls.