agentlift

Agent runtimes all want your agent in a different shape. agentlift lets you define it once as a neutral .managed-agents/ folder — system prompt, skills, MCP servers, tool allowlist, subagents — then audit, export, or deploy it to Anthropic Managed Agents, AWS Bedrock AgentCore, Google Agent Engine, or OpenAI Agents SDK. And now import reads a live agent back into the folder — so you can migrate between runtimes, not just deploy to them.

Own the definition. Rent the runtime.

It's the folder you already use with Claude Code / the Agent SDK (CLAUDE.md/agent.md + skills/ + .mcp.json + a roster). Nothing new to learn — the thing you have is the input, and it stays yours, not a vendor's.

pip install agentlift
agentlift audit  ./my-agent                  # how portable is it, per provider? (offline)
agentlift deploy ./my-agent                  # → Anthropic Managed Agents (reference target)
agentlift deploy ./my-agent --target bedrock # → AWS Bedrock AgentCore (Claude-native)
agentlift deploy ./my-agent --target google  # → Google Vertex AI Agent Engine (preview)
agentlift export openai-agents ./my-agent    # → an OpenAI Agents SDK script (self-host)
agentlift import anthropic    ./my-agent     # ← read a live agent back into the folder

agentlift not found after install? Run it module-style — python -m agentlift.cli <cmd> (the launcher just landed off PATH; add it if you prefer the short form).

Migrate between runtimes

Because the folder is the neutral pivot, import + deploy is a migration — pull an agent out of one runtime and push it into another:

# Anthropic → AWS Bedrock
agentlift import anthropic ./agent                          # read the live agent into ./agent
agentlift deploy ./agent --target bedrock --mode harness    # redeploy it to AWS Bedrock AgentCore
# (or `agentlift export bedrock-strands ./agent` for a self-host container instead)

# …and back the other way
agentlift import bedrock ./agent --harness-name my-agent --bedrock-region us-west-2
agentlift deploy ./agent                                    # → Anthropic Managed Agents

Anything that doesn't survive a given hop is surfaced as a agentlift plan diagnostic before you deploy — never a silent lossy copy. See docs/import.md for the round-trip details and the one-way limitations.

Why this exists

Adopt a provider's native tooling — Anthropic YAML, a Bedrock Strands container, Google ADK Python, an OpenAI graph — and your agents are now shaped by that provider. The day you want a different runtime, you re-author everything. agentlift makes the deploy unit the same folder you develop against, keeps it provider-neutral, and treats each runtime as a back-end of one compiler. One definition, many backends, no lock-in.

See it happen (a skill that runs in the cloud)

The believable bit isn't "we generated config" — it's that an uploaded skill actually fires inside the hosted runtime. plan is a deterministic, no-network dry run; deploy pushes it; run proves the skill rode along:

$ agentlift plan ./examples/quickstart
Skills to upload: 1
  - receipt-stamp  (035823c8, 1 file)  used by: knowledge-agent
Agents to create: 1
  - knowledge-agent  [claude-haiku-4-5]  tools: read/glob/grep  skills: @skill:035823c8
Deployable: yes

$ agentlift deploy ./examples/quickstart -y
  skill 'receipt-stamp': uploaded skill_01Ph…   agent 'knowledge-agent': created agent_019L…
  Lockfile written: ./examples/quickstart/.agentlift-lock.json

$ agentlift run knowledge-agent --project ./examples/quickstart --task "What is a North Star metric?"
  A North Star metric is the single measure that best captures the value users get…
  RECEIPT: metric captured          ← the uploaded SKILL.md firing inside the hosted runtime
  latency 5.9s | in 4121 out 220 | ~$0.0044

The plan is a pure function of the folder (same input → same plan): it's the dry-run, the diff, and what the offline tests assert against.

The folder is the agent

agentlift reads a convention you may already use. A minimal single agent:

my-agent/.managed-agents/knowledge-agent/
├── agent.md          # YAML frontmatter + system prompt
├── skills/receipt-stamp/SKILL.md   # uploaded as a managed skill
└── knowledge/pm-basics.md          # folded into the system prompt

