Skip to content

DOC write doc page on how to create a new target #642

Closed

Description

@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

Activity

  1. Xabilimon1 commented on Jun 18, 2026

    @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?

  2. Xabilimon1 commented on Jun 18, 2026

    @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.

  3. Xabilimon1 commented on Jun 22, 2026

    @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.

  4. romanlutz commented on Jun 22, 2026

    @romanlutz
    ContributorAuthor

    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.

  5. added
    documentationImprovements or additions to documentation
    and removed
    help wantedExtra attention is needed
    on Jun 22, 2026
  6. Xabilimon1 commented on Jun 22, 2026

    @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.

  7. romanlutz commented on Nov 18, 2026

    @romanlutz
    ContributorAuthor

    Closing as completed: the page this issue asks for now exists.

    Creating Custom Targets was rewritten as a self-contained guide in #3467. Against the three things requested here:

    • All the requirements for a target: covered by the "Anatomy of a custom target" section (keyword-only __init__, implementing _send_prompt_to_target_async, rate limiting, _build_identifier, declaring capabilities, and not overriding send_prompt_async).
    • Multi-turn vs single-turn targets: covered by the capabilities item in that section, which links to the dedicated Target Capabilities page.
    • An example of adapting a target to a different HTTP endpoint: partly covered. The page sends readers with a plain HTTP endpoint to HTTPTarget first, and then walks through a complete, runnable custom target and red-teams it. That example wraps a simulated application rather than making a raw HTTP call.

    If a worked raw-HTTP example is still wanted, please open a new, narrower issue for just that. #4144 (open) adds documentation on in-process agents as custom targets.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions