[tracisiebel]

Summary

Adds agentcontrol/legacy-sdk-migrate, an agent skill version of Migrate from the legacy AI SDKs, so customers can have an agent move them from launchdarkly-server-sdk-ai / @launchdarkly/server-sdk-ai to the current handler-based SDKs.

• Explore → Assess → Execute → Verify workflow: inventory legacy calls (LDAIClient, initAi, completion_config, agent_config, trackers, judges, graphs), map each to a convenience function, config().invoke(), or graph(), then confirm no legacy references remain
• Covers packages, lazy init / init_client(), tools and Registry, streaming and history, async judges (skip_judges + run_judge()), graphs (graph(), resolve_graph() + native runners)
• Fallbacks: there's no fallback argument and invoke() raises when the variation is disabled, so the skill ports enabled=False branches to error handling and inspect_config() / inspectConfig()
• references/api-mapping.md: before/after code in Python and Node.js
• README row, CHANGELOG entry, regenerated skills.json

Testing

• Not applicable
• Manual (describe below)

python3 scripts/validate_skills.py, python3 -m unittest discover -s tests, python3 scripts/generate_catalog.py --check, and (cd evals && npm test) all pass. API and package names checked against launchdarkly/python-ai-sdk and launchdarkly/js-ai-sdk source.

Notes

Details

• Doc discrepancy: the migration page uses createOpenAIHandler, createOpenAIAgentHandler, and create_openai_agent_handler, which aren't exported. The SDKs export createOpenAIMessagesHandler, createOpenAIAgentsHandler, and create_openai_agents_handler. The skill uses the exported names and warns agents about the mismatch. The docs page should be fixed separately.
• Not covered by the guide: the current SDKs have no track_feedback / trackFeedback equivalent, so the skill tells the agent to flag the gap to the user instead of deleting those calls.
• Separate from agentcontrol/migrate, which moves hardcoded prompts into AgentControl. Related open PRs fix(migrate): roll forward to the new AI SDK #218, fix(built-in-metrics): roll forward to the new AI SDK #219, and fix(tools): roll forward to the new AI SDK #221 update other skills to the new SDK and don't overlap with this one.
• Not added to the curated .claude-plugin/plugin.json list, matching migrate. Codex and Cursor pick it up from the directory.
• No evals suite in this PR.

Link to Devin session: https://app.devin.ai/sessions/d950e07d53954b9880874f06e845ac40
Open in Devin Desktop: https://app.devin.ai/desktop/session/d950e07d53954b9880874f06e845ac40?variant=devin
Requested by: @tracisiebel

---

Note

Overview
Adds agentcontrol/legacy-sdk-migrate 0.1.0, an agent playbook for upgrading apps already on launchdarkly-server-sdk-ai / @launchdarkly/server-sdk-ai to the handler-based SDKs (config().invoke(), handler packages, Registry, graph()).

The skill follows Explore → Assess → Execute → Verify: inventory legacy APIs, map them to current patterns (including fallbacks via inspect_config, durable background judges, and track_data for feedback), and verify no legacy references remain. references/api-mapping.md supplies Python and Node before/after examples. The catalog is updated in skills.json, README.md (new row; migrate description clarified as hardcoded-prompt onboarding), and CHANGELOG.md.

tests/test_legacy_sdk_migrate.py asserts the skill and reference docs require explicit judge metric tracking and discourage fire-and-forget run_judge usage.

^{Reviewed by Cursor Bugbot for commit f4f7015. Bugbot is set up for automated code reviews on this repo. Configure here.}

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring

[github-actions]

Skill eval results

Skill	Before	After	Δ
agentcontrol/configs-create	100/100 (4/4)	75/100 (3/4)	-25
agentcontrol/configs-update	80/100 (4/5)	100/100 (5/5)	+20
agentcontrol/configs-variations	80/100 (4/5)	80/100 (4/5)	no change
agentcontrol/tools	75/100 (3/4)	75/100 (3/4)	no change
aws-devops-agent/experiment-orchestration	-	100/100 (9/9)	new
experiments/launchdarkly-experiment-guide	-	100/100 (5/5)	new
experiments/launchdarkly-experiment-hypothesis-builder	-	100/100 (13/13)	new
experiments/launchdarkly-experiment-setup	-	100/100 (8/8)	new
feature-flags/flag-and-release-change	-	100/100 (4/4)	new
feature-flags/flag-release	-	80/100 (4/5)	new
feature-flags/launchdarkly-flag-command	-	100/100 (3/3)	new
feature-flags/launchdarkly-flag-create	100/100 (3/3)	100/100 (4/4)	no change
feature-flags/launchdarkly-flag-drift	-	100/100 (4/4)	new
feature-flags/should-flag-change	-	100/100 (17/17)	new
onboarding	-	86/100 (6/7)	new
release-autopilot/launchdarkly-release-autopilot-onboarding	-	92/100 (34/37)	new