---
name: knowledge-agent
model: claude-haiku-4-5
tools: [read, glob, grep]      # built-in allowlist (omit = all)
---
You are the Knowledge Agent. Answer product questions concisely.

…and the same convention scales to a multi-agent system — a coordinator, workers, shared and private skills/MCP servers, all wired by frontmatter:

.managed-agents/
├── shared/skills/cite-sources/SKILL.md   # shared skill — uploaded once, used by many
├── shared/mcp.json                        # shared MCP — one server, many agents
├── lead/agent.md                          # subagents: [bug-finder, researcher] → coordinator
├── bug-finder/  (agent.md + skills/bug-report/)     # private skill
└── researcher/  (agent.md + mcp.json)               # private MCP

A bare ref (search) resolves to the agent's own resource first, then shared/. Your local .claude/agents/ are never swept in. Full spec: docs/convention.md.

How it works

parse → plan → apply → run — and only apply/run touch the network.

• parse — read the folder into an in-memory project (pure file IO).
• plan — a deterministic list of API ops with symbolic refs, skill dedup, validation, and diagnostics. No network. This is the dry-run and the test contract.
• apply — upload skills (deduped), create agents in order, write .agentlift-lock.json (local definition → remote IDs) so re-deploys are idempotent. Commit it.
• run — invoke a deployed agent by ID, or run the same folder locally with --local.

Diagnostics surface anything a runtime can't represent — never a silent drop. Internals: docs/how-it-works.md.

Provider snapshot

One folder, four managed-agent runtimes — at different maturity tiers. agentlift audit rates portability per provider before you deploy; the table below is what agentlift ships today:

Runtime	Deploy status	Model	Notes
Anthropic Managed Agents	✅ Live — reference target, fullest mapping	Claude (native)	skills · MCP · :ask · coordinator
AWS Bedrock AgentCore	✅ Live — both primitives: managed Harness (single agent · skills · MCP · sandbox · browser, 6/6 live-verified) and custom-container Runtime (multi-agent; subagent delegation live-verified); the AWS AgentCore feature is in public preview	Claude (native, no remap)	--mode auto routes single→Harness, team→Runtime (deploy-bedrock.md)
Google Vertex AI Agent Engine	🟡 Live (preview)	Claude → Gemini	skills · MCP · web tools; deploy-google.md
OpenAI Agents SDK	📦 Export / self-host	gpt-*	as_tool composition; no hosted-deploy path

Each runtime captures the agent differently (Anthropic YAML, a Strands/AgentCore container, ADK Python, an Agents SDK script) — the full cell-by-cell map is docs/provider-matrix.md. Read the tier before assuming parity: Google is preview; on AWS a single agent deploys to the Harness and a multi-agent team deploys to the custom-container Runtime (both live) — and the Runtime's nested specialist skill/MCP calls are wired + output-corroborated, not independently exercised (the /invocations response is the container's JSON body, not a tool-event stream).

Proof, not assertion

agentlift's claims are pinned by tests and committed live receipts, not prose:

• Live coverage matrix — one neutral fixture deployed + queried on Anthropic and Google, with all six portability dimensions (agents · subagents · shared/individual MCP · shared/individual skill) EXERCISED server-side (committed receipts under tests/live/receipts/).

• AWS Bedrock AgentCore — both primitives live-verified (committed Nova receipts):

  • Harness, 6/6 (single agent): CreateHarness → READY then InvokeHarness exercising agent + base-session sandbox + remote MCP + S3-loaded skill + agentcore_browser.
  • Runtime, multi-agent (the headline): a real team (coordinator + 2 specialists) built to an ARM64 image → ECR → CreateAgentRuntime → READY → InvokeAgentRuntime, with subagent DELEGATION exercised (the coordinator's top-level trace named both specialists); a single-agent smoke separately exercised a root-level MCP call. Nested specialist skill/MCP are wired + text-corroborated (the /invocations body isn't a tool-event stream).
  • Model mapping stays Claude-native; the receipts run on Nova to prove the control plane, container, invocation path, and delegation while Claude-on-Bedrock access is account-gated (a one-time entitlement, not a code gap). Evidence: docs/tested-platforms.md.

