code-snippets

name	code-snippets
description	How to reference code from sample repos in Agent Framework docs pages using :::code directives, snippet tags, zone pivots, and highlight attributes.

Skill: Code Snippets in Docs

Purpose

This skill describes how to reference code from sample repos in Agent Framework docs pages, eliminating inline code duplication.

:::code Directive Syntax

:::code language="python" source="~/../agent-framework-code/python/samples/01-get-started/01_hello_agent.py" id="create_agent" highlight="1-4":::

Parameters

Parameter	Required	Description
language	Yes	"python" or "csharp"
source	Yes	Snippet file path using docset-relative syntax (for example ~/... or ~/../<dependent-repo>/...)
id	No	Matches a snippet tag in source (# <name> / # </name> for Python, // <name> / // </name> for C#)
range	No	Line range (e.g. "2-24,26"). Cannot coexist with id
highlight	No	Lines to highlight, relative to the displayed snippet (not the file)

Source Path Conventions

• In-repo snippets: ~/agent-framework/<path-to-file>
• Out-of-repo snippets (dependent repositories): ~/../<path_to_root>/<path-to-file>
• Agent Framework code samples in this repo: ~/../agent-framework-code/python/samples/<section>/<file>.py

Out-of-repo snippet references

If the code file you want to reference is in a different repository, set up that code repository as a dependent repository in .openpublishing.publish.config.json. The path_to_root you assign acts like a folder name for snippet source paths.

Dependent repositories metadata

The dependent_repositories list is required in .openpublishing.publish.config.json for cross-repository references (CRR):

{
  "dependent_repositories": [
    {
      "path_to_root": "<relative path to repository root>",
      "url": "<referenced repository url>",
      "branch": "<branch name of referenced repository>",
      "branch_mapping": {
        "<source repository branch>": "<referenced repository branch>",
        "<source repository branch>": "<referenced repository branch>"
      }
    },
    {
      "path_to_root": "token",
      "url": "https://github.com/Microsoft/token",
      "branch": "main",
      "branch_mapping": {
        "main": "main",
        "develop": "test"
      }
    }
  ]
}

Metadata	Meaning	Required
dependent_repositories	The CRR relationship list name	Yes
path_to_root	Relative folder path to the repository root (folder can be virtual)	Yes
url	URL of the reference repository this repo depends on	Yes
branch	Default branch of the reference repository for builds	Yes
branch_mapping	Optional source-branch to reference-branch map	No

Snippet reference syntax

Use the same :::code syntax for CRR snippets as in-repo snippets. Only the source path changes.

• Start paths with ~ for docset-root-relative references.
• Use .. segments to move up directories when needed (for example ../../).
• Prefer readable paths; deeply nested .. chains are harder to maintain.

Example CRR source path:

~/../xamarin-forms-samples/WebServices/TodoREST/TodoAPI/TodoAPI/Startup.cs

[!NOTE] The dependent repository alias is rooted at repo root, but ~ is rooted at the docset's build_source_folder. In this repo, Agent Framework docs use "build_source_folder": "agent-framework", so dependent repositories are referenced like ~/../agent-framework-code/....

[!IMPORTANT] Updating an external code snippet does not automatically trigger a content build. Trigger a build by changing doc content or starting a build manually.

Snippet Tags in Source Files

Python

# <create_agent>
client = OpenAIResponsesClient(...)
agent = client.as_agent(name="...", instructions="...")
# </create_agent>

C#

// <create_agent>
var agent = await client.CreateAIAgentAsync(...);
// </create_agent>

Rules

• Tag names use snake_case
• Tags must be unique within a file
• Tags cannot overlap or nest
• Keep snippet regions small and focused (5-20 lines ideal)
• Include all necessary imports within the snippet OR document them separately

Zone Pivots

Every page showing code for both languages uses zone pivots:

:::zone pivot="programming-language-csharp"
:::code language="csharp" source="~/../agent-framework-code/dotnet/samples/..." id="...":::
:::zone-end

:::zone pivot="programming-language-python"
:::code language="python" source="~/../agent-framework-code/python/samples/..." id="...":::
:::zone-end

When to Apply This Skill

Apply :::code references when:

1. The sample repo structure is stable (samples merged to main)
2. The sample file has proper snippet tags
3. You want to eliminate inline code duplication

Until then, use inline code blocks (python / csharp) as a temporary measure.

Common Snippet IDs

ID	Purpose	Typical file
create_agent	Agent instantiation	01_hello_agent.py
run_agent	Non-streaming run	01_hello_agent.py
run_agent_streaming	Streaming run	01_hello_agent.py
define_tool	Tool definition	02_add_tools.py
create_agent_with_tools	Agent + tools	02_add_tools.py
multi_turn	Thread-based conversation	03_multi_turn.py
context_provider	Memory/context setup	04_memory.py
create_workflow	Workflow builder	05_first_workflow.py

Reference

• MS Learn code-in-docs guide