Only suites whose source actually changed since their last recorded score were re-run. Soft-failing while we stabilise the baseline.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 3 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit d7c0bf3. Configure here.}

[jeffdupont]

Approving. I tested the skill end to end. A fresh agent that saw only SKILL.md and references/api-mapping.md migrated two realistic legacy apps, one Python (launchdarkly-server-sdk-ai 1.2.0) and one Node.js (@launchdarkly/server-sdk-ai 2.0.20). Each app covers a completion config with variables, token/duration/success tracking, thumbs-up feedback, an agent with a hand-written tool loop, a disabled-config fallback, a judge and (Node) streaming.

• The migrated code passes mypy --strict and tsc --strict against the published launchdarkly-ai-server 1.1.0 and @launchdarkly/ai-server 1.1.0 / @launchdarkly/ai-node 1.0.1 with the OpenAI handlers.
• Run against test-data flags and a local OpenAI stub, it returns the same results as the legacy code in every scenario, including the fallback. It emits the same LaunchDarkly metric events with the same values and track data: tokens, duration, success, tool_call, and the feedback events through get_client().track() / getClient().track(). Node streaming now also reports tokens.
• validate_skills.py, the catalog check and the new unit test pass. That test only checks that some phrases are present, so it doesn't exercise the examples.

Worth fixing (none block):

1. Graph event keys (SKILL.md:122, api-mapping.md:568). The current legacy SDKs already emit $ld:ai:graph:handoff_success/handoff_failure, invocation_success/invocation_failure, total_tokens and $ld:ai:tool_call, the same keys as 1.x (ldai/tracker.py:553-796; the same in the Node package). Only $ld:ai:graph:path → $ld:ai:graph:node changed, and redirect is gone. As written, the note tells users to rebuild metrics that already work.
2. Node background-judge example (api-mapping.md:520). runJudge(task, handlers) uses handlers without defining it, unlike the Python example. Copied as is, it won't compile.
3. Python names in Node guidance. setting_sources should be settingSources for createClaudeAgentsHandler() (SKILL.md:124). graph.run_node / edge.target_key should be runNode / targetKey in Node (SKILL.md:122, api-mapping.md:567-568).
4. Deleting the tool loop can silently lose behaviour (api-mapping.md:338). If the app defined a tool's schema in code and the variation in LaunchDarkly doesn't have it, the migrated agent runs without the tool and nothing fails. A line asking the agent to confirm each tool exists on the variation would help. The same applies to a step cap or default model the old loop set.
5. get_client().track() with a dict (SKILL.md:100). It isn't silently dropped. It raises AttributeError: 'dict' object has no attribute 'valid'. The fix the skill gives, Context.from_dict(...), is right; only the description of the failure is off.

Nits:

• The Step 1 search list misses track_judge_result / trackJudgeResult, trackToolCall (Node), the feedback enums, and AICompletionConfigDefault / AIAgentConfigDefault.
• Judges attached to a variation run on every invoke(). An app that judged only some calls on a config will now judge all of them, so mentioning skip_judges there would help.
• In Node, the app's existing LDContext type from @launchdarkly/node-server-sdk doesn't type-check as the context argument. A plain object literal does.
• The branch conflicts with main in CHANGELOG.md and skills.json, so it needs a rebase before merge.

[devin-ai-integration]

@jeffdupont thanks for the end-to-end run. I addressed all of the review in f4f7015 and merged main in f0e502f, so the CHANGELOG.md / skills.json conflicts are gone.

1. Graph event keys: I checked the legacy Python tracker against the current SDK, and you're right. The notes in SKILL.md and api-mapping.md now say that only $ld:ai:graph:path → $ld:ai:graph:node changed and $ld:ai:graph:redirect is gone. They tell the user to update only the metrics built on those two keys.
2. Node runJudge: the example now imports createOpenAIMessagesHandler and defines const handlers = [...].
3. Node names: added settingSources, runNode and targetKey next to the Python names.
4. Tool loop: before the agent deletes the loop, it now confirms that each tool defined in code exists on every variation, and does the same for a step cap or default model the old loop set.
5. get_client().track() with a dict: the text now says it raises AttributeError: 'dict' object has no attribute 'valid'.

Nits: the Step 1 search list now has track_judge_result / trackJudgeResult, trackToolCall(s), FeedbackKind / LDFeedbackKind and AICompletionConfigDefault / AIAgentConfigDefault. The judges section says to use skip_judges / skipJudges on calls that shouldn't be judged. Step 3 says to pass a plain object literal instead of the node-server-sdk LDContext type.

validate_skills.py, the unit tests, generate_catalog.py --check and the evals' npm test (218 tests) pass locally.

Written by Devin