• Managed vs local benchmark (benchmarks/results.md, claude-haiku-4-5):

  Arm	Pass rate	Median latency	Avg cost
  managed (cloud)	100% on N=5 runs	5.9s	$0.0052
  local (your machine)	100% on N=5 runs	2.3s	$0.0034

  Pass = the uploaded skill fired and the answer was on-topic. Same folder, two runtimes, identical behavior.

pytest -m "not live"   # deterministic translation + idempotency — no API key, runs in CI
pytest -m live         # deploy to the real API, run, LLM-grade (needs credentials)

What you get, briefly

• Isolation by construction — a deployed agent gets only its own folder (+ shared/); the repo-root CLAUDE.md, a sibling's skills, and your machine's MCP servers can't leak in. Pinned by tests/test_isolation.py.
• Permissions that deploy — append :ask to any tool (bash:ask, create_issue:ask) and the hosted agent pauses for caller approval — the deployable form of a hook.
• Deploy how you work — a command (deploy --yes), a git-push workflow, or from inside Claude Code. Idempotent via the lockfile.
• A full CLI — validate · plan · audit · export · diff · deploy · import · run · list · destroy · bench. See docs/deploying.md.
• Round-trip, so you can migrate — import reads a live Anthropic agent (or a Bedrock harness) back into the folder; deploy it elsewhere and the folder is the neutral pivot. See docs/import.md.

Documentation

Doc	What's in it
docs/convention.md	The .managed-agents/ folder spec — frontmatter, skills, MCP, :ask, subagents
docs/how-it-works.md	parse → plan → apply → run, determinism, idempotency, the lockfile
docs/import.md	import — read a live agent back into the folder; the round-trip + migration story, one-way losses
docs/deploying.md	The three deploy paths, commands, the lockfile, install/PATH
docs/provider-matrix.md	Cell-by-cell capability matrix across all four runtimes
docs/anthropic-mapping.md	Exact local → Managed Agents field mapping
docs/deploy-bedrock.md · deploy-google.md	Per-provider credentials, gates, and caveats
docs/tested-platforms.md	Per-platform live receipts + reproduce steps
docs/limitations.md	Honest constraints (stdio MCP, MCP auth, knowledge inlining)

Examples: quickstart/ (one agent) · team/ (coordinator + roster, shared skill, MCP, bash:ask) · in-a-project/ (embedded in a real repo, proves isolation) · deploy-workflow/ · claude-code-skill/.

Limitations

Each is surfaced as a agentlift plan diagnostic, never a silent surprise — full list in docs/limitations.md:

• Remote MCP only — local stdio servers (npx …) can't be deployed; host behind HTTPS.
• No inline MCP auth on Anthropic (Bedrock + Google carry it via runtime env vars).
• Knowledge files are inlined into the system prompt (no persistent FS in the sandbox).
• Maturity varies — Anthropic is live/full; AWS is live on both AgentCore primitives (Harness single-agent + Runtime multi-agent; the AgentCore feature is in AWS preview); Google is live preview; OpenAI is export-only.
• Runtime nested-tool visibility — on the AWS Runtime, subagent delegation is objectively traced, but a specialist's internal skill/MCP calls don't cross the /invocations boundary (wired + output-corroborated, not independently exercised).
• Import is read-only, and one-way in places — import reads Anthropic (full) and the Bedrock harness back into the folder; a Bedrock Runtime is an opaque container and refuses. Knowledge inlining, custom tools, and MCP auth values don't round-trip (each flagged as a diagnostic). See docs/import.md.

Roadmap

Current focus: a same-Claude-brain AWS receipt (Gate A: the one-time Anthropic use-case entitlement — the hosted Runtime + Harness are already live-proven on Nova), surfacing the Runtime's nested specialist tool calls past the /invocations boundary, and a self-hostable openai-chatkit export. Per-provider gaps and status live in their deploy docs and docs/provider-matrix.md.

License

MIT — see LICENSE.