Author Samples

Author samples for new ai-projects features

When to Use

• After apply-post-emitter-edits has merged in new public API surface.
• The diff of review/ai-projects-node.api.md shows new classes, methods, or namespaces.
• A new agent tool, operation, or namespace was added that has no example yet under samples-dev/.

Inputs

• The current API surface report: review/ai-projects-node.api.md.
• The previous version of that file (git show HEAD:review/ai-projects-node.api.md).
• Existing samples under samples-dev/ — used as style/voice anchors.

Procedure

Run from sdk/ai/ai-projects/.

Step 1: Diff the API surface

Use the bundled prompt to identify additions:

prompts/diff-api-surface.prompt.md

Concretely:

git diff HEAD -- review/ai-projects-node.api.md > /tmp/api-surface.diff

Extract added items only (lines beginning with + that declare a class, method, namespace, or interface). Ignore reformatting noise.

Step 2: Bucket each addition

Map each new feature to one of the existing samples-dev/ subfolders. Existing buckets:

agents/, assets/, chatCompletions/, connections/, conversations/, datasets/, deployments/, evaluations/, files/, finetuning/, indexes/, mcpTools/, memories/, redTeam/, responses/, skills/, telemetry/, toolboxes/

If a new feature does not fit any existing bucket, create a new lowercase subfolder and surface the choice to the human.

Step 3: Generate the sample

For each bucketed feature, produce a samples-dev/<bucket>/<featureName>.ts file from templates/sample-skeleton.ts. Conventions taken from existing samples (samples-dev/agents/agentBasic.ts is the canonical reference):

• Header: copyright comment, then a TSDoc block with @summary and @azsdk-weight.
• Import DefaultAzureCredential from @azure/identity and AIProjectClient from @azure/ai-projects.
• Import "dotenv/config" for env loading.
• Pull endpoint and model from process.env["FOUNDRY_PROJECT_ENDPOINT"] and process.env["FOUNDRY_MODEL_NAME"].
• Define export async function main(): Promise<void> and end with main().catch((err) => { console.error("Sample failed: ", err); });.
• Use console.log to narrate each step.

Step 4: Validate

npm run build:samples

Must succeed. If it fails, fix the sample (do not loosen lint/tsc). Also run npm run check-format and npm run format if needed.

Step 5: Hand off

Done. Next: the author-tests skill (for non-beta additions only) and then update-changelog.

Notes

• Do not author samples for project.beta.* additions unless explicitly asked — beta surface is allowed to stay sample-less. (Beta samples that already exist in samples-dev/ like agents/betaAgents.ts are fine; just don't add new ones reflexively.)
• Match the voice of nearby samples in the same bucket. Read at least one neighboring file before writing.
• Samples must be runnable end-to-end against a real Foundry project; do not mock.
• Watch for cascade renames from apply-post-emitter-edits. If a method on the public surface was renamed in the customization layer (e.g. listSessionFiles → getSessionFiles), npm run build:samples will fail in existing samples that called the old name. Fix the call site in the existing sample as part of this skill — do not revert the rename. Cross-reference the rename table in ../apply-post-emitter-edits/references/post-emitter-workarounds.md before debugging build failures.