بنقرة واحدة
code-snippets
// How to reference code from sample repos in Agent Framework docs pages using :::code directives, snippet tags, zone pivots, and highlight attributes.
// How to reference code from sample repos in Agent Framework docs pages using :::code directives, snippet tags, zone pivots, and highlight attributes.
Required when reviewing, updating, auditing, or creating any concept documentation page. Covers code accuracy checks against source repos, language parity across zone pivots, parity table comments, and structural consistency.
How to configure cross-repository references (CRR) and create API class links for Microsoft Learn docs in this repository.
How breadcrumbs work on Microsoft Learn: structure, creation, configuration in docfx.json, and best practices for documentation repos.
How to delete, rename, or move articles on Microsoft Learn while preserving Platform IDs, preventing broken links, and managing redirects.
Conceptual organization of Agent Framework documentation and samples. For language-specific details (file naming, provider setup, code patterns), see each code repo's skills files.
How to create, structure, and configure table of contents (TOC) files for Microsoft Learn documentation using toc.yml and docfx.json.
| 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. |
This skill describes how to reference code from sample repos in Agent Framework docs pages, eliminating inline code duplication.
:::code language="python" source="~/../agent-framework-code/python/samples/01-get-started/01_hello_agent.py" id="create_agent" highlight="1-4":::
| 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) |
~/agent-framework/<path-to-file>~/../<path_to_root>/<path-to-file>~/../agent-framework-code/python/samples/<section>/<file>.pyIf 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.
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 |
Use the same :::code syntax for CRR snippets as in-repo snippets. Only the source path changes.
~ for docset-root-relative references... segments to move up directories when needed (for example ../../)... 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'sbuild_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.
# <create_agent>
client = OpenAIResponsesClient(...)
agent = client.as_agent(name="...", instructions="...")
# </create_agent>
// <create_agent>
var agent = await client.CreateAIAgentAsync(...);
// </create_agent>
snake_caseEvery 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
Apply :::code references when:
Until then, use inline code blocks (python / csharp) as a temporary measure.
| 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 |