DOC write doc page on how to create a new target

[romanlutz]

Describe the issue linked to the documentation

This is a common question. The page should at least describe

• all the requirements for a target
• multi-turn vs single-turn targets
• an actual example of how to adjust AML target or another one to a different HTTP based endpoint

Suggest a potential alternative/fix

[Xabilimon1]

I would like to take this.

Quick plan before drafting.

New page at doc/code/targets/12_creating_a_target.py (jupytext-paired with .ipynb like the rest of the folder; trailing slot so I don't renumber the OpenAI sequence at 1–5).

Three sections:

1. Requirements: subclassing PromptTarget vs PromptChatTarget, overriding _send_prompt_to_target_async (since send_prompt_async is @final on the base), TargetCapabilities plus TargetRequirements, identifier and memory wiring. Linking 6_1_target_capabilities instead of restating.
2. Single-turn vs multi-turn: when PromptChatTarget is the right base, conversation state, what breaks if you pick wrong.
3. Worked example: porting AzureMLChatTarget to a different HTTP endpoint as the issue asks. Auth, payload shape, response parsing, error handling.

Out of scope: 6_custom_targets (Gandalf-specific), 10_http_target (generic HTTP), and the executor docs touched by #1979.

Draft PR in about a week. One question: fine to point the worked example at a generic HTTP shape, or do you want it hitting a real public endpoint readers can run?

[Xabilimon1]

Quick correction on my own comment — PromptChatTarget is deprecated since 0.14.0 and removed in 0.16.0. The right framing for the multi-turn section is when to declare supports_multi_turn=True (and supports_editable_history=True) on TargetConfiguration directly, not when to inl write section 2 that way.

[Xabilimon1]

if the outline above is more than you'd want to greenlight on text alone, happy to push a draft PR you can review concretely instead. or fold into 6_custom_targets if a standalone tutorial isn't the right shape. no rush.

[romanlutz]

Thanks for reaching out. You're right about the deprecation of PromptChatTarget. I suspect this doc page can only be written by a maintainer because it might require more contextualization based on many requests we've had to create custom targets, and perhaps also requires rewriting the custom targets section. CC @rlundeen2 who's rewritten quite a few doc pages recently. I'll remove the tag "help wanted" for the time being.

[Xabilimon1]

All good, totally fair call. I'd already written sections 1 and 2 locally (the requirements contract + the multi-turn capability declaration with the deprecation framing). happy to share what's there as a starting point if it'd save @rlundeen2 any time; otherwise I'll close my loop here. thanks for the quick reply.