From 1c4e3c7b59175a8edef5db9ef302cd56e13f9031 Mon Sep 17 00:00:00 2001 From: Owen Kaplan Date: Mon, 11 May 2026 16:48:53 -0400 Subject: [PATCH 1/5] feat: add code source references and related page tagging; emits Related/Implementation blocks into //index.md and /llms-full.txt, and JSON-LD TechArticle keywords + relatedLink into ; No visible change; all headless updates --- src/components/overrides/Head.astro | 38 +++++++- src/config/tags.ts | 25 ++++++ src/config/tags.yml | 42 +++++++++ src/content.config.ts | 12 +++ .../user-guide/concepts/agents/agent-loop.mdx | 5 ++ .../agents/conversation-management.mdx | 6 ++ .../docs/user-guide/concepts/agents/hooks.mdx | 10 +++ .../user-guide/concepts/agents/prompts.mdx | 5 ++ .../concepts/agents/retry-strategies.mdx | 6 ++ .../concepts/agents/session-management.mdx | 6 ++ .../docs/user-guide/concepts/agents/state.mdx | 6 ++ .../concepts/agents/structured-output.mdx | 6 ++ .../bidirectional-streaming/agent.mdx | 4 + .../bidirectional-streaming/events.mdx | 4 + .../bidirectional-streaming/hooks.mdx | 4 + .../bidirectional-streaming/interruption.mdx | 4 + .../concepts/bidirectional-streaming/io.mdx | 6 ++ .../models/gemini_live.mdx | 4 + .../models/nova_sonic.mdx | 4 + .../models/openai_realtime.mdx | 4 + .../session-management.mdx | 4 + .../docs/user-guide/concepts/interrupts.mdx | 5 ++ .../model-providers/amazon-bedrock.mdx | 6 ++ .../concepts/model-providers/amazon-nova.mdx | 4 + .../concepts/model-providers/anthropic.mdx | 5 ++ .../model-providers/custom_model_provider.mdx | 5 ++ .../concepts/model-providers/google.mdx | 5 ++ .../concepts/model-providers/litellm.mdx | 3 + .../concepts/model-providers/llamaapi.mdx | 3 + .../concepts/model-providers/llamacpp.mdx | 3 + .../concepts/model-providers/mistral.mdx | 3 + .../concepts/model-providers/ollama.mdx | 3 + .../model-providers/openai-responses.mdx | 5 ++ .../concepts/model-providers/openai.mdx | 5 ++ .../concepts/model-providers/sagemaker.mdx | 4 + .../concepts/model-providers/vercel.mdx | 3 + .../concepts/model-providers/writer.mdx | 3 + .../concepts/multi-agent/agent-to-agent.mdx | 10 +++ .../concepts/multi-agent/agents-as-tools.mdx | 6 ++ .../user-guide/concepts/multi-agent/graph.mdx | 6 ++ .../multi-agent/multi-agent-patterns.mdx | 6 ++ .../user-guide/concepts/multi-agent/swarm.mdx | 6 ++ .../concepts/multi-agent/workflow.mdx | 1 + .../concepts/plugins/context-offloader.mdx | 5 ++ .../user-guide/concepts/plugins/index.mdx | 9 ++ .../user-guide/concepts/plugins/skills.mdx | 5 ++ .../user-guide/concepts/plugins/steering.mdx | 5 ++ .../concepts/streaming/async-iterators.mdx | 4 + .../concepts/streaming/callback-handlers.mdx | 4 + .../user-guide/concepts/streaming/index.mdx | 6 ++ .../concepts/tools/custom-tools.mdx | 6 ++ .../user-guide/concepts/tools/executors.mdx | 8 ++ .../docs/user-guide/concepts/tools/index.mdx | 6 ++ .../user-guide/concepts/tools/mcp-tools.mdx | 8 ++ .../concepts/tools/vended-tools.mdx | 10 +++ .../deploy/deploy_to_amazon_ec2.mdx | 1 + .../deploy/deploy_to_amazon_eks.mdx | 1 + .../deploy/deploy_to_aws_apprunner.mdx | 1 + .../deploy/deploy_to_aws_fargate.mdx | 1 + .../deploy/deploy_to_aws_lambda.mdx | 1 + .../deploy_to_bedrock_agentcore/index.mdx | 1 + .../deploy_to_bedrock_agentcore/python.mdx | 1 + .../typescript.mdx | 1 + .../deploy/deploy_to_docker/index.mdx | 1 + .../deploy/deploy_to_docker/python.mdx | 1 + .../deploy/deploy_to_docker/typescript.mdx | 1 + .../deploy/deploy_to_kubernetes.mdx | 1 + .../user-guide/deploy/deploy_to_terraform.mdx | 1 + .../deploy/operating-agents-in-production.mdx | 1 + .../observability-evaluation/evaluation.mdx | 1 + .../observability-evaluation/logs.mdx | 4 + .../observability-evaluation/metrics.mdx | 6 ++ .../observability.mdx | 6 ++ .../observability-evaluation/traces.mdx | 6 ++ .../docs/user-guide/quickstart/overview.mdx | 1 + .../docs/user-guide/quickstart/python.mdx | 1 + .../docs/user-guide/quickstart/typescript.mdx | 1 + .../user-guide/safety-security/guardrails.mdx | 4 + .../safety-security/pii-redaction.mdx | 1 + .../safety-security/prompt-engineering.mdx | 1 + .../safety-security/responsible-ai.mdx | 1 + src/util/related-docs.ts | 57 ++++++++++++ src/util/render-to-markdown.ts | 45 +++++++++- test/related-docs.test.ts | 86 +++++++++++++++++++ 84 files changed, 613 insertions(+), 3 deletions(-) create mode 100644 src/config/tags.ts create mode 100644 src/config/tags.yml create mode 100644 src/util/related-docs.ts create mode 100644 test/related-docs.test.ts diff --git a/src/components/overrides/Head.astro b/src/components/overrides/Head.astro index 7f9ce3f62..bad502f46 100644 --- a/src/components/overrides/Head.astro +++ b/src/components/overrides/Head.astro @@ -4,8 +4,10 @@ * and structured data (JSON-LD). * See ARCHITECTURE.md for details. */ +import { getCollection } from 'astro:content' import SiteScripts from '../SiteScripts.astro' import { baseSchemas } from '../../util/structured-data' +import { relatedUserGuideFor } from '../../util/related-docs' const { head } = Astro.locals.starlightRoute const route = Astro.locals.starlightRoute @@ -60,6 +62,39 @@ const breadcrumbItems = pathSegments.map((segment, i) => { } }) +// TechArticle node for docs pages with tags or sourceLinks. +// Reaches HTML-only crawlers that don't follow the llms.txt convention. +const entry = route.entry +// Non-docs routes (blog authors/tags pages, etc.) flow through Starlight too +// but their synthetic entry.data has no `tags` field — guard with ??. +const tags = entry.data.tags ?? [] +const sourceLinks = entry.data.sourceLinks ?? [] +let techArticle: Record | null = null +if (tags.length > 0 || sourceLinks.length > 0) { + const related = tags.length > 0 + ? relatedUserGuideFor(entry, await getCollection('docs')) + : [] + techArticle = { + "@type": "TechArticle", + "headline": entry.data.title, + "url": siteUrl + Astro.url.pathname, + ...(tags.length > 0 ? { "keywords": tags.join(', ') } : {}), + ...(entry.data.description ? { "description": entry.data.description } : {}), + ...(related.length > 0 + ? { "relatedLink": related.map((r) => siteUrl + '/' + r.slug + '/') } + : {}), + ...(sourceLinks.length > 0 + ? { + "isBasedOn": sourceLinks.map((s: { repo: string, path: string }) => ({ + "@type": "SoftwareSourceCode", + "codeRepository": `https://github.com/strands-agents/${s.repo}`, + "url": `https://github.com/strands-agents/${s.repo}/blob/main/${s.path}`, + })), + } + : {}), + } +} + const structuredData = { "@context": "https://schema.org", "@graph": [ @@ -67,7 +102,8 @@ const structuredData = { { "@type": "BreadcrumbList", "itemListElement": breadcrumbItems - } + }, + ...(techArticle ? [techArticle] : []), ] } --- diff --git a/src/config/tags.ts b/src/config/tags.ts new file mode 100644 index 000000000..5693f782b --- /dev/null +++ b/src/config/tags.ts @@ -0,0 +1,25 @@ +import fs from 'node:fs' +import { fileURLToPath } from 'node:url' +import yaml from 'js-yaml' +import { z } from 'astro/zod' + +const TAGS_YML = fileURLToPath(new URL('./tags.yml', import.meta.url)) + +function loadAllowedTags(): readonly string[] { + const raw = yaml.load(fs.readFileSync(TAGS_YML, 'utf-8')) + if (!Array.isArray(raw) || !raw.every((t): t is string => typeof t === 'string')) { + throw new Error(`[tags] ${TAGS_YML} must be a flat YAML list of strings`) + } + const deduped = Array.from(new Set(raw)) + if (deduped.length !== raw.length) { + const dupes = raw.filter((t, i) => raw.indexOf(t) !== i) + throw new Error(`[tags] ${TAGS_YML} contains duplicate entries: ${[...new Set(dupes)].join(', ')}`) + } + return deduped +} + +export const ALLOWED_TAGS = loadAllowedTags() + +export const TagSchema = z.enum(ALLOWED_TAGS as readonly [string, ...string[]]) + +export type Tag = z.infer diff --git a/src/config/tags.yml b/src/config/tags.yml new file mode 100644 index 000000000..a21a6fbfd --- /dev/null +++ b/src/config/tags.yml @@ -0,0 +1,42 @@ +# Allowed tag vocabulary for user-guide pages. +# +# Tags drive the build-time "Related pages" block. A page's `tags` frontmatter +# is validated against this list by the docs schema (src/content.config.ts) — +# unknown tags fail the build. +# +# Scoring: `more shared tags = more related`. Aim for 2–4 tags per page drawn +# from different axes below so pages naturally connect along topic, capability, +# lifecycle, and audience dimensions. +# +# Adding a tag = PR editing this file in the same change that first uses it. + +# Topics / domains — specific products, protocols, data types +- agentcore +- aws +- bedrock +- guardrails +- mcp +- pii + +# Capabilities — what the page teaches the reader to do +- conversation-management +- hooks +- multi-agent +- retry +- session-management +- state +- streaming +- structured-output +- tools + +# Lifecycle / practice — where in the dev lifecycle this sits +- deployment +- evaluation +- observability +- production +- quickstart +- safety + +# Audience — language-specific pages +- python +- typescript diff --git a/src/content.config.ts b/src/content.config.ts index 95caec836..af7705634 100644 --- a/src/content.config.ts +++ b/src/content.config.ts @@ -6,6 +6,7 @@ import { docsSchema } from '@astrojs/starlight/schema' import { slug as githubSlug } from 'github-slugger' import { glob, file } from 'astro/loaders' import { normalizePathToSlug } from './util/links' +import { TagSchema } from './config/tags' const authorSchema = z.object({ name: z.string(), @@ -14,6 +15,12 @@ const authorSchema = z.object({ avatar: z.string().optional(), }) +export const sourceLinkSchema = z.object({ + repo: z.enum(['sdk-python', 'sdk-typescript']), + path: z.string(), +}) +export type SourceLink = z.infer + const blogSchema = z.object({ title: z.string(), date: z.coerce.date(), @@ -89,6 +96,11 @@ export const collections = { description: z.string().optional(), // Array of slugs that should redirect to this page (e.g., old URLs) redirectFrom: z.array(z.string()).optional(), + // Tags from src/config/tags.yml — drive the build-time "Related pages" block + tags: z.array(TagSchema).default([]), + // Pointers to the SDK implementation behind this page. Rendered as an + // "Implementation" section on headless surfaces only (index.md, llms-full.txt). + sourceLinks: z.array(sourceLinkSchema).optional(), }), }), }), diff --git a/src/content/docs/user-guide/concepts/agents/agent-loop.mdx b/src/content/docs/user-guide/concepts/agents/agent-loop.mdx index 52f9c8d25..bb565123b 100644 --- a/src/content/docs/user-guide/concepts/agents/agent-loop.mdx +++ b/src/content/docs/user-guide/concepts/agents/agent-loop.mdx @@ -1,6 +1,11 @@ --- title: Agent Loop description: "How Strands agents reason, plan, and act. Understand the model-driven loop that orchestrates tool use, reflection, and goal completion." +sourceLinks: + - repo: sdk-python + path: src/strands/event_loop/event_loop.py + - repo: sdk-typescript + path: strands-ts/src/agent/agent.ts --- A language model can answer questions. An agent can *do things*. The agent loop is what makes that difference possible. diff --git a/src/content/docs/user-guide/concepts/agents/conversation-management.mdx b/src/content/docs/user-guide/concepts/agents/conversation-management.mdx index ddacfcd67..bba21842d 100644 --- a/src/content/docs/user-guide/concepts/agents/conversation-management.mdx +++ b/src/content/docs/user-guide/concepts/agents/conversation-management.mdx @@ -1,5 +1,11 @@ --- title: Conversation Management +tags: [conversation-management] +sourceLinks: + - repo: sdk-python + path: src/strands/agent/conversation_manager/conversation_manager.py + - repo: sdk-typescript + path: strands-ts/src/conversation-manager/conversation-manager.ts --- In the Strands Agents SDK, context refers to the information provided to the agent for understanding and reasoning. This includes: diff --git a/src/content/docs/user-guide/concepts/agents/hooks.mdx b/src/content/docs/user-guide/concepts/agents/hooks.mdx index ea291e644..b90ab5736 100644 --- a/src/content/docs/user-guide/concepts/agents/hooks.mdx +++ b/src/content/docs/user-guide/concepts/agents/hooks.mdx @@ -1,6 +1,16 @@ --- title: Hooks description: "Intercept and customize agent behavior at every step. Hooks let you add logging, validation, guardrails, and custom logic to the agent loop." +tags: [hooks] +sourceLinks: + - repo: sdk-python + path: src/strands/hooks/registry.py + - repo: sdk-python + path: src/strands/hooks/events.py + - repo: sdk-typescript + path: strands-ts/src/hooks/registry.ts + - repo: sdk-typescript + path: strands-ts/src/hooks/events.ts --- diff --git a/src/content/docs/user-guide/concepts/agents/prompts.mdx b/src/content/docs/user-guide/concepts/agents/prompts.mdx index aff56a6b5..79171bda8 100644 --- a/src/content/docs/user-guide/concepts/agents/prompts.mdx +++ b/src/content/docs/user-guide/concepts/agents/prompts.mdx @@ -1,5 +1,10 @@ --- title: Prompts +sourceLinks: + - repo: sdk-python + path: src/strands/agent/agent.py + - repo: sdk-typescript + path: strands-ts/src/agent/agent.ts --- In the Strands Agents SDK, system prompts and user messages are the primary way to communicate with AI models. The SDK provides a flexible system for managing prompts, including both system prompts and user messages. diff --git a/src/content/docs/user-guide/concepts/agents/retry-strategies.mdx b/src/content/docs/user-guide/concepts/agents/retry-strategies.mdx index f585a8c8d..042b212cb 100644 --- a/src/content/docs/user-guide/concepts/agents/retry-strategies.mdx +++ b/src/content/docs/user-guide/concepts/agents/retry-strategies.mdx @@ -1,5 +1,11 @@ --- title: Retry Strategies +tags: [retry] +sourceLinks: + - repo: sdk-python + path: src/strands/event_loop/_retry.py + - repo: sdk-typescript + path: strands-ts/src/retry/retry-strategy.ts --- Model providers occasionally encounter errors such as rate limits, service unavailability, or network timeouts. By default, the agent retries `ModelThrottledException` failures automatically with exponential backoff and the `Angent.retry_strategy` parameter lets you customize this behavior. diff --git a/src/content/docs/user-guide/concepts/agents/session-management.mdx b/src/content/docs/user-guide/concepts/agents/session-management.mdx index bf4f365c6..cae1bf8ed 100644 --- a/src/content/docs/user-guide/concepts/agents/session-management.mdx +++ b/src/content/docs/user-guide/concepts/agents/session-management.mdx @@ -1,6 +1,12 @@ --- title: Session Management description: "Persist agent conversations across sessions. Save and restore chat history, tool state, and context for long-running AI workflows." +tags: [session-management] +sourceLinks: + - repo: sdk-python + path: src/strands/session/session_manager.py + - repo: sdk-typescript + path: strands-ts/src/session/session-manager.ts --- Session management in Strands Agents provides a robust mechanism for persisting agent state and conversation history across multiple interactions. This enables agents to maintain context and continuity even when the application restarts or when deployed in distributed environments. diff --git a/src/content/docs/user-guide/concepts/agents/state.mdx b/src/content/docs/user-guide/concepts/agents/state.mdx index 5b48ed132..46fbf6d43 100644 --- a/src/content/docs/user-guide/concepts/agents/state.mdx +++ b/src/content/docs/user-guide/concepts/agents/state.mdx @@ -2,6 +2,12 @@ title: State Management sidebar: label: "State" +tags: [state] +sourceLinks: + - repo: sdk-python + path: src/strands/agent/state.py + - repo: sdk-typescript + path: strands-ts/src/state-store.ts --- Strands Agents state is maintained in several forms: diff --git a/src/content/docs/user-guide/concepts/agents/structured-output.mdx b/src/content/docs/user-guide/concepts/agents/structured-output.mdx index 31d0fa7d6..ec85ff4dc 100644 --- a/src/content/docs/user-guide/concepts/agents/structured-output.mdx +++ b/src/content/docs/user-guide/concepts/agents/structured-output.mdx @@ -1,6 +1,12 @@ --- title: Structured Output description: "Get typed, validated responses from AI agents. Define Pydantic models and Strands returns structured data instead of raw text." +tags: [structured-output] +sourceLinks: + - repo: sdk-python + path: src/strands/tools/structured_output/structured_output_tool.py + - repo: sdk-typescript + path: strands-ts/src/tools/structured-output-tool.ts --- ## Introduction diff --git a/src/content/docs/user-guide/concepts/bidirectional-streaming/agent.mdx b/src/content/docs/user-guide/concepts/bidirectional-streaming/agent.mdx index 1c3f823a6..49034c4cd 100644 --- a/src/content/docs/user-guide/concepts/bidirectional-streaming/agent.mdx +++ b/src/content/docs/user-guide/concepts/bidirectional-streaming/agent.mdx @@ -1,6 +1,10 @@ --- title: BidiAgent experimental: true +tags: [streaming] +sourceLinks: + - repo: sdk-python + path: src/strands/experimental/bidi/agent/agent.py --- diff --git a/src/content/docs/user-guide/concepts/bidirectional-streaming/events.mdx b/src/content/docs/user-guide/concepts/bidirectional-streaming/events.mdx index 4efd7c77d..db6f83c9c 100644 --- a/src/content/docs/user-guide/concepts/bidirectional-streaming/events.mdx +++ b/src/content/docs/user-guide/concepts/bidirectional-streaming/events.mdx @@ -1,6 +1,10 @@ --- title: Events experimental: true +tags: [streaming] +sourceLinks: + - repo: sdk-python + path: src/strands/experimental/bidi/types/events.py --- diff --git a/src/content/docs/user-guide/concepts/bidirectional-streaming/hooks.mdx b/src/content/docs/user-guide/concepts/bidirectional-streaming/hooks.mdx index c9f8dc5a3..826616e5b 100644 --- a/src/content/docs/user-guide/concepts/bidirectional-streaming/hooks.mdx +++ b/src/content/docs/user-guide/concepts/bidirectional-streaming/hooks.mdx @@ -1,6 +1,10 @@ --- title: Hooks experimental: true +tags: [hooks, streaming] +sourceLinks: + - repo: sdk-python + path: src/strands/experimental/hooks/events.py --- diff --git a/src/content/docs/user-guide/concepts/bidirectional-streaming/interruption.mdx b/src/content/docs/user-guide/concepts/bidirectional-streaming/interruption.mdx index fa1b5197f..157a0dc4f 100644 --- a/src/content/docs/user-guide/concepts/bidirectional-streaming/interruption.mdx +++ b/src/content/docs/user-guide/concepts/bidirectional-streaming/interruption.mdx @@ -1,6 +1,10 @@ --- title: Interruptions experimental: true +tags: [streaming] +sourceLinks: + - repo: sdk-python + path: src/strands/experimental/bidi/agent/loop.py --- diff --git a/src/content/docs/user-guide/concepts/bidirectional-streaming/io.mdx b/src/content/docs/user-guide/concepts/bidirectional-streaming/io.mdx index 9bba4ce46..c84c668cb 100644 --- a/src/content/docs/user-guide/concepts/bidirectional-streaming/io.mdx +++ b/src/content/docs/user-guide/concepts/bidirectional-streaming/io.mdx @@ -3,6 +3,12 @@ title: I/O Channels experimental: true sidebar: label: "IO" +tags: [streaming] +sourceLinks: + - repo: sdk-python + path: src/strands/experimental/bidi/io/audio.py + - repo: sdk-python + path: src/strands/experimental/bidi/io/text.py --- diff --git a/src/content/docs/user-guide/concepts/bidirectional-streaming/models/gemini_live.mdx b/src/content/docs/user-guide/concepts/bidirectional-streaming/models/gemini_live.mdx index 68e362f1e..436055d73 100644 --- a/src/content/docs/user-guide/concepts/bidirectional-streaming/models/gemini_live.mdx +++ b/src/content/docs/user-guide/concepts/bidirectional-streaming/models/gemini_live.mdx @@ -1,6 +1,10 @@ --- title: Gemini Live experimental: true +tags: [streaming] +sourceLinks: + - repo: sdk-python + path: src/strands/experimental/bidi/models/gemini_live.py --- diff --git a/src/content/docs/user-guide/concepts/bidirectional-streaming/models/nova_sonic.mdx b/src/content/docs/user-guide/concepts/bidirectional-streaming/models/nova_sonic.mdx index f9f193526..d8d0fdb7e 100644 --- a/src/content/docs/user-guide/concepts/bidirectional-streaming/models/nova_sonic.mdx +++ b/src/content/docs/user-guide/concepts/bidirectional-streaming/models/nova_sonic.mdx @@ -1,6 +1,10 @@ --- title: Nova Sonic experimental: true +tags: [streaming, aws, bedrock] +sourceLinks: + - repo: sdk-python + path: src/strands/experimental/bidi/models/nova_sonic.py --- diff --git a/src/content/docs/user-guide/concepts/bidirectional-streaming/models/openai_realtime.mdx b/src/content/docs/user-guide/concepts/bidirectional-streaming/models/openai_realtime.mdx index a2309009b..73a314768 100644 --- a/src/content/docs/user-guide/concepts/bidirectional-streaming/models/openai_realtime.mdx +++ b/src/content/docs/user-guide/concepts/bidirectional-streaming/models/openai_realtime.mdx @@ -1,6 +1,10 @@ --- title: OpenAI Realtime experimental: true +tags: [streaming] +sourceLinks: + - repo: sdk-python + path: src/strands/experimental/bidi/models/openai_realtime.py --- diff --git a/src/content/docs/user-guide/concepts/bidirectional-streaming/session-management.mdx b/src/content/docs/user-guide/concepts/bidirectional-streaming/session-management.mdx index 598d97c27..7a5f1db1d 100644 --- a/src/content/docs/user-guide/concepts/bidirectional-streaming/session-management.mdx +++ b/src/content/docs/user-guide/concepts/bidirectional-streaming/session-management.mdx @@ -1,6 +1,10 @@ --- title: Session Management experimental: true +tags: [session-management, streaming] +sourceLinks: + - repo: sdk-python + path: src/strands/experimental/checkpoint/checkpoint.py --- diff --git a/src/content/docs/user-guide/concepts/interrupts.mdx b/src/content/docs/user-guide/concepts/interrupts.mdx index 0ffd16005..bd95773c2 100644 --- a/src/content/docs/user-guide/concepts/interrupts.mdx +++ b/src/content/docs/user-guide/concepts/interrupts.mdx @@ -1,6 +1,11 @@ --- title: Interrupts description: "Pause AI agents mid-execution for human approval, input, or review. Build human-in-the-loop workflows with interrupt and resume patterns." +sourceLinks: + - repo: sdk-python + path: src/strands/interrupt.py + - repo: sdk-typescript + path: strands-ts/src/interrupt.ts --- The interrupt system enables human-in-the-loop workflows by allowing users to pause agent execution and request human input before continuing. When an interrupt is raised, the agent stops its loop and returns control to the user. The user in turn provides a response to the agent. The agent then continues its execution starting from the point of interruption. Users can raise interrupts from either hook callbacks or tool definitions. The general flow looks as follows: diff --git a/src/content/docs/user-guide/concepts/model-providers/amazon-bedrock.mdx b/src/content/docs/user-guide/concepts/model-providers/amazon-bedrock.mdx index eacb0807f..6a34e0733 100644 --- a/src/content/docs/user-guide/concepts/model-providers/amazon-bedrock.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/amazon-bedrock.mdx @@ -1,6 +1,12 @@ --- title: Amazon Bedrock integrationType: model-provider +tags: [bedrock, aws] +sourceLinks: + - repo: sdk-python + path: src/strands/models/bedrock.py + - repo: sdk-typescript + path: strands-ts/src/models/bedrock.ts --- Amazon Bedrock is a fully managed service that offers a choice of high-performing foundation models from leading AI companies through a unified API. Strands provides native support for Amazon Bedrock, allowing you to use these powerful models in your agents with minimal configuration. diff --git a/src/content/docs/user-guide/concepts/model-providers/amazon-nova.mdx b/src/content/docs/user-guide/concepts/model-providers/amazon-nova.mdx index 97f08d030..c88fc4636 100644 --- a/src/content/docs/user-guide/concepts/model-providers/amazon-nova.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/amazon-nova.mdx @@ -2,6 +2,10 @@ title: Amazon Nova languages: Python integrationType: model-provider +tags: [aws, bedrock] +sourceLinks: + - repo: sdk-python + path: src/strands/models/bedrock.py --- [Amazon Nova](https://nova.amazon.com/) is a new generation of foundation models with frontier intelligence and industry leading price performance. Generate text, code, and images with natural language prompts. The [`strands-amazon-nova`](https://pypi.org/project/strands-amazon-nova/) package ([GitHub](https://github.com/amazon-nova-api/strands-nova)) provides an integration for the Strands Agents SDK, enabling seamless use of Amazon Nova models. diff --git a/src/content/docs/user-guide/concepts/model-providers/anthropic.mdx b/src/content/docs/user-guide/concepts/model-providers/anthropic.mdx index af004a171..03655d912 100644 --- a/src/content/docs/user-guide/concepts/model-providers/anthropic.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/anthropic.mdx @@ -1,6 +1,11 @@ --- title: Anthropic integrationType: model-provider +sourceLinks: + - repo: sdk-python + path: src/strands/models/anthropic.py + - repo: sdk-typescript + path: strands-ts/src/models/anthropic.ts --- [Anthropic](https://docs.anthropic.com/en/home) is an AI safety and research company focused on building reliable, interpretable, and steerable AI systems. Included in their offerings is the Claude AI family of models, which are known for their conversational abilities, careful reasoning, and capacity to follow complex instructions. The Strands Agents SDK implements an Anthropic provider, allowing users to run agents against Claude models directly. diff --git a/src/content/docs/user-guide/concepts/model-providers/custom_model_provider.mdx b/src/content/docs/user-guide/concepts/model-providers/custom_model_provider.mdx index ab4293f2e..b934d7607 100644 --- a/src/content/docs/user-guide/concepts/model-providers/custom_model_provider.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/custom_model_provider.mdx @@ -3,6 +3,11 @@ title: Creating a Custom Model Provider sidebar: label: "Custom Providers" integrationType: model-provider +sourceLinks: + - repo: sdk-python + path: src/strands/models/model.py + - repo: sdk-typescript + path: strands-ts/src/models/model.ts --- Strands Agents SDK provides an extensible interface for implementing custom model providers, allowing organizations to integrate their own LLM services while keeping implementation details private to their codebase. diff --git a/src/content/docs/user-guide/concepts/model-providers/google.mdx b/src/content/docs/user-guide/concepts/model-providers/google.mdx index 1f0cfb8dc..b335a2118 100644 --- a/src/content/docs/user-guide/concepts/model-providers/google.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/google.mdx @@ -3,6 +3,11 @@ title: Google integrationType: model-provider redirectFrom: - docs/user-guide/concepts/model-providers/gemini +sourceLinks: + - repo: sdk-python + path: src/strands/models/gemini.py + - repo: sdk-typescript + path: strands-ts/src/models/google/model.ts --- [Google Gemini](https://ai.google.dev/api) is Google's family of multimodal large language models designed for advanced reasoning, code generation, and creative tasks. The Strands Agents SDK implements a Google/Gemini provider, allowing you to run agents against the Gemini models available through Google's AI API. diff --git a/src/content/docs/user-guide/concepts/model-providers/litellm.mdx b/src/content/docs/user-guide/concepts/model-providers/litellm.mdx index da44d0901..d5073f801 100644 --- a/src/content/docs/user-guide/concepts/model-providers/litellm.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/litellm.mdx @@ -2,6 +2,9 @@ title: LiteLLM languages: Python integrationType: model-provider +sourceLinks: + - repo: sdk-python + path: src/strands/models/litellm.py --- [LiteLLM](https://docs.litellm.ai/docs/) is a unified interface for various LLM providers that allows you to interact with models from Amazon, Anthropic, OpenAI, and many others through a single API. The Strands Agents SDK implements a LiteLLM provider, allowing you to run agents against any model LiteLLM supports. diff --git a/src/content/docs/user-guide/concepts/model-providers/llamaapi.mdx b/src/content/docs/user-guide/concepts/model-providers/llamaapi.mdx index ce5658b30..ba97ee114 100644 --- a/src/content/docs/user-guide/concepts/model-providers/llamaapi.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/llamaapi.mdx @@ -4,6 +4,9 @@ languages: Python sidebar: label: "LlamaAPI" integrationType: model-provider +sourceLinks: + - repo: sdk-python + path: src/strands/models/llamaapi.py --- [Llama API](https://llama.developer.meta.com?utm_source=partner-strandsagent&utm_medium=website) is a Meta-hosted API service that helps you integrate Llama models into your applications quickly and efficiently. diff --git a/src/content/docs/user-guide/concepts/model-providers/llamacpp.mdx b/src/content/docs/user-guide/concepts/model-providers/llamacpp.mdx index a896ba379..61974e8c2 100644 --- a/src/content/docs/user-guide/concepts/model-providers/llamacpp.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/llamacpp.mdx @@ -2,6 +2,9 @@ title: llama.cpp languages: Python integrationType: model-provider +sourceLinks: + - repo: sdk-python + path: src/strands/models/llamacpp.py --- [llama.cpp](https://github.com/ggml-org/llama.cpp) is a high-performance C++ inference engine for running large language models locally. The Strands Agents SDK implements a llama.cpp provider, allowing you to run agents against any llama.cpp server with quantized models. diff --git a/src/content/docs/user-guide/concepts/model-providers/mistral.mdx b/src/content/docs/user-guide/concepts/model-providers/mistral.mdx index 3cccd3f72..5e819f991 100644 --- a/src/content/docs/user-guide/concepts/model-providers/mistral.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/mistral.mdx @@ -4,6 +4,9 @@ languages: Python sidebar: label: "MistralAI" integrationType: model-provider +sourceLinks: + - repo: sdk-python + path: src/strands/models/mistral.py --- [Mistral AI](https://mistral.ai/) is a research lab building the best open source models in the world. diff --git a/src/content/docs/user-guide/concepts/model-providers/ollama.mdx b/src/content/docs/user-guide/concepts/model-providers/ollama.mdx index 2aaa2faf0..6d610ad88 100644 --- a/src/content/docs/user-guide/concepts/model-providers/ollama.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/ollama.mdx @@ -2,6 +2,9 @@ title: Ollama languages: Python integrationType: model-provider +sourceLinks: + - repo: sdk-python + path: src/strands/models/ollama.py --- Ollama is a framework for running open-source large language models locally. Strands provides native support for Ollama, allowing you to use locally-hosted models in your agents. diff --git a/src/content/docs/user-guide/concepts/model-providers/openai-responses.mdx b/src/content/docs/user-guide/concepts/model-providers/openai-responses.mdx index 8f2140e20..1ed84aba3 100644 --- a/src/content/docs/user-guide/concepts/model-providers/openai-responses.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/openai-responses.mdx @@ -1,6 +1,11 @@ --- title: OpenAI Responses API integrationType: model-provider +sourceLinks: + - repo: sdk-python + path: src/strands/models/openai_responses.py + - repo: sdk-typescript + path: strands-ts/src/models/openai/responses-adapter.ts --- The [Responses API](https://platform.openai.com/docs/api-reference/responses) is OpenAI's interface for generating model responses and building agents. It is a superset of the [Chat Completions](./openai) API, with additional support for [built-in tools](#built-in-tools), server-side conversation state management, and multi-modal inputs. diff --git a/src/content/docs/user-guide/concepts/model-providers/openai.mdx b/src/content/docs/user-guide/concepts/model-providers/openai.mdx index 07a79c030..98cd013e3 100644 --- a/src/content/docs/user-guide/concepts/model-providers/openai.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/openai.mdx @@ -1,6 +1,11 @@ --- title: OpenAI integrationType: model-provider +sourceLinks: + - repo: sdk-python + path: src/strands/models/openai.py + - repo: sdk-typescript + path: strands-ts/src/models/openai/model.ts --- [OpenAI](https://platform.openai.com/docs/overview) is an AI research and deployment company that provides a suite of powerful language models. The Strands Agents SDK implements an OpenAI provider, allowing you to run agents against any OpenAI or OpenAI-compatible model. diff --git a/src/content/docs/user-guide/concepts/model-providers/sagemaker.mdx b/src/content/docs/user-guide/concepts/model-providers/sagemaker.mdx index 487459b5c..52fe9d215 100644 --- a/src/content/docs/user-guide/concepts/model-providers/sagemaker.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/sagemaker.mdx @@ -4,6 +4,10 @@ languages: Python sidebar: label: "SageMaker" integrationType: model-provider +tags: [aws] +sourceLinks: + - repo: sdk-python + path: src/strands/models/sagemaker.py --- [Amazon SageMaker](https://aws.amazon.com/sagemaker/) is a fully managed machine learning service that provides infrastructure and tools for building, training, and deploying ML models at scale. The Strands Agents SDK implements a SageMaker provider, allowing you to run agents against models deployed on SageMaker inference endpoints, including both pre-trained models from SageMaker JumpStart and custom fine-tuned models. The provider is designed to work with models that support OpenAI-compatible chat completion APIs. diff --git a/src/content/docs/user-guide/concepts/model-providers/vercel.mdx b/src/content/docs/user-guide/concepts/model-providers/vercel.mdx index e2dfcc30a..f04cb096d 100644 --- a/src/content/docs/user-guide/concepts/model-providers/vercel.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/vercel.mdx @@ -2,6 +2,9 @@ title: Vercel languages: TypeScript integrationType: model-provider +sourceLinks: + - repo: sdk-typescript + path: strands-ts/src/models/vercel.ts --- The [Vercel AI SDK](https://sdk.vercel.ai/) is a TypeScript toolkit for building AI-powered applications. It defines a [Language Model Specification](https://github.com/vercel/ai/tree/main/packages/provider/src/language-model/v3) that standardizes how applications interact with LLMs across providers. The Strands Agents SDK includes a `VercelModel` adapter that wraps any Language Model Specification v3 (`LanguageModelV3`) provider for use as a Strands model provider. diff --git a/src/content/docs/user-guide/concepts/model-providers/writer.mdx b/src/content/docs/user-guide/concepts/model-providers/writer.mdx index f67dd1a24..03ab91188 100644 --- a/src/content/docs/user-guide/concepts/model-providers/writer.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/writer.mdx @@ -2,6 +2,9 @@ title: Writer languages: Python integrationType: model-provider +sourceLinks: + - repo: sdk-python + path: src/strands/models/writer.py --- [Writer](https://writer.com/) is an enterprise generative AI platform offering specialized Palmyra models for finance, healthcare, creative, and general-purpose use cases. The models excel at tool calling, structured outputs, and domain-specific tasks, with Palmyra X5 supporting a 1M token context window. diff --git a/src/content/docs/user-guide/concepts/multi-agent/agent-to-agent.mdx b/src/content/docs/user-guide/concepts/multi-agent/agent-to-agent.mdx index b976f9dba..51b16c048 100644 --- a/src/content/docs/user-guide/concepts/multi-agent/agent-to-agent.mdx +++ b/src/content/docs/user-guide/concepts/multi-agent/agent-to-agent.mdx @@ -2,6 +2,16 @@ title: Agent-to-Agent (A2A) Protocol sidebar: label: "Agent2Agent (A2A)" +tags: [multi-agent] +sourceLinks: + - repo: sdk-python + path: src/strands/multiagent/a2a/server.py + - repo: sdk-python + path: src/strands/agent/a2a_agent.py + - repo: sdk-typescript + path: strands-ts/src/a2a/a2a-agent.ts + - repo: sdk-typescript + path: strands-ts/src/a2a/server.ts --- Strands Agents supports the [Agent-to-Agent (A2A) protocol](https://a2aproject.github.io/A2A/latest/), enabling seamless communication between AI agents across different platforms and implementations. diff --git a/src/content/docs/user-guide/concepts/multi-agent/agents-as-tools.mdx b/src/content/docs/user-guide/concepts/multi-agent/agents-as-tools.mdx index f1a9921a0..f138ee886 100644 --- a/src/content/docs/user-guide/concepts/multi-agent/agents-as-tools.mdx +++ b/src/content/docs/user-guide/concepts/multi-agent/agents-as-tools.mdx @@ -2,6 +2,12 @@ title: Agents as Tools with Strands Agents SDK sidebar: label: "Agents as Tools" +tags: [multi-agent, tools] +sourceLinks: + - repo: sdk-python + path: src/strands/agent/_agent_as_tool.py + - repo: sdk-typescript + path: strands-ts/src/agent/agent-as-tool.ts --- ## The Concept: Agents as Tools diff --git a/src/content/docs/user-guide/concepts/multi-agent/graph.mdx b/src/content/docs/user-guide/concepts/multi-agent/graph.mdx index 51eb576d0..909fddd04 100644 --- a/src/content/docs/user-guide/concepts/multi-agent/graph.mdx +++ b/src/content/docs/user-guide/concepts/multi-agent/graph.mdx @@ -2,6 +2,12 @@ title: Graph Multi-Agent Pattern sidebar: label: "Graph" +tags: [multi-agent] +sourceLinks: + - repo: sdk-python + path: src/strands/multiagent/graph.py + - repo: sdk-typescript + path: strands-ts/src/multiagent/graph.ts --- A Graph is a deterministic directed graph based agent orchestration system where agents, custom nodes, or other multi-agent systems (like [Swarm](./swarm.md) or nested Graphs) are nodes in a graph. Nodes are executed according to edge dependencies, with output from one node passed as input to connected nodes. The Graph pattern supports both acyclic (DAG) and cyclic topologies, enabling feedback loops and iterative refinement workflows. diff --git a/src/content/docs/user-guide/concepts/multi-agent/multi-agent-patterns.mdx b/src/content/docs/user-guide/concepts/multi-agent/multi-agent-patterns.mdx index 9d2665b96..7805d731c 100644 --- a/src/content/docs/user-guide/concepts/multi-agent/multi-agent-patterns.mdx +++ b/src/content/docs/user-guide/concepts/multi-agent/multi-agent-patterns.mdx @@ -1,6 +1,12 @@ --- title: Multi-agent Patterns description: "Coordinate multiple AI agents with handoffs, swarms, graphs, and workflow patterns. Built-in primitives for complex multi-agent orchestration." +tags: [multi-agent] +sourceLinks: + - repo: sdk-python + path: src/strands/multiagent/base.py + - repo: sdk-typescript + path: strands-ts/src/multiagent/multiagent.ts --- In Strands, building a system with multiple agents or complex tool chains can be approached in several ways. The three primary patterns you'll encounter are Graph, Swarm, and Workflow. While they all aim to solve complex problems, they have differences in their structures, execution workflows, and use cases. diff --git a/src/content/docs/user-guide/concepts/multi-agent/swarm.mdx b/src/content/docs/user-guide/concepts/multi-agent/swarm.mdx index 6cab73974..c22445c26 100644 --- a/src/content/docs/user-guide/concepts/multi-agent/swarm.mdx +++ b/src/content/docs/user-guide/concepts/multi-agent/swarm.mdx @@ -2,6 +2,12 @@ title: Swarm Multi-Agent Pattern sidebar: label: "Swarm" +tags: [multi-agent] +sourceLinks: + - repo: sdk-python + path: src/strands/multiagent/swarm.py + - repo: sdk-typescript + path: strands-ts/src/multiagent/swarm.ts --- A Swarm is a collaborative agent orchestration system where multiple agents work together as a team to solve complex tasks. Unlike traditional sequential or hierarchical multi-agent systems, a Swarm enables autonomous coordination between agents with shared context and working memory. diff --git a/src/content/docs/user-guide/concepts/multi-agent/workflow.mdx b/src/content/docs/user-guide/concepts/multi-agent/workflow.mdx index f1c533696..9491af3a0 100644 --- a/src/content/docs/user-guide/concepts/multi-agent/workflow.mdx +++ b/src/content/docs/user-guide/concepts/multi-agent/workflow.mdx @@ -2,6 +2,7 @@ title: "Agent Workflows: Building Multi-Agent Systems with Strands Agents SDK" sidebar: label: "Workflow" +tags: [multi-agent] --- ## Understanding Workflows diff --git a/src/content/docs/user-guide/concepts/plugins/context-offloader.mdx b/src/content/docs/user-guide/concepts/plugins/context-offloader.mdx index c0051f534..4222a6757 100644 --- a/src/content/docs/user-guide/concepts/plugins/context-offloader.mdx +++ b/src/content/docs/user-guide/concepts/plugins/context-offloader.mdx @@ -4,6 +4,11 @@ sidebar: badge: text: New variant: tip +sourceLinks: + - repo: sdk-python + path: src/strands/vended_plugins/context_offloader/plugin.py + - repo: sdk-python + path: src/strands/vended_plugins/context_offloader/storage.py --- The `ContextOffloader` plugin prevents large tool results from consuming your agent's context window. When a tool returns a result that exceeds a configurable token threshold, the plugin stores each content block individually in an external storage backend and replaces it in the conversation with a truncated preview plus per-block references. Each offloaded result includes inline guidance telling the agent to use its available tools to selectively access the data it needs. diff --git a/src/content/docs/user-guide/concepts/plugins/index.mdx b/src/content/docs/user-guide/concepts/plugins/index.mdx index 1453806a2..79684e339 100644 --- a/src/content/docs/user-guide/concepts/plugins/index.mdx +++ b/src/content/docs/user-guide/concepts/plugins/index.mdx @@ -1,6 +1,15 @@ --- title: Plugins description: "Extend agent behavior with plugins. Add steering, guardrails, and custom capabilities that hook into the agent lifecycle." +sourceLinks: + - repo: sdk-python + path: src/strands/plugins/plugin.py + - repo: sdk-python + path: src/strands/plugins/registry.py + - repo: sdk-typescript + path: strands-ts/src/plugins/plugin.ts + - repo: sdk-typescript + path: strands-ts/src/plugins/registry.ts --- Plugins allow you to change the typical behavior of an agent. They enable you to introduce concepts like [Skills](https://agentskills.io/specification), [steering](./steering), or other behavioral modifications into the agentic loop. Plugins work by taking advantage of the low-level primitives exposed by the Agent class—`model`, `system_prompt`, `messages`, `tools`, and `hooks`—and executing logic to improve an agent's behavior. diff --git a/src/content/docs/user-guide/concepts/plugins/skills.mdx b/src/content/docs/user-guide/concepts/plugins/skills.mdx index 6c50bfeb0..e9e33e318 100644 --- a/src/content/docs/user-guide/concepts/plugins/skills.mdx +++ b/src/content/docs/user-guide/concepts/plugins/skills.mdx @@ -4,6 +4,11 @@ sidebar: badge: text: New variant: tip +sourceLinks: + - repo: sdk-python + path: src/strands/vended_plugins/skills/agent_skills.py + - repo: sdk-python + path: src/strands/vended_plugins/skills/skill.py --- Skills give your agent on-demand access to specialized instructions without bloating the system prompt. Instead of front-loading every possible instruction into a single prompt, you define modular skill packages that the agent discovers and activates only when relevant. diff --git a/src/content/docs/user-guide/concepts/plugins/steering.mdx b/src/content/docs/user-guide/concepts/plugins/steering.mdx index 318eef162..9b29ef101 100644 --- a/src/content/docs/user-guide/concepts/plugins/steering.mdx +++ b/src/content/docs/user-guide/concepts/plugins/steering.mdx @@ -1,6 +1,11 @@ --- title: Steering languages: [python] +sourceLinks: + - repo: sdk-python + path: src/strands/vended_plugins/steering/core/handler.py + - repo: sdk-python + path: src/strands/vended_plugins/steering/handlers/llm/llm_handler.py --- diff --git a/src/content/docs/user-guide/concepts/streaming/async-iterators.mdx b/src/content/docs/user-guide/concepts/streaming/async-iterators.mdx index 5ac093e69..db6430f0a 100644 --- a/src/content/docs/user-guide/concepts/streaming/async-iterators.mdx +++ b/src/content/docs/user-guide/concepts/streaming/async-iterators.mdx @@ -2,6 +2,10 @@ title: Async Iterators for Streaming sidebar: label: "Async Iterators" +tags: [streaming] +sourceLinks: + - repo: sdk-python + path: src/strands/event_loop/streaming.py --- Async iterators provide asynchronous streaming of agent events, allowing you to process events as they occur in real-time. This approach is ideal for asynchronous frameworks where you need fine-grained control over async execution flow. diff --git a/src/content/docs/user-guide/concepts/streaming/callback-handlers.mdx b/src/content/docs/user-guide/concepts/streaming/callback-handlers.mdx index ef5b4fa33..3d42355b6 100644 --- a/src/content/docs/user-guide/concepts/streaming/callback-handlers.mdx +++ b/src/content/docs/user-guide/concepts/streaming/callback-handlers.mdx @@ -1,5 +1,9 @@ --- title: Callback Handlers +tags: [streaming] +sourceLinks: + - repo: sdk-python + path: src/strands/handlers/callback_handler.py --- :::note[Not supported in TypeScript] diff --git a/src/content/docs/user-guide/concepts/streaming/index.mdx b/src/content/docs/user-guide/concepts/streaming/index.mdx index 3f3d28728..af9f654d7 100644 --- a/src/content/docs/user-guide/concepts/streaming/index.mdx +++ b/src/content/docs/user-guide/concepts/streaming/index.mdx @@ -3,6 +3,12 @@ title: Streaming Events description: "Stream AI agent responses in real time. Handle partial results, tool invocations, and token-by-token output as the agent works." sidebar: label: "Overview" +tags: [streaming] +sourceLinks: + - repo: sdk-python + path: src/strands/event_loop/streaming.py + - repo: sdk-typescript + path: strands-ts/src/models/streaming.ts --- Strands Agents SDK provides real-time streaming capabilities that allow you to monitor and process events as they occur during agent execution. This enables responsive user interfaces, real-time monitoring, and custom output formatting. diff --git a/src/content/docs/user-guide/concepts/tools/custom-tools.mdx b/src/content/docs/user-guide/concepts/tools/custom-tools.mdx index 52fe60144..5a7d73701 100644 --- a/src/content/docs/user-guide/concepts/tools/custom-tools.mdx +++ b/src/content/docs/user-guide/concepts/tools/custom-tools.mdx @@ -1,6 +1,12 @@ --- title: Creating Custom Tools description: "Turn any Python function into an AI agent tool. Define inputs with docstrings, and the agent calls your function autonomously." +tags: [tools] +sourceLinks: + - repo: sdk-python + path: src/strands/tools/decorator.py + - repo: sdk-typescript + path: strands-ts/src/tools/function-tool.ts --- There are multiple approaches to defining custom tools in Strands, with differences between Python and TypeScript implementations. diff --git a/src/content/docs/user-guide/concepts/tools/executors.mdx b/src/content/docs/user-guide/concepts/tools/executors.mdx index 1e138c5b2..fac133362 100644 --- a/src/content/docs/user-guide/concepts/tools/executors.mdx +++ b/src/content/docs/user-guide/concepts/tools/executors.mdx @@ -2,6 +2,14 @@ title: Tool Executors sidebar: label: "Executors" +tags: [tools] +sourceLinks: + - repo: sdk-python + path: src/strands/tools/executors/_executor.py + - repo: sdk-python + path: src/strands/tools/executors/concurrent.py + - repo: sdk-python + path: src/strands/tools/executors/sequential.py --- Tool executors control whether tools from a single assistant turn run concurrently or sequentially. Both SDKs default to concurrent execution. diff --git a/src/content/docs/user-guide/concepts/tools/index.mdx b/src/content/docs/user-guide/concepts/tools/index.mdx index ccc940a60..fa7bff231 100644 --- a/src/content/docs/user-guide/concepts/tools/index.mdx +++ b/src/content/docs/user-guide/concepts/tools/index.mdx @@ -3,6 +3,12 @@ title: Tools Overview description: "Give AI agents the ability to take real-world actions. Strands supports built-in tools, custom Python functions, MCP servers, and community packages." sidebar: label: "Overview" +tags: [tools] +sourceLinks: + - repo: sdk-python + path: src/strands/tools/registry.py + - repo: sdk-typescript + path: strands-ts/src/registry/tool-registry.ts --- Tools are the primary mechanism for extending agent capabilities, enabling them to perform actions beyond simple text generation. Tools allow agents to interact with external systems, access data, and manipulate their environment. diff --git a/src/content/docs/user-guide/concepts/tools/mcp-tools.mdx b/src/content/docs/user-guide/concepts/tools/mcp-tools.mdx index feaaa1ef2..729598940 100644 --- a/src/content/docs/user-guide/concepts/tools/mcp-tools.mdx +++ b/src/content/docs/user-guide/concepts/tools/mcp-tools.mdx @@ -3,6 +3,14 @@ title: Model Context Protocol (MCP) Tools description: "Connect AI agents to any MCP server for tool access. Strands agents integrate and invoke MCP tools without custom integration code." sidebar: label: "Model Context Protocol (MCP)" +tags: [tools, mcp] +sourceLinks: + - repo: sdk-python + path: src/strands/tools/mcp/mcp_client.py + - repo: sdk-typescript + path: strands-ts/src/mcp.ts + - repo: sdk-typescript + path: strands-ts/src/tools/mcp-tool.ts --- The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is an open protocol that standardizes how applications provide context to Large Language Models. Strands Agents integrates with MCP to extend agent capabilities through external tools and services. diff --git a/src/content/docs/user-guide/concepts/tools/vended-tools.mdx b/src/content/docs/user-guide/concepts/tools/vended-tools.mdx index d6234b7b2..1ce077164 100644 --- a/src/content/docs/user-guide/concepts/tools/vended-tools.mdx +++ b/src/content/docs/user-guide/concepts/tools/vended-tools.mdx @@ -4,6 +4,16 @@ description: "Pre-built tools included in the TypeScript SDK for common agent ta sidebar: label: "Vended Tools" languages: [typescript] +tags: [tools, typescript] +sourceLinks: + - repo: sdk-typescript + path: strands-ts/src/vended-tools/bash/bash.ts + - repo: sdk-typescript + path: strands-ts/src/vended-tools/file-editor/file-editor.ts + - repo: sdk-typescript + path: strands-ts/src/vended-tools/http-request/http-request.ts + - repo: sdk-typescript + path: strands-ts/src/vended-tools/notebook/notebook.ts --- Vended tools are pre-built tools included directly in the Strands SDK for common agent tasks like file operations, shell commands, HTTP requests, and persistent notes. diff --git a/src/content/docs/user-guide/deploy/deploy_to_amazon_ec2.mdx b/src/content/docs/user-guide/deploy/deploy_to_amazon_ec2.mdx index c2fe96314..41535564b 100644 --- a/src/content/docs/user-guide/deploy/deploy_to_amazon_ec2.mdx +++ b/src/content/docs/user-guide/deploy/deploy_to_amazon_ec2.mdx @@ -2,6 +2,7 @@ title: Deploying Strands Agents SDK Agents to Amazon EC2 sidebar: label: "Amazon EC2" +tags: [deployment, aws, production] --- Amazon EC2 (Elastic Compute Cloud) provides resizable compute capacity in the cloud, making it a flexible option for deploying Strands Agents SDK agents. This deployment approach gives you full control over the underlying infrastructure while maintaining the ability to scale as needed. diff --git a/src/content/docs/user-guide/deploy/deploy_to_amazon_eks.mdx b/src/content/docs/user-guide/deploy/deploy_to_amazon_eks.mdx index b7648ddaa..1b50c6994 100644 --- a/src/content/docs/user-guide/deploy/deploy_to_amazon_eks.mdx +++ b/src/content/docs/user-guide/deploy/deploy_to_amazon_eks.mdx @@ -2,6 +2,7 @@ title: Deploying Strands Agents SDK Agents to Amazon EKS sidebar: label: "Amazon EKS" +tags: [deployment, aws, production] --- Amazon Elastic Kubernetes Service (EKS) is a managed container orchestration service that makes it easy to deploy, manage, and scale containerized applications using Kubernetes, while AWS manages the Kubernetes control plane. diff --git a/src/content/docs/user-guide/deploy/deploy_to_aws_apprunner.mdx b/src/content/docs/user-guide/deploy/deploy_to_aws_apprunner.mdx index 0ddef7eb7..b0bed0a57 100644 --- a/src/content/docs/user-guide/deploy/deploy_to_aws_apprunner.mdx +++ b/src/content/docs/user-guide/deploy/deploy_to_aws_apprunner.mdx @@ -2,6 +2,7 @@ title: Deploying Strands Agents SDK Agents to AWS App Runner sidebar: label: "AWS App Runner" +tags: [deployment, aws, production] --- AWS App Runner is the easiest way to deploy web applications on AWS, including API services, backend web services, and websites. App Runner eliminates the need for infrastructure management or container orchestration by providing a fully managed platform with automatic integration and delivery pipelines, high performance, scalability, and security. diff --git a/src/content/docs/user-guide/deploy/deploy_to_aws_fargate.mdx b/src/content/docs/user-guide/deploy/deploy_to_aws_fargate.mdx index f8439ec47..c04712cd1 100644 --- a/src/content/docs/user-guide/deploy/deploy_to_aws_fargate.mdx +++ b/src/content/docs/user-guide/deploy/deploy_to_aws_fargate.mdx @@ -2,6 +2,7 @@ title: Deploying Strands Agents SDK Agents to AWS Fargate sidebar: label: "AWS Fargate" +tags: [deployment, aws, production] --- AWS Fargate is a serverless compute engine for containers that works with Amazon ECS and EKS. It allows you to run containers without having to manage servers or clusters. This makes it an excellent choice for deploying Strands Agents SDK agents as containerized applications with high availability and scalability. diff --git a/src/content/docs/user-guide/deploy/deploy_to_aws_lambda.mdx b/src/content/docs/user-guide/deploy/deploy_to_aws_lambda.mdx index bca080309..931c1ff0b 100644 --- a/src/content/docs/user-guide/deploy/deploy_to_aws_lambda.mdx +++ b/src/content/docs/user-guide/deploy/deploy_to_aws_lambda.mdx @@ -5,6 +5,7 @@ sidebar: badge: text: New variant: note +tags: [deployment, aws, production] --- AWS Lambda is a serverless compute service that lets you run code without provisioning or managing servers. This makes it an excellent choice for deploying Strands Agents SDK agents because you only pay for the compute time you consume and don't need to manage hosts or servers. diff --git a/src/content/docs/user-guide/deploy/deploy_to_bedrock_agentcore/index.mdx b/src/content/docs/user-guide/deploy/deploy_to_bedrock_agentcore/index.mdx index af2efc9e1..10a395168 100644 --- a/src/content/docs/user-guide/deploy/deploy_to_bedrock_agentcore/index.mdx +++ b/src/content/docs/user-guide/deploy/deploy_to_bedrock_agentcore/index.mdx @@ -2,6 +2,7 @@ title: Deploying Strands Agents to Amazon Bedrock AgentCore Runtime sidebar: label: "Overview" +tags: [deployment, aws, bedrock, agentcore, production] --- import { LinkCard, CardGrid } from '@astrojs/starlight/components'; diff --git a/src/content/docs/user-guide/deploy/deploy_to_bedrock_agentcore/python.mdx b/src/content/docs/user-guide/deploy/deploy_to_bedrock_agentcore/python.mdx index d6bac1256..879062eae 100644 --- a/src/content/docs/user-guide/deploy/deploy_to_bedrock_agentcore/python.mdx +++ b/src/content/docs/user-guide/deploy/deploy_to_bedrock_agentcore/python.mdx @@ -2,6 +2,7 @@ title: Python Deployment to Amazon Bedrock AgentCore Runtime sidebar: label: "Python" +tags: [deployment, aws, bedrock, agentcore, python, production] --- This guide covers deploying Python-based Strands agents to [Amazon Bedrock AgentCore Runtime](index.md). diff --git a/src/content/docs/user-guide/deploy/deploy_to_bedrock_agentcore/typescript.mdx b/src/content/docs/user-guide/deploy/deploy_to_bedrock_agentcore/typescript.mdx index 8484b0c44..58bb6dec4 100644 --- a/src/content/docs/user-guide/deploy/deploy_to_bedrock_agentcore/typescript.mdx +++ b/src/content/docs/user-guide/deploy/deploy_to_bedrock_agentcore/typescript.mdx @@ -2,6 +2,7 @@ title: TypeScript Deployment to Amazon Bedrock AgentCore Runtime sidebar: label: "TypeScript" +tags: [deployment, aws, bedrock, agentcore, typescript, production] --- diff --git a/src/content/docs/user-guide/deploy/deploy_to_docker/index.mdx b/src/content/docs/user-guide/deploy/deploy_to_docker/index.mdx index f795c5501..6bc4262a1 100644 --- a/src/content/docs/user-guide/deploy/deploy_to_docker/index.mdx +++ b/src/content/docs/user-guide/deploy/deploy_to_docker/index.mdx @@ -2,6 +2,7 @@ title: Deploying Strands Agents to Docker sidebar: label: "Overview" +tags: [deployment, production] --- import { LinkCard, CardGrid } from '@astrojs/starlight/components'; diff --git a/src/content/docs/user-guide/deploy/deploy_to_docker/python.mdx b/src/content/docs/user-guide/deploy/deploy_to_docker/python.mdx index 6a8ae3c81..de0be6abe 100644 --- a/src/content/docs/user-guide/deploy/deploy_to_docker/python.mdx +++ b/src/content/docs/user-guide/deploy/deploy_to_docker/python.mdx @@ -2,6 +2,7 @@ title: Python Deployment to Docker sidebar: label: "Python" +tags: [deployment, python, production] --- This guide covers deploying Python-based Strands agents using Docker for for local and cloud development. diff --git a/src/content/docs/user-guide/deploy/deploy_to_docker/typescript.mdx b/src/content/docs/user-guide/deploy/deploy_to_docker/typescript.mdx index 0c155c913..ef812dadc 100644 --- a/src/content/docs/user-guide/deploy/deploy_to_docker/typescript.mdx +++ b/src/content/docs/user-guide/deploy/deploy_to_docker/typescript.mdx @@ -2,6 +2,7 @@ title: TypeScript Deployment to Docker sidebar: label: "TypeScript" +tags: [deployment, typescript, production] --- This guide covers deploying TypeScript-based Strands agents using Docker for local and cloud development. diff --git a/src/content/docs/user-guide/deploy/deploy_to_kubernetes.mdx b/src/content/docs/user-guide/deploy/deploy_to_kubernetes.mdx index 2a9c13b1f..2d8ed26ca 100644 --- a/src/content/docs/user-guide/deploy/deploy_to_kubernetes.mdx +++ b/src/content/docs/user-guide/deploy/deploy_to_kubernetes.mdx @@ -2,6 +2,7 @@ title: Deploy to Kubernetes sidebar: label: "Kubernetes" +tags: [deployment, production] --- This guide covers deploying containerized Strands agents to Kubernetes using Kind (Kubernetes in Docker) for local and cloud development. diff --git a/src/content/docs/user-guide/deploy/deploy_to_terraform.mdx b/src/content/docs/user-guide/deploy/deploy_to_terraform.mdx index 3ec1bc9b9..fbffca25f 100644 --- a/src/content/docs/user-guide/deploy/deploy_to_terraform.mdx +++ b/src/content/docs/user-guide/deploy/deploy_to_terraform.mdx @@ -2,6 +2,7 @@ title: Deploy to Terraform sidebar: label: "Terraform" +tags: [deployment, production] --- This guide covers deploying Strands agents using Terraform infrastructure as code. Terraform enables consistent, repeatable deployments across AWS, Google Cloud, Azure, and other cloud providers. diff --git a/src/content/docs/user-guide/deploy/operating-agents-in-production.mdx b/src/content/docs/user-guide/deploy/operating-agents-in-production.mdx index 957bb279c..22f2d75db 100644 --- a/src/content/docs/user-guide/deploy/operating-agents-in-production.mdx +++ b/src/content/docs/user-guide/deploy/operating-agents-in-production.mdx @@ -1,6 +1,7 @@ --- title: Operating Agents in Production description: "Deploy AI agents to production on AWS Lambda, EKS, Fargate, EC2, or Bedrock AgentCore. Monitoring, scaling, and operational best practices." +tags: [deployment, production, observability] --- This guide provides best practices for deploying Strands agents in production environments, focusing on security, stability, and performance optimization. diff --git a/src/content/docs/user-guide/observability-evaluation/evaluation.mdx b/src/content/docs/user-guide/observability-evaluation/evaluation.mdx index 504a2b6c2..b9a876cfd 100644 --- a/src/content/docs/user-guide/observability-evaluation/evaluation.mdx +++ b/src/content/docs/user-guide/observability-evaluation/evaluation.mdx @@ -1,5 +1,6 @@ --- title: Evaluation +tags: [evaluation, observability] --- This guide covers approaches to evaluating agents. Effective evaluation is essential for measuring agent performance, tracking improvements, and ensuring your agents meet quality standards. diff --git a/src/content/docs/user-guide/observability-evaluation/logs.mdx b/src/content/docs/user-guide/observability-evaluation/logs.mdx index 68bc88bfe..04b5223be 100644 --- a/src/content/docs/user-guide/observability-evaluation/logs.mdx +++ b/src/content/docs/user-guide/observability-evaluation/logs.mdx @@ -2,6 +2,10 @@ title: Logging sidebar: label: "Logs" +tags: [observability] +sourceLinks: + - repo: sdk-typescript + path: strands-ts/src/logging/logger.ts --- The Strands SDK provides logging infrastructure to give visibility into its operations. diff --git a/src/content/docs/user-guide/observability-evaluation/metrics.mdx b/src/content/docs/user-guide/observability-evaluation/metrics.mdx index 0519a1f43..9abe0e6ab 100644 --- a/src/content/docs/user-guide/observability-evaluation/metrics.mdx +++ b/src/content/docs/user-guide/observability-evaluation/metrics.mdx @@ -1,5 +1,11 @@ --- title: Metrics +tags: [observability] +sourceLinks: + - repo: sdk-python + path: src/strands/telemetry/metrics.py + - repo: sdk-typescript + path: strands-ts/src/telemetry/meter.ts --- Metrics are essential for understanding agent performance, optimizing behavior, and monitoring resource usage. The Strands Agents SDK provides comprehensive metrics tracking capabilities that give you visibility into how your agents operate. diff --git a/src/content/docs/user-guide/observability-evaluation/observability.mdx b/src/content/docs/user-guide/observability-evaluation/observability.mdx index e61cf4987..fadd643fb 100644 --- a/src/content/docs/user-guide/observability-evaluation/observability.mdx +++ b/src/content/docs/user-guide/observability-evaluation/observability.mdx @@ -1,6 +1,12 @@ --- title: Observability description: "Monitor AI agents with OpenTelemetry traces, metrics, and logs. Debug agent behavior and measure performance in production." +tags: [observability, production] +sourceLinks: + - repo: sdk-python + path: src/strands/telemetry/config.py + - repo: sdk-typescript + path: strands-ts/src/telemetry/config.ts --- In the Strands Agents SDK, observability refers to the ability to measure system behavior and performance. Observability is the combination of instrumentation, data collection, and analysis techniques that provide insights into an agent's behavior and performance. It enables Strands Agents developers to effectively build, debug and maintain agents to better serve their unique customer needs and reliably complete their tasks. This guide provides background on what type of data (or "Primitives") makes up observability as well as best practices for implementing agent observability with the Strands Agents SDK. diff --git a/src/content/docs/user-guide/observability-evaluation/traces.mdx b/src/content/docs/user-guide/observability-evaluation/traces.mdx index b1f92e9ab..00b80f77e 100644 --- a/src/content/docs/user-guide/observability-evaluation/traces.mdx +++ b/src/content/docs/user-guide/observability-evaluation/traces.mdx @@ -1,5 +1,11 @@ --- title: Traces +tags: [observability] +sourceLinks: + - repo: sdk-python + path: src/strands/telemetry/tracer.py + - repo: sdk-typescript + path: strands-ts/src/telemetry/tracer.ts --- Tracing is a fundamental component of the Strands SDK's observability framework, providing detailed insights into your agent's execution. Using the OpenTelemetry standard, Strands traces capture the complete journey of a request through your agent, including LLM interactions, retrievers, tool usage, and event loop processing. diff --git a/src/content/docs/user-guide/quickstart/overview.mdx b/src/content/docs/user-guide/quickstart/overview.mdx index 44cdc8a64..df8098592 100644 --- a/src/content/docs/user-guide/quickstart/overview.mdx +++ b/src/content/docs/user-guide/quickstart/overview.mdx @@ -6,6 +6,7 @@ sidebar: redirectFrom: - docs - docs/user-guide/quickstart +tags: [quickstart] --- import { LinkCard, CardGrid } from '@astrojs/starlight/components'; diff --git a/src/content/docs/user-guide/quickstart/python.mdx b/src/content/docs/user-guide/quickstart/python.mdx index d7e962dff..ff0db44f7 100644 --- a/src/content/docs/user-guide/quickstart/python.mdx +++ b/src/content/docs/user-guide/quickstart/python.mdx @@ -3,6 +3,7 @@ title: Python Quickstart description: "Get an AI agent running in Python in under 5 minutes. Install the SDK, configure a model provider, and build your first agent." sidebar: label: "Python" +tags: [quickstart, python] --- This quickstart guide shows you how to create your first basic Strands agent, add built-in and custom tools to your agent, use different model providers, emit debug logs, and run the agent locally. diff --git a/src/content/docs/user-guide/quickstart/typescript.mdx b/src/content/docs/user-guide/quickstart/typescript.mdx index bbae0dafb..f21568b26 100644 --- a/src/content/docs/user-guide/quickstart/typescript.mdx +++ b/src/content/docs/user-guide/quickstart/typescript.mdx @@ -3,6 +3,7 @@ title: TypeScript Quickstart description: "Get an AI agent running in TypeScript in under 5 minutes. Install the SDK, configure a model provider, and build your first agent." sidebar: label: "TypeScript" +tags: [quickstart, typescript] --- This quickstart guide shows you how to create your first basic Strands agent with TypeScript, add built-in and custom tools to your agent, use different model providers, emit debug logs, and run the agent locally. diff --git a/src/content/docs/user-guide/safety-security/guardrails.mdx b/src/content/docs/user-guide/safety-security/guardrails.mdx index bd5641276..8e70a4df4 100644 --- a/src/content/docs/user-guide/safety-security/guardrails.mdx +++ b/src/content/docs/user-guide/safety-security/guardrails.mdx @@ -1,6 +1,10 @@ --- title: Guardrails description: "Add safety guardrails to AI agents. Control tool permissions, validate outputs, and enforce responsible AI policies in production." +tags: [safety, guardrails, bedrock, production] +sourceLinks: + - repo: sdk-python + path: src/strands/models/bedrock.py --- Strands Agents SDK provides seamless integration with guardrails, enabling you to implement content filtering, topic blocking, PII protection, and other safety measures in your AI applications. diff --git a/src/content/docs/user-guide/safety-security/pii-redaction.mdx b/src/content/docs/user-guide/safety-security/pii-redaction.mdx index 840c1db67..17108c8bf 100644 --- a/src/content/docs/user-guide/safety-security/pii-redaction.mdx +++ b/src/content/docs/user-guide/safety-security/pii-redaction.mdx @@ -1,5 +1,6 @@ --- title: PII Redaction +tags: [safety, pii, production] --- PII redaction is a critical aspect of protecting personal information. This document provides clear instructions and recommended practices for safely handling PII, including guidance on integrating third-party redaction solutions with Strands SDK. diff --git a/src/content/docs/user-guide/safety-security/prompt-engineering.mdx b/src/content/docs/user-guide/safety-security/prompt-engineering.mdx index 5176003f5..2a98a92ce 100644 --- a/src/content/docs/user-guide/safety-security/prompt-engineering.mdx +++ b/src/content/docs/user-guide/safety-security/prompt-engineering.mdx @@ -1,5 +1,6 @@ --- title: Prompt Engineering +tags: [safety] --- Effective prompt engineering is crucial not only for maximizing Strands Agents' capabilities but also for securing against LLM-based threats. This guide outlines key techniques for creating secure prompts that enhance reliability, specificity, and performance, while protecting against common attack vectors. It's always recommended to systematically test prompts across varied inputs, comparing variations to identify potential vulnerabilities. Security testing should also include adversarial examples to verify prompt robustness against potential attacks. diff --git a/src/content/docs/user-guide/safety-security/responsible-ai.mdx b/src/content/docs/user-guide/safety-security/responsible-ai.mdx index 52d4076e9..682c1839a 100644 --- a/src/content/docs/user-guide/safety-security/responsible-ai.mdx +++ b/src/content/docs/user-guide/safety-security/responsible-ai.mdx @@ -1,5 +1,6 @@ --- title: Responsible AI +tags: [safety] --- Strands Agents SDK provides powerful capabilities for building AI agents with access to tools and external resources. With this power comes the responsibility to ensure your AI applications are developed and deployed in an ethical, safe, and beneficial manner. This guide outlines best practices for responsible AI usage with the Strands Agents SDK. Please also reference our [Prompt Engineering](./prompt-engineering.md) page for guidance on how to effectively create agents that align with responsible AI usage, and [Guardrails](./guardrails.md) page for how to add mechanisms to ensure safety and security. diff --git a/src/util/related-docs.ts b/src/util/related-docs.ts new file mode 100644 index 000000000..78d761c11 --- /dev/null +++ b/src/util/related-docs.ts @@ -0,0 +1,57 @@ +/** + * Compute "Related pages" for user-guide docs via tag overlap. + * + * Called from src/util/render-to-markdown.ts (markdown/llms surfaces) and + * src/components/overrides/Head.astro (JSON-LD). + * + * Each candidate is scored by the count of tags it shares with the current + * page (NOT by how many tags it has in total — a candidate with 8 unrelated + * tags scores 0 and is excluded). The result is the top N candidates by + * shared-tag count. + * + * Algorithm choices (deliberately simple — this output is LLM-facing): + * • Flat overlap score (count of shared tags). Predictable for authors: they + * can read two pages' frontmatter and guess the result. TF-IDF / rarity + * weighting would add opacity for negligible gain on ~120 tagged pages. + * • Require ≥1 shared tag. Raising to ≥2 would starve many single-tag pages + * that legitimately bridge sections (e.g. a page tagged only [hooks]). + * • Alphabetical tie-break on title. Deterministic across rebuilds. + * • Cap at 10. This output goes to //index.md and llms-full.txt — no + * UI budget to respect; 10 extra bullets is rounding-error tokens and + * lets LLMs self-filter from a wider recall set. + */ +import type { CollectionEntry } from 'astro:content' + +export interface RelatedLink { + slug: string + title: string + overlap: number +} + +const MAX_RELATED = 10 +const USER_GUIDE_PREFIX = 'docs/user-guide/' + +function isUserGuide(entry: CollectionEntry<'docs'>): boolean { + return entry.id.startsWith(USER_GUIDE_PREFIX) +} + +export function relatedUserGuideFor( + current: CollectionEntry<'docs'>, + allDocs: readonly CollectionEntry<'docs'>[], +): RelatedLink[] { + if (!isUserGuide(current)) return [] + const currentTags = current.data.tags + if (currentTags.length === 0) return [] + const tagSet = new Set(currentTags) + + return allDocs + .filter((d) => d.id !== current.id && isUserGuide(d) && d.data.tags.length > 0) + .map((d) => ({ + doc: d, + overlap: d.data.tags.reduce((n, t) => n + (tagSet.has(t) ? 1 : 0), 0), + })) + .filter((s) => s.overlap > 0) + .sort((a, b) => b.overlap - a.overlap || a.doc.data.title.localeCompare(b.doc.data.title)) + .slice(0, MAX_RELATED) + .map(({ doc, overlap }) => ({ slug: doc.id, title: doc.data.title, overlap })) +} diff --git a/src/util/render-to-markdown.ts b/src/util/render-to-markdown.ts index fad22c5e7..7b4f8c156 100644 --- a/src/util/render-to-markdown.ts +++ b/src/util/render-to-markdown.ts @@ -1,10 +1,47 @@ import type { CollectionEntry } from 'astro:content' -import { render } from 'astro:content' +import { getCollection, render } from 'astro:content' import { experimental_AstroContainer } from 'astro/container' import { loadRenderers } from 'astro:container' import { getContainerRenderer } from '@astrojs/mdx' import { htmlToMarkdown } from './html-to-markdown' import { pathWithBase } from './links' +import { relatedUserGuideFor } from './related-docs' +import type { SourceLink } from '../content.config' + +/** + * Render the "Related pages" block for headless consumers. Appended only to + * markdown surfaces (//index.md, /llms-full.txt) — never the HTML page. + */ +async function renderRelatedPages( + entry: CollectionEntry<'docs'> | CollectionEntry<'blog'>, + allDocs?: readonly CollectionEntry<'docs'>[], +): Promise { + if (entry.collection !== 'docs') return '' + const docs = allDocs ?? await getCollection('docs') + const related = relatedUserGuideFor(entry, docs) + if (related.length === 0) return '' + const items = related.map((r) => { + const tagLabel = r.overlap === 1 ? '1 shared tag' : `${r.overlap} shared tags` + return `- [${r.title}](${pathWithBase(`/${r.slug}/`)}index.md) (${tagLabel})` + }) + return `\n\n## Related pages\n\n${items.join('\n')}\n` +} + +/** + * Render the "Implementation" block for headless consumers. Appended only to + * the markdown surfaces (//index.md, /llms-full.txt) — never the HTML + * page. Link text and URL both embed repo+path so parsers can extract either. + */ +function renderImplementation(entry: CollectionEntry<'docs'> | CollectionEntry<'blog'>): string { + if (entry.collection !== 'docs') return '' + const links: SourceLink[] | undefined = entry.data.sourceLinks + if (!links || links.length === 0) return '' + const items = links.map(({ repo, path }) => { + const url = `https://github.com/strands-agents/${repo}/blob/main/${path}` + return `- [${repo}/${path}](${url})` + }) + return `\n\n## Implementation\n\n${items.join('\n')}\n` +} /** * Renders a content collection entry to markdown. @@ -17,6 +54,7 @@ import { pathWithBase } from './links' export async function renderEntryToMarkdown( entry: CollectionEntry<'docs'> | CollectionEntry<'blog'>, basePath?: string, + allDocs?: readonly CollectionEntry<'docs'>[], ): Promise<{ markdown: string, html: string }> { const data = await render(entry) const { Content } = data @@ -31,5 +69,8 @@ export async function renderEntryToMarkdown( request: new Request(pageUrl), }) - return { markdown: htmlToMarkdown(html), html: html } + const body = htmlToMarkdown(html) + const related = await renderRelatedPages(entry, allDocs) + const implementation = renderImplementation(entry) + return { markdown: body + related + implementation, html } } diff --git a/test/related-docs.test.ts b/test/related-docs.test.ts new file mode 100644 index 000000000..9ad486400 --- /dev/null +++ b/test/related-docs.test.ts @@ -0,0 +1,86 @@ +import { describe, it, expect } from 'vitest' +import type { CollectionEntry } from 'astro:content' +import { relatedUserGuideFor } from '../src/util/related-docs' + +function doc(id: string, title: string, tags: string[]): CollectionEntry<'docs'> { + return { id, collection: 'docs', data: { title, tags } } as unknown as CollectionEntry<'docs'> +} + +describe('relatedUserGuideFor', () => { + it('ranks pages by tag-overlap size, descending', () => { + const current = doc('docs/user-guide/a', 'A', ['x', 'y', 'z']) + const two = doc('docs/user-guide/b', 'B', ['x', 'y']) + const one = doc('docs/user-guide/c', 'C', ['x']) + + const result = relatedUserGuideFor(current, [current, one, two]) + expect(result.map((r) => r.title)).toEqual(['B', 'C']) + }) + + it('breaks overlap ties alphabetically by title', () => { + const current = doc('docs/user-guide/a', 'A', ['x']) + const zebra = doc('docs/user-guide/z', 'Zebra', ['x']) + const apple = doc('docs/user-guide/b', 'Apple', ['x']) + + const result = relatedUserGuideFor(current, [current, zebra, apple]) + expect(result.map((r) => r.title)).toEqual(['Apple', 'Zebra']) + }) + + it('excludes the current page from its own results', () => { + const current = doc('docs/user-guide/a', 'A', ['x']) + const other = doc('docs/user-guide/b', 'B', ['x']) + + const result = relatedUserGuideFor(current, [current, other]) + expect(result.map((r) => r.slug)).toEqual(['docs/user-guide/b']) + }) + + it('returns empty when the current page has no tags', () => { + const current = doc('docs/user-guide/a', 'A', []) + const other = doc('docs/user-guide/b', 'B', ['x']) + + expect(relatedUserGuideFor(current, [current, other])).toEqual([]) + }) + + it('returns empty when no other page shares a tag', () => { + const current = doc('docs/user-guide/a', 'A', ['x']) + const other = doc('docs/user-guide/b', 'B', ['y']) + + expect(relatedUserGuideFor(current, [current, other])).toEqual([]) + }) + + it('ignores candidates outside the user-guide tree', () => { + const current = doc('docs/user-guide/a', 'A', ['x']) + const blogLike = doc('docs/community/b', 'B', ['x']) + const userGuide = doc('docs/user-guide/c', 'C', ['x']) + + const result = relatedUserGuideFor(current, [current, blogLike, userGuide]) + expect(result.map((r) => r.slug)).toEqual(['docs/user-guide/c']) + }) + + it('returns empty when the current page is not in the user-guide tree', () => { + const current = doc('docs/community/a', 'A', ['x']) + const other = doc('docs/user-guide/b', 'B', ['x']) + + expect(relatedUserGuideFor(current, [current, other])).toEqual([]) + }) + + it('caps at 10 matches', () => { + const current = doc('docs/user-guide/a', 'A', ['x']) + const candidates = Array.from({ length: 12 }, (_, i) => + doc(`docs/user-guide/${i}`, `T${i}`, ['x']) + ) + + expect(relatedUserGuideFor(current, [current, ...candidates])).toHaveLength(10) + }) + + it('reports overlap count on each result', () => { + const current = doc('docs/user-guide/a', 'A', ['x', 'y', 'z']) + const two = doc('docs/user-guide/b', 'B', ['x', 'y']) + const one = doc('docs/user-guide/c', 'C', ['x']) + + const result = relatedUserGuideFor(current, [current, one, two]) + expect(result).toEqual([ + { slug: 'docs/user-guide/b', title: 'B', overlap: 2 }, + { slug: 'docs/user-guide/c', title: 'C', overlap: 1 }, + ]) + }) +}) From 1644cc9cf7859b992c472b836948eab2f4508093 Mon Sep 17 00:00:00 2001 From: Owen Kaplan Date: Tue, 12 May 2026 10:55:41 -0400 Subject: [PATCH 2/5] fix: remove source references in frontmatter; add related pages to user facing page; add title uniqueness test --- src/components/RelatedPagesInline.astro | 75 +++++++++++++++++++ .../overrides/MarkdownContent.astro | 2 + .../user-guide/concepts/agents/agent-loop.mdx | 5 -- .../agents/conversation-management.mdx | 5 -- .../docs/user-guide/concepts/agents/hooks.mdx | 9 --- .../user-guide/concepts/agents/prompts.mdx | 5 -- .../concepts/agents/retry-strategies.mdx | 5 -- .../concepts/agents/session-management.mdx | 5 -- .../docs/user-guide/concepts/agents/state.mdx | 5 -- .../concepts/agents/structured-output.mdx | 5 -- .../bidirectional-streaming/agent.mdx | 3 - .../bidirectional-streaming/events.mdx | 3 - .../bidirectional-streaming/hooks.mdx | 7 +- .../bidirectional-streaming/interruption.mdx | 3 - .../concepts/bidirectional-streaming/io.mdx | 5 -- .../models/gemini_live.mdx | 3 - .../models/nova_sonic.mdx | 3 - .../models/openai_realtime.mdx | 3 - .../session-management.mdx | 7 +- .../docs/user-guide/concepts/interrupts.mdx | 5 -- .../model-providers/amazon-bedrock.mdx | 5 -- .../concepts/model-providers/amazon-nova.mdx | 3 - .../concepts/model-providers/anthropic.mdx | 5 -- .../model-providers/custom_model_provider.mdx | 5 -- .../concepts/model-providers/google.mdx | 5 -- .../concepts/model-providers/litellm.mdx | 3 - .../concepts/model-providers/llamaapi.mdx | 3 - .../concepts/model-providers/llamacpp.mdx | 3 - .../concepts/model-providers/mistral.mdx | 3 - .../concepts/model-providers/ollama.mdx | 3 - .../model-providers/openai-responses.mdx | 5 -- .../concepts/model-providers/openai.mdx | 5 -- .../concepts/model-providers/sagemaker.mdx | 3 - .../concepts/model-providers/vercel.mdx | 3 - .../concepts/model-providers/writer.mdx | 3 - .../concepts/multi-agent/agent-to-agent.mdx | 9 --- .../concepts/multi-agent/agents-as-tools.mdx | 5 -- .../user-guide/concepts/multi-agent/graph.mdx | 5 -- .../multi-agent/multi-agent-patterns.mdx | 5 -- .../user-guide/concepts/multi-agent/swarm.mdx | 5 -- .../concepts/plugins/context-offloader.mdx | 5 -- .../user-guide/concepts/plugins/index.mdx | 9 --- .../user-guide/concepts/plugins/skills.mdx | 5 -- .../user-guide/concepts/plugins/steering.mdx | 5 -- .../concepts/streaming/async-iterators.mdx | 3 - .../concepts/streaming/callback-handlers.mdx | 3 - .../user-guide/concepts/streaming/index.mdx | 5 -- .../concepts/tools/custom-tools.mdx | 5 -- .../user-guide/concepts/tools/executors.mdx | 7 -- .../docs/user-guide/concepts/tools/index.mdx | 5 -- .../user-guide/concepts/tools/mcp-tools.mdx | 7 -- .../concepts/tools/vended-tools.mdx | 9 --- .../observability-evaluation/logs.mdx | 3 - .../observability-evaluation/metrics.mdx | 5 -- .../observability.mdx | 5 -- .../observability-evaluation/traces.mdx | 5 -- .../user-guide/safety-security/guardrails.mdx | 3 - src/util/related-docs.ts | 8 +- test/content-collection.test.ts | 28 +++++++ 59 files changed, 116 insertions(+), 258 deletions(-) create mode 100644 src/components/RelatedPagesInline.astro diff --git a/src/components/RelatedPagesInline.astro b/src/components/RelatedPagesInline.astro new file mode 100644 index 000000000..7bf1d6d4d --- /dev/null +++ b/src/components/RelatedPagesInline.astro @@ -0,0 +1,75 @@ +--- +/** + * Quiet "See also" list rendered at the end of the article body, above + * Starlight's Prev/Next pagination. Reads as a caption, not navigation — + * complements the linear Prev/Next with lateral topical jumps. + * + * Display cap (4) differs from the headless cap (10) in related-docs.ts: + * humans can only scan a handful of links before it becomes noise. + */ +import { getCollection } from 'astro:content' +import { relatedUserGuideFor } from '../util/related-docs' +import { pathWithBase } from '../util/links' + +const MAX_DISPLAY = 4 + +const { starlightRoute } = Astro.locals +const entry = starlightRoute.entry +// Non-docs routes (blog pages, StarlightPage splashes) flow through +// MarkdownContent too — short-circuit before calling into the util. +const related = entry.collection === 'docs' + ? relatedUserGuideFor(entry, await getCollection('docs')).slice(0, MAX_DISPLAY) + : [] +--- + +{related.length > 0 && ( + +)} + + diff --git a/src/components/overrides/MarkdownContent.astro b/src/components/overrides/MarkdownContent.astro index daaf66972..bf56c48d2 100644 --- a/src/components/overrides/MarkdownContent.astro +++ b/src/components/overrides/MarkdownContent.astro @@ -3,6 +3,7 @@ import '@astrojs/starlight/style/markdown.css'; import CommunityContributionAside from '../CommunityContributionAside.astro'; import LanguageSupportAside from '../LanguageSupportAside.astro'; import ExperimentalAside from '../ExperimentalAside.astro'; +import RelatedPagesInline from '../RelatedPagesInline.astro'; const { starlightRoute } = Astro.locals; const { languages, community, experimental } = starlightRoute.entry.data; @@ -15,4 +16,5 @@ const { languages, community, experimental } = starlightRoute.entry.data; contextualizes the page, and language support is listed in the community catalog table instead. */} {languages && !community && } + diff --git a/src/content/docs/user-guide/concepts/agents/agent-loop.mdx b/src/content/docs/user-guide/concepts/agents/agent-loop.mdx index bb565123b..52f9c8d25 100644 --- a/src/content/docs/user-guide/concepts/agents/agent-loop.mdx +++ b/src/content/docs/user-guide/concepts/agents/agent-loop.mdx @@ -1,11 +1,6 @@ --- title: Agent Loop description: "How Strands agents reason, plan, and act. Understand the model-driven loop that orchestrates tool use, reflection, and goal completion." -sourceLinks: - - repo: sdk-python - path: src/strands/event_loop/event_loop.py - - repo: sdk-typescript - path: strands-ts/src/agent/agent.ts --- A language model can answer questions. An agent can *do things*. The agent loop is what makes that difference possible. diff --git a/src/content/docs/user-guide/concepts/agents/conversation-management.mdx b/src/content/docs/user-guide/concepts/agents/conversation-management.mdx index bba21842d..662a0ce98 100644 --- a/src/content/docs/user-guide/concepts/agents/conversation-management.mdx +++ b/src/content/docs/user-guide/concepts/agents/conversation-management.mdx @@ -1,11 +1,6 @@ --- title: Conversation Management tags: [conversation-management] -sourceLinks: - - repo: sdk-python - path: src/strands/agent/conversation_manager/conversation_manager.py - - repo: sdk-typescript - path: strands-ts/src/conversation-manager/conversation-manager.ts --- In the Strands Agents SDK, context refers to the information provided to the agent for understanding and reasoning. This includes: diff --git a/src/content/docs/user-guide/concepts/agents/hooks.mdx b/src/content/docs/user-guide/concepts/agents/hooks.mdx index b90ab5736..9978a6f9a 100644 --- a/src/content/docs/user-guide/concepts/agents/hooks.mdx +++ b/src/content/docs/user-guide/concepts/agents/hooks.mdx @@ -2,15 +2,6 @@ title: Hooks description: "Intercept and customize agent behavior at every step. Hooks let you add logging, validation, guardrails, and custom logic to the agent loop." tags: [hooks] -sourceLinks: - - repo: sdk-python - path: src/strands/hooks/registry.py - - repo: sdk-python - path: src/strands/hooks/events.py - - repo: sdk-typescript - path: strands-ts/src/hooks/registry.ts - - repo: sdk-typescript - path: strands-ts/src/hooks/events.ts --- diff --git a/src/content/docs/user-guide/concepts/agents/prompts.mdx b/src/content/docs/user-guide/concepts/agents/prompts.mdx index 79171bda8..aff56a6b5 100644 --- a/src/content/docs/user-guide/concepts/agents/prompts.mdx +++ b/src/content/docs/user-guide/concepts/agents/prompts.mdx @@ -1,10 +1,5 @@ --- title: Prompts -sourceLinks: - - repo: sdk-python - path: src/strands/agent/agent.py - - repo: sdk-typescript - path: strands-ts/src/agent/agent.ts --- In the Strands Agents SDK, system prompts and user messages are the primary way to communicate with AI models. The SDK provides a flexible system for managing prompts, including both system prompts and user messages. diff --git a/src/content/docs/user-guide/concepts/agents/retry-strategies.mdx b/src/content/docs/user-guide/concepts/agents/retry-strategies.mdx index 042b212cb..041c56217 100644 --- a/src/content/docs/user-guide/concepts/agents/retry-strategies.mdx +++ b/src/content/docs/user-guide/concepts/agents/retry-strategies.mdx @@ -1,11 +1,6 @@ --- title: Retry Strategies tags: [retry] -sourceLinks: - - repo: sdk-python - path: src/strands/event_loop/_retry.py - - repo: sdk-typescript - path: strands-ts/src/retry/retry-strategy.ts --- Model providers occasionally encounter errors such as rate limits, service unavailability, or network timeouts. By default, the agent retries `ModelThrottledException` failures automatically with exponential backoff and the `Angent.retry_strategy` parameter lets you customize this behavior. diff --git a/src/content/docs/user-guide/concepts/agents/session-management.mdx b/src/content/docs/user-guide/concepts/agents/session-management.mdx index cae1bf8ed..58097507f 100644 --- a/src/content/docs/user-guide/concepts/agents/session-management.mdx +++ b/src/content/docs/user-guide/concepts/agents/session-management.mdx @@ -2,11 +2,6 @@ title: Session Management description: "Persist agent conversations across sessions. Save and restore chat history, tool state, and context for long-running AI workflows." tags: [session-management] -sourceLinks: - - repo: sdk-python - path: src/strands/session/session_manager.py - - repo: sdk-typescript - path: strands-ts/src/session/session-manager.ts --- Session management in Strands Agents provides a robust mechanism for persisting agent state and conversation history across multiple interactions. This enables agents to maintain context and continuity even when the application restarts or when deployed in distributed environments. diff --git a/src/content/docs/user-guide/concepts/agents/state.mdx b/src/content/docs/user-guide/concepts/agents/state.mdx index 46fbf6d43..8b38e68b1 100644 --- a/src/content/docs/user-guide/concepts/agents/state.mdx +++ b/src/content/docs/user-guide/concepts/agents/state.mdx @@ -3,11 +3,6 @@ title: State Management sidebar: label: "State" tags: [state] -sourceLinks: - - repo: sdk-python - path: src/strands/agent/state.py - - repo: sdk-typescript - path: strands-ts/src/state-store.ts --- Strands Agents state is maintained in several forms: diff --git a/src/content/docs/user-guide/concepts/agents/structured-output.mdx b/src/content/docs/user-guide/concepts/agents/structured-output.mdx index ec85ff4dc..184dff90b 100644 --- a/src/content/docs/user-guide/concepts/agents/structured-output.mdx +++ b/src/content/docs/user-guide/concepts/agents/structured-output.mdx @@ -2,11 +2,6 @@ title: Structured Output description: "Get typed, validated responses from AI agents. Define Pydantic models and Strands returns structured data instead of raw text." tags: [structured-output] -sourceLinks: - - repo: sdk-python - path: src/strands/tools/structured_output/structured_output_tool.py - - repo: sdk-typescript - path: strands-ts/src/tools/structured-output-tool.ts --- ## Introduction diff --git a/src/content/docs/user-guide/concepts/bidirectional-streaming/agent.mdx b/src/content/docs/user-guide/concepts/bidirectional-streaming/agent.mdx index 49034c4cd..ecb241a63 100644 --- a/src/content/docs/user-guide/concepts/bidirectional-streaming/agent.mdx +++ b/src/content/docs/user-guide/concepts/bidirectional-streaming/agent.mdx @@ -2,9 +2,6 @@ title: BidiAgent experimental: true tags: [streaming] -sourceLinks: - - repo: sdk-python - path: src/strands/experimental/bidi/agent/agent.py --- diff --git a/src/content/docs/user-guide/concepts/bidirectional-streaming/events.mdx b/src/content/docs/user-guide/concepts/bidirectional-streaming/events.mdx index db6f83c9c..7bab93189 100644 --- a/src/content/docs/user-guide/concepts/bidirectional-streaming/events.mdx +++ b/src/content/docs/user-guide/concepts/bidirectional-streaming/events.mdx @@ -2,9 +2,6 @@ title: Events experimental: true tags: [streaming] -sourceLinks: - - repo: sdk-python - path: src/strands/experimental/bidi/types/events.py --- diff --git a/src/content/docs/user-guide/concepts/bidirectional-streaming/hooks.mdx b/src/content/docs/user-guide/concepts/bidirectional-streaming/hooks.mdx index 826616e5b..47d7d2a92 100644 --- a/src/content/docs/user-guide/concepts/bidirectional-streaming/hooks.mdx +++ b/src/content/docs/user-guide/concepts/bidirectional-streaming/hooks.mdx @@ -1,10 +1,9 @@ --- -title: Hooks +title: Bidirectional Streaming Hooks +sidebar: + label: "Hooks" experimental: true tags: [hooks, streaming] -sourceLinks: - - repo: sdk-python - path: src/strands/experimental/hooks/events.py --- diff --git a/src/content/docs/user-guide/concepts/bidirectional-streaming/interruption.mdx b/src/content/docs/user-guide/concepts/bidirectional-streaming/interruption.mdx index 157a0dc4f..0ccaf18eb 100644 --- a/src/content/docs/user-guide/concepts/bidirectional-streaming/interruption.mdx +++ b/src/content/docs/user-guide/concepts/bidirectional-streaming/interruption.mdx @@ -2,9 +2,6 @@ title: Interruptions experimental: true tags: [streaming] -sourceLinks: - - repo: sdk-python - path: src/strands/experimental/bidi/agent/loop.py --- diff --git a/src/content/docs/user-guide/concepts/bidirectional-streaming/io.mdx b/src/content/docs/user-guide/concepts/bidirectional-streaming/io.mdx index c84c668cb..5c2b986b9 100644 --- a/src/content/docs/user-guide/concepts/bidirectional-streaming/io.mdx +++ b/src/content/docs/user-guide/concepts/bidirectional-streaming/io.mdx @@ -4,11 +4,6 @@ experimental: true sidebar: label: "IO" tags: [streaming] -sourceLinks: - - repo: sdk-python - path: src/strands/experimental/bidi/io/audio.py - - repo: sdk-python - path: src/strands/experimental/bidi/io/text.py --- diff --git a/src/content/docs/user-guide/concepts/bidirectional-streaming/models/gemini_live.mdx b/src/content/docs/user-guide/concepts/bidirectional-streaming/models/gemini_live.mdx index 436055d73..bb4d5a163 100644 --- a/src/content/docs/user-guide/concepts/bidirectional-streaming/models/gemini_live.mdx +++ b/src/content/docs/user-guide/concepts/bidirectional-streaming/models/gemini_live.mdx @@ -2,9 +2,6 @@ title: Gemini Live experimental: true tags: [streaming] -sourceLinks: - - repo: sdk-python - path: src/strands/experimental/bidi/models/gemini_live.py --- diff --git a/src/content/docs/user-guide/concepts/bidirectional-streaming/models/nova_sonic.mdx b/src/content/docs/user-guide/concepts/bidirectional-streaming/models/nova_sonic.mdx index d8d0fdb7e..b858578f7 100644 --- a/src/content/docs/user-guide/concepts/bidirectional-streaming/models/nova_sonic.mdx +++ b/src/content/docs/user-guide/concepts/bidirectional-streaming/models/nova_sonic.mdx @@ -2,9 +2,6 @@ title: Nova Sonic experimental: true tags: [streaming, aws, bedrock] -sourceLinks: - - repo: sdk-python - path: src/strands/experimental/bidi/models/nova_sonic.py --- diff --git a/src/content/docs/user-guide/concepts/bidirectional-streaming/models/openai_realtime.mdx b/src/content/docs/user-guide/concepts/bidirectional-streaming/models/openai_realtime.mdx index 73a314768..e957e6559 100644 --- a/src/content/docs/user-guide/concepts/bidirectional-streaming/models/openai_realtime.mdx +++ b/src/content/docs/user-guide/concepts/bidirectional-streaming/models/openai_realtime.mdx @@ -2,9 +2,6 @@ title: OpenAI Realtime experimental: true tags: [streaming] -sourceLinks: - - repo: sdk-python - path: src/strands/experimental/bidi/models/openai_realtime.py --- diff --git a/src/content/docs/user-guide/concepts/bidirectional-streaming/session-management.mdx b/src/content/docs/user-guide/concepts/bidirectional-streaming/session-management.mdx index 7a5f1db1d..44d2c019a 100644 --- a/src/content/docs/user-guide/concepts/bidirectional-streaming/session-management.mdx +++ b/src/content/docs/user-guide/concepts/bidirectional-streaming/session-management.mdx @@ -1,10 +1,9 @@ --- -title: Session Management +title: Bidirectional Streaming Session Management +sidebar: + label: "Session Management" experimental: true tags: [session-management, streaming] -sourceLinks: - - repo: sdk-python - path: src/strands/experimental/checkpoint/checkpoint.py --- diff --git a/src/content/docs/user-guide/concepts/interrupts.mdx b/src/content/docs/user-guide/concepts/interrupts.mdx index bd95773c2..0ffd16005 100644 --- a/src/content/docs/user-guide/concepts/interrupts.mdx +++ b/src/content/docs/user-guide/concepts/interrupts.mdx @@ -1,11 +1,6 @@ --- title: Interrupts description: "Pause AI agents mid-execution for human approval, input, or review. Build human-in-the-loop workflows with interrupt and resume patterns." -sourceLinks: - - repo: sdk-python - path: src/strands/interrupt.py - - repo: sdk-typescript - path: strands-ts/src/interrupt.ts --- The interrupt system enables human-in-the-loop workflows by allowing users to pause agent execution and request human input before continuing. When an interrupt is raised, the agent stops its loop and returns control to the user. The user in turn provides a response to the agent. The agent then continues its execution starting from the point of interruption. Users can raise interrupts from either hook callbacks or tool definitions. The general flow looks as follows: diff --git a/src/content/docs/user-guide/concepts/model-providers/amazon-bedrock.mdx b/src/content/docs/user-guide/concepts/model-providers/amazon-bedrock.mdx index 6a34e0733..4d4d1de45 100644 --- a/src/content/docs/user-guide/concepts/model-providers/amazon-bedrock.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/amazon-bedrock.mdx @@ -2,11 +2,6 @@ title: Amazon Bedrock integrationType: model-provider tags: [bedrock, aws] -sourceLinks: - - repo: sdk-python - path: src/strands/models/bedrock.py - - repo: sdk-typescript - path: strands-ts/src/models/bedrock.ts --- Amazon Bedrock is a fully managed service that offers a choice of high-performing foundation models from leading AI companies through a unified API. Strands provides native support for Amazon Bedrock, allowing you to use these powerful models in your agents with minimal configuration. diff --git a/src/content/docs/user-guide/concepts/model-providers/amazon-nova.mdx b/src/content/docs/user-guide/concepts/model-providers/amazon-nova.mdx index c88fc4636..301fe25fe 100644 --- a/src/content/docs/user-guide/concepts/model-providers/amazon-nova.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/amazon-nova.mdx @@ -3,9 +3,6 @@ title: Amazon Nova languages: Python integrationType: model-provider tags: [aws, bedrock] -sourceLinks: - - repo: sdk-python - path: src/strands/models/bedrock.py --- [Amazon Nova](https://nova.amazon.com/) is a new generation of foundation models with frontier intelligence and industry leading price performance. Generate text, code, and images with natural language prompts. The [`strands-amazon-nova`](https://pypi.org/project/strands-amazon-nova/) package ([GitHub](https://github.com/amazon-nova-api/strands-nova)) provides an integration for the Strands Agents SDK, enabling seamless use of Amazon Nova models. diff --git a/src/content/docs/user-guide/concepts/model-providers/anthropic.mdx b/src/content/docs/user-guide/concepts/model-providers/anthropic.mdx index 03655d912..af004a171 100644 --- a/src/content/docs/user-guide/concepts/model-providers/anthropic.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/anthropic.mdx @@ -1,11 +1,6 @@ --- title: Anthropic integrationType: model-provider -sourceLinks: - - repo: sdk-python - path: src/strands/models/anthropic.py - - repo: sdk-typescript - path: strands-ts/src/models/anthropic.ts --- [Anthropic](https://docs.anthropic.com/en/home) is an AI safety and research company focused on building reliable, interpretable, and steerable AI systems. Included in their offerings is the Claude AI family of models, which are known for their conversational abilities, careful reasoning, and capacity to follow complex instructions. The Strands Agents SDK implements an Anthropic provider, allowing users to run agents against Claude models directly. diff --git a/src/content/docs/user-guide/concepts/model-providers/custom_model_provider.mdx b/src/content/docs/user-guide/concepts/model-providers/custom_model_provider.mdx index b934d7607..ab4293f2e 100644 --- a/src/content/docs/user-guide/concepts/model-providers/custom_model_provider.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/custom_model_provider.mdx @@ -3,11 +3,6 @@ title: Creating a Custom Model Provider sidebar: label: "Custom Providers" integrationType: model-provider -sourceLinks: - - repo: sdk-python - path: src/strands/models/model.py - - repo: sdk-typescript - path: strands-ts/src/models/model.ts --- Strands Agents SDK provides an extensible interface for implementing custom model providers, allowing organizations to integrate their own LLM services while keeping implementation details private to their codebase. diff --git a/src/content/docs/user-guide/concepts/model-providers/google.mdx b/src/content/docs/user-guide/concepts/model-providers/google.mdx index b335a2118..1f0cfb8dc 100644 --- a/src/content/docs/user-guide/concepts/model-providers/google.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/google.mdx @@ -3,11 +3,6 @@ title: Google integrationType: model-provider redirectFrom: - docs/user-guide/concepts/model-providers/gemini -sourceLinks: - - repo: sdk-python - path: src/strands/models/gemini.py - - repo: sdk-typescript - path: strands-ts/src/models/google/model.ts --- [Google Gemini](https://ai.google.dev/api) is Google's family of multimodal large language models designed for advanced reasoning, code generation, and creative tasks. The Strands Agents SDK implements a Google/Gemini provider, allowing you to run agents against the Gemini models available through Google's AI API. diff --git a/src/content/docs/user-guide/concepts/model-providers/litellm.mdx b/src/content/docs/user-guide/concepts/model-providers/litellm.mdx index d5073f801..da44d0901 100644 --- a/src/content/docs/user-guide/concepts/model-providers/litellm.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/litellm.mdx @@ -2,9 +2,6 @@ title: LiteLLM languages: Python integrationType: model-provider -sourceLinks: - - repo: sdk-python - path: src/strands/models/litellm.py --- [LiteLLM](https://docs.litellm.ai/docs/) is a unified interface for various LLM providers that allows you to interact with models from Amazon, Anthropic, OpenAI, and many others through a single API. The Strands Agents SDK implements a LiteLLM provider, allowing you to run agents against any model LiteLLM supports. diff --git a/src/content/docs/user-guide/concepts/model-providers/llamaapi.mdx b/src/content/docs/user-guide/concepts/model-providers/llamaapi.mdx index ba97ee114..ce5658b30 100644 --- a/src/content/docs/user-guide/concepts/model-providers/llamaapi.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/llamaapi.mdx @@ -4,9 +4,6 @@ languages: Python sidebar: label: "LlamaAPI" integrationType: model-provider -sourceLinks: - - repo: sdk-python - path: src/strands/models/llamaapi.py --- [Llama API](https://llama.developer.meta.com?utm_source=partner-strandsagent&utm_medium=website) is a Meta-hosted API service that helps you integrate Llama models into your applications quickly and efficiently. diff --git a/src/content/docs/user-guide/concepts/model-providers/llamacpp.mdx b/src/content/docs/user-guide/concepts/model-providers/llamacpp.mdx index 61974e8c2..a896ba379 100644 --- a/src/content/docs/user-guide/concepts/model-providers/llamacpp.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/llamacpp.mdx @@ -2,9 +2,6 @@ title: llama.cpp languages: Python integrationType: model-provider -sourceLinks: - - repo: sdk-python - path: src/strands/models/llamacpp.py --- [llama.cpp](https://github.com/ggml-org/llama.cpp) is a high-performance C++ inference engine for running large language models locally. The Strands Agents SDK implements a llama.cpp provider, allowing you to run agents against any llama.cpp server with quantized models. diff --git a/src/content/docs/user-guide/concepts/model-providers/mistral.mdx b/src/content/docs/user-guide/concepts/model-providers/mistral.mdx index 5e819f991..3cccd3f72 100644 --- a/src/content/docs/user-guide/concepts/model-providers/mistral.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/mistral.mdx @@ -4,9 +4,6 @@ languages: Python sidebar: label: "MistralAI" integrationType: model-provider -sourceLinks: - - repo: sdk-python - path: src/strands/models/mistral.py --- [Mistral AI](https://mistral.ai/) is a research lab building the best open source models in the world. diff --git a/src/content/docs/user-guide/concepts/model-providers/ollama.mdx b/src/content/docs/user-guide/concepts/model-providers/ollama.mdx index 6d610ad88..2aaa2faf0 100644 --- a/src/content/docs/user-guide/concepts/model-providers/ollama.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/ollama.mdx @@ -2,9 +2,6 @@ title: Ollama languages: Python integrationType: model-provider -sourceLinks: - - repo: sdk-python - path: src/strands/models/ollama.py --- Ollama is a framework for running open-source large language models locally. Strands provides native support for Ollama, allowing you to use locally-hosted models in your agents. diff --git a/src/content/docs/user-guide/concepts/model-providers/openai-responses.mdx b/src/content/docs/user-guide/concepts/model-providers/openai-responses.mdx index 1ed84aba3..8f2140e20 100644 --- a/src/content/docs/user-guide/concepts/model-providers/openai-responses.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/openai-responses.mdx @@ -1,11 +1,6 @@ --- title: OpenAI Responses API integrationType: model-provider -sourceLinks: - - repo: sdk-python - path: src/strands/models/openai_responses.py - - repo: sdk-typescript - path: strands-ts/src/models/openai/responses-adapter.ts --- The [Responses API](https://platform.openai.com/docs/api-reference/responses) is OpenAI's interface for generating model responses and building agents. It is a superset of the [Chat Completions](./openai) API, with additional support for [built-in tools](#built-in-tools), server-side conversation state management, and multi-modal inputs. diff --git a/src/content/docs/user-guide/concepts/model-providers/openai.mdx b/src/content/docs/user-guide/concepts/model-providers/openai.mdx index 98cd013e3..07a79c030 100644 --- a/src/content/docs/user-guide/concepts/model-providers/openai.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/openai.mdx @@ -1,11 +1,6 @@ --- title: OpenAI integrationType: model-provider -sourceLinks: - - repo: sdk-python - path: src/strands/models/openai.py - - repo: sdk-typescript - path: strands-ts/src/models/openai/model.ts --- [OpenAI](https://platform.openai.com/docs/overview) is an AI research and deployment company that provides a suite of powerful language models. The Strands Agents SDK implements an OpenAI provider, allowing you to run agents against any OpenAI or OpenAI-compatible model. diff --git a/src/content/docs/user-guide/concepts/model-providers/sagemaker.mdx b/src/content/docs/user-guide/concepts/model-providers/sagemaker.mdx index 52fe9d215..a7d8a1f62 100644 --- a/src/content/docs/user-guide/concepts/model-providers/sagemaker.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/sagemaker.mdx @@ -5,9 +5,6 @@ sidebar: label: "SageMaker" integrationType: model-provider tags: [aws] -sourceLinks: - - repo: sdk-python - path: src/strands/models/sagemaker.py --- [Amazon SageMaker](https://aws.amazon.com/sagemaker/) is a fully managed machine learning service that provides infrastructure and tools for building, training, and deploying ML models at scale. The Strands Agents SDK implements a SageMaker provider, allowing you to run agents against models deployed on SageMaker inference endpoints, including both pre-trained models from SageMaker JumpStart and custom fine-tuned models. The provider is designed to work with models that support OpenAI-compatible chat completion APIs. diff --git a/src/content/docs/user-guide/concepts/model-providers/vercel.mdx b/src/content/docs/user-guide/concepts/model-providers/vercel.mdx index f04cb096d..e2dfcc30a 100644 --- a/src/content/docs/user-guide/concepts/model-providers/vercel.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/vercel.mdx @@ -2,9 +2,6 @@ title: Vercel languages: TypeScript integrationType: model-provider -sourceLinks: - - repo: sdk-typescript - path: strands-ts/src/models/vercel.ts --- The [Vercel AI SDK](https://sdk.vercel.ai/) is a TypeScript toolkit for building AI-powered applications. It defines a [Language Model Specification](https://github.com/vercel/ai/tree/main/packages/provider/src/language-model/v3) that standardizes how applications interact with LLMs across providers. The Strands Agents SDK includes a `VercelModel` adapter that wraps any Language Model Specification v3 (`LanguageModelV3`) provider for use as a Strands model provider. diff --git a/src/content/docs/user-guide/concepts/model-providers/writer.mdx b/src/content/docs/user-guide/concepts/model-providers/writer.mdx index 03ab91188..f67dd1a24 100644 --- a/src/content/docs/user-guide/concepts/model-providers/writer.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/writer.mdx @@ -2,9 +2,6 @@ title: Writer languages: Python integrationType: model-provider -sourceLinks: - - repo: sdk-python - path: src/strands/models/writer.py --- [Writer](https://writer.com/) is an enterprise generative AI platform offering specialized Palmyra models for finance, healthcare, creative, and general-purpose use cases. The models excel at tool calling, structured outputs, and domain-specific tasks, with Palmyra X5 supporting a 1M token context window. diff --git a/src/content/docs/user-guide/concepts/multi-agent/agent-to-agent.mdx b/src/content/docs/user-guide/concepts/multi-agent/agent-to-agent.mdx index 51b16c048..6a3d04e8b 100644 --- a/src/content/docs/user-guide/concepts/multi-agent/agent-to-agent.mdx +++ b/src/content/docs/user-guide/concepts/multi-agent/agent-to-agent.mdx @@ -3,15 +3,6 @@ title: Agent-to-Agent (A2A) Protocol sidebar: label: "Agent2Agent (A2A)" tags: [multi-agent] -sourceLinks: - - repo: sdk-python - path: src/strands/multiagent/a2a/server.py - - repo: sdk-python - path: src/strands/agent/a2a_agent.py - - repo: sdk-typescript - path: strands-ts/src/a2a/a2a-agent.ts - - repo: sdk-typescript - path: strands-ts/src/a2a/server.ts --- Strands Agents supports the [Agent-to-Agent (A2A) protocol](https://a2aproject.github.io/A2A/latest/), enabling seamless communication between AI agents across different platforms and implementations. diff --git a/src/content/docs/user-guide/concepts/multi-agent/agents-as-tools.mdx b/src/content/docs/user-guide/concepts/multi-agent/agents-as-tools.mdx index f138ee886..22f363507 100644 --- a/src/content/docs/user-guide/concepts/multi-agent/agents-as-tools.mdx +++ b/src/content/docs/user-guide/concepts/multi-agent/agents-as-tools.mdx @@ -3,11 +3,6 @@ title: Agents as Tools with Strands Agents SDK sidebar: label: "Agents as Tools" tags: [multi-agent, tools] -sourceLinks: - - repo: sdk-python - path: src/strands/agent/_agent_as_tool.py - - repo: sdk-typescript - path: strands-ts/src/agent/agent-as-tool.ts --- ## The Concept: Agents as Tools diff --git a/src/content/docs/user-guide/concepts/multi-agent/graph.mdx b/src/content/docs/user-guide/concepts/multi-agent/graph.mdx index 909fddd04..e528d6955 100644 --- a/src/content/docs/user-guide/concepts/multi-agent/graph.mdx +++ b/src/content/docs/user-guide/concepts/multi-agent/graph.mdx @@ -3,11 +3,6 @@ title: Graph Multi-Agent Pattern sidebar: label: "Graph" tags: [multi-agent] -sourceLinks: - - repo: sdk-python - path: src/strands/multiagent/graph.py - - repo: sdk-typescript - path: strands-ts/src/multiagent/graph.ts --- A Graph is a deterministic directed graph based agent orchestration system where agents, custom nodes, or other multi-agent systems (like [Swarm](./swarm.md) or nested Graphs) are nodes in a graph. Nodes are executed according to edge dependencies, with output from one node passed as input to connected nodes. The Graph pattern supports both acyclic (DAG) and cyclic topologies, enabling feedback loops and iterative refinement workflows. diff --git a/src/content/docs/user-guide/concepts/multi-agent/multi-agent-patterns.mdx b/src/content/docs/user-guide/concepts/multi-agent/multi-agent-patterns.mdx index 7805d731c..775c52821 100644 --- a/src/content/docs/user-guide/concepts/multi-agent/multi-agent-patterns.mdx +++ b/src/content/docs/user-guide/concepts/multi-agent/multi-agent-patterns.mdx @@ -2,11 +2,6 @@ title: Multi-agent Patterns description: "Coordinate multiple AI agents with handoffs, swarms, graphs, and workflow patterns. Built-in primitives for complex multi-agent orchestration." tags: [multi-agent] -sourceLinks: - - repo: sdk-python - path: src/strands/multiagent/base.py - - repo: sdk-typescript - path: strands-ts/src/multiagent/multiagent.ts --- In Strands, building a system with multiple agents or complex tool chains can be approached in several ways. The three primary patterns you'll encounter are Graph, Swarm, and Workflow. While they all aim to solve complex problems, they have differences in their structures, execution workflows, and use cases. diff --git a/src/content/docs/user-guide/concepts/multi-agent/swarm.mdx b/src/content/docs/user-guide/concepts/multi-agent/swarm.mdx index c22445c26..5feffc0b8 100644 --- a/src/content/docs/user-guide/concepts/multi-agent/swarm.mdx +++ b/src/content/docs/user-guide/concepts/multi-agent/swarm.mdx @@ -3,11 +3,6 @@ title: Swarm Multi-Agent Pattern sidebar: label: "Swarm" tags: [multi-agent] -sourceLinks: - - repo: sdk-python - path: src/strands/multiagent/swarm.py - - repo: sdk-typescript - path: strands-ts/src/multiagent/swarm.ts --- A Swarm is a collaborative agent orchestration system where multiple agents work together as a team to solve complex tasks. Unlike traditional sequential or hierarchical multi-agent systems, a Swarm enables autonomous coordination between agents with shared context and working memory. diff --git a/src/content/docs/user-guide/concepts/plugins/context-offloader.mdx b/src/content/docs/user-guide/concepts/plugins/context-offloader.mdx index 4222a6757..c0051f534 100644 --- a/src/content/docs/user-guide/concepts/plugins/context-offloader.mdx +++ b/src/content/docs/user-guide/concepts/plugins/context-offloader.mdx @@ -4,11 +4,6 @@ sidebar: badge: text: New variant: tip -sourceLinks: - - repo: sdk-python - path: src/strands/vended_plugins/context_offloader/plugin.py - - repo: sdk-python - path: src/strands/vended_plugins/context_offloader/storage.py --- The `ContextOffloader` plugin prevents large tool results from consuming your agent's context window. When a tool returns a result that exceeds a configurable token threshold, the plugin stores each content block individually in an external storage backend and replaces it in the conversation with a truncated preview plus per-block references. Each offloaded result includes inline guidance telling the agent to use its available tools to selectively access the data it needs. diff --git a/src/content/docs/user-guide/concepts/plugins/index.mdx b/src/content/docs/user-guide/concepts/plugins/index.mdx index 79684e339..1453806a2 100644 --- a/src/content/docs/user-guide/concepts/plugins/index.mdx +++ b/src/content/docs/user-guide/concepts/plugins/index.mdx @@ -1,15 +1,6 @@ --- title: Plugins description: "Extend agent behavior with plugins. Add steering, guardrails, and custom capabilities that hook into the agent lifecycle." -sourceLinks: - - repo: sdk-python - path: src/strands/plugins/plugin.py - - repo: sdk-python - path: src/strands/plugins/registry.py - - repo: sdk-typescript - path: strands-ts/src/plugins/plugin.ts - - repo: sdk-typescript - path: strands-ts/src/plugins/registry.ts --- Plugins allow you to change the typical behavior of an agent. They enable you to introduce concepts like [Skills](https://agentskills.io/specification), [steering](./steering), or other behavioral modifications into the agentic loop. Plugins work by taking advantage of the low-level primitives exposed by the Agent class—`model`, `system_prompt`, `messages`, `tools`, and `hooks`—and executing logic to improve an agent's behavior. diff --git a/src/content/docs/user-guide/concepts/plugins/skills.mdx b/src/content/docs/user-guide/concepts/plugins/skills.mdx index e9e33e318..6c50bfeb0 100644 --- a/src/content/docs/user-guide/concepts/plugins/skills.mdx +++ b/src/content/docs/user-guide/concepts/plugins/skills.mdx @@ -4,11 +4,6 @@ sidebar: badge: text: New variant: tip -sourceLinks: - - repo: sdk-python - path: src/strands/vended_plugins/skills/agent_skills.py - - repo: sdk-python - path: src/strands/vended_plugins/skills/skill.py --- Skills give your agent on-demand access to specialized instructions without bloating the system prompt. Instead of front-loading every possible instruction into a single prompt, you define modular skill packages that the agent discovers and activates only when relevant. diff --git a/src/content/docs/user-guide/concepts/plugins/steering.mdx b/src/content/docs/user-guide/concepts/plugins/steering.mdx index 9b29ef101..318eef162 100644 --- a/src/content/docs/user-guide/concepts/plugins/steering.mdx +++ b/src/content/docs/user-guide/concepts/plugins/steering.mdx @@ -1,11 +1,6 @@ --- title: Steering languages: [python] -sourceLinks: - - repo: sdk-python - path: src/strands/vended_plugins/steering/core/handler.py - - repo: sdk-python - path: src/strands/vended_plugins/steering/handlers/llm/llm_handler.py --- diff --git a/src/content/docs/user-guide/concepts/streaming/async-iterators.mdx b/src/content/docs/user-guide/concepts/streaming/async-iterators.mdx index db6430f0a..c53d178c5 100644 --- a/src/content/docs/user-guide/concepts/streaming/async-iterators.mdx +++ b/src/content/docs/user-guide/concepts/streaming/async-iterators.mdx @@ -3,9 +3,6 @@ title: Async Iterators for Streaming sidebar: label: "Async Iterators" tags: [streaming] -sourceLinks: - - repo: sdk-python - path: src/strands/event_loop/streaming.py --- Async iterators provide asynchronous streaming of agent events, allowing you to process events as they occur in real-time. This approach is ideal for asynchronous frameworks where you need fine-grained control over async execution flow. diff --git a/src/content/docs/user-guide/concepts/streaming/callback-handlers.mdx b/src/content/docs/user-guide/concepts/streaming/callback-handlers.mdx index 3d42355b6..9562d6f73 100644 --- a/src/content/docs/user-guide/concepts/streaming/callback-handlers.mdx +++ b/src/content/docs/user-guide/concepts/streaming/callback-handlers.mdx @@ -1,9 +1,6 @@ --- title: Callback Handlers tags: [streaming] -sourceLinks: - - repo: sdk-python - path: src/strands/handlers/callback_handler.py --- :::note[Not supported in TypeScript] diff --git a/src/content/docs/user-guide/concepts/streaming/index.mdx b/src/content/docs/user-guide/concepts/streaming/index.mdx index af9f654d7..e3636f182 100644 --- a/src/content/docs/user-guide/concepts/streaming/index.mdx +++ b/src/content/docs/user-guide/concepts/streaming/index.mdx @@ -4,11 +4,6 @@ description: "Stream AI agent responses in real time. Handle partial results, to sidebar: label: "Overview" tags: [streaming] -sourceLinks: - - repo: sdk-python - path: src/strands/event_loop/streaming.py - - repo: sdk-typescript - path: strands-ts/src/models/streaming.ts --- Strands Agents SDK provides real-time streaming capabilities that allow you to monitor and process events as they occur during agent execution. This enables responsive user interfaces, real-time monitoring, and custom output formatting. diff --git a/src/content/docs/user-guide/concepts/tools/custom-tools.mdx b/src/content/docs/user-guide/concepts/tools/custom-tools.mdx index 5a7d73701..d5095ce1b 100644 --- a/src/content/docs/user-guide/concepts/tools/custom-tools.mdx +++ b/src/content/docs/user-guide/concepts/tools/custom-tools.mdx @@ -2,11 +2,6 @@ title: Creating Custom Tools description: "Turn any Python function into an AI agent tool. Define inputs with docstrings, and the agent calls your function autonomously." tags: [tools] -sourceLinks: - - repo: sdk-python - path: src/strands/tools/decorator.py - - repo: sdk-typescript - path: strands-ts/src/tools/function-tool.ts --- There are multiple approaches to defining custom tools in Strands, with differences between Python and TypeScript implementations. diff --git a/src/content/docs/user-guide/concepts/tools/executors.mdx b/src/content/docs/user-guide/concepts/tools/executors.mdx index fac133362..beb15c1b9 100644 --- a/src/content/docs/user-guide/concepts/tools/executors.mdx +++ b/src/content/docs/user-guide/concepts/tools/executors.mdx @@ -3,13 +3,6 @@ title: Tool Executors sidebar: label: "Executors" tags: [tools] -sourceLinks: - - repo: sdk-python - path: src/strands/tools/executors/_executor.py - - repo: sdk-python - path: src/strands/tools/executors/concurrent.py - - repo: sdk-python - path: src/strands/tools/executors/sequential.py --- Tool executors control whether tools from a single assistant turn run concurrently or sequentially. Both SDKs default to concurrent execution. diff --git a/src/content/docs/user-guide/concepts/tools/index.mdx b/src/content/docs/user-guide/concepts/tools/index.mdx index fa7bff231..c6721838e 100644 --- a/src/content/docs/user-guide/concepts/tools/index.mdx +++ b/src/content/docs/user-guide/concepts/tools/index.mdx @@ -4,11 +4,6 @@ description: "Give AI agents the ability to take real-world actions. Strands sup sidebar: label: "Overview" tags: [tools] -sourceLinks: - - repo: sdk-python - path: src/strands/tools/registry.py - - repo: sdk-typescript - path: strands-ts/src/registry/tool-registry.ts --- Tools are the primary mechanism for extending agent capabilities, enabling them to perform actions beyond simple text generation. Tools allow agents to interact with external systems, access data, and manipulate their environment. diff --git a/src/content/docs/user-guide/concepts/tools/mcp-tools.mdx b/src/content/docs/user-guide/concepts/tools/mcp-tools.mdx index 729598940..dbc2944b9 100644 --- a/src/content/docs/user-guide/concepts/tools/mcp-tools.mdx +++ b/src/content/docs/user-guide/concepts/tools/mcp-tools.mdx @@ -4,13 +4,6 @@ description: "Connect AI agents to any MCP server for tool access. Strands agent sidebar: label: "Model Context Protocol (MCP)" tags: [tools, mcp] -sourceLinks: - - repo: sdk-python - path: src/strands/tools/mcp/mcp_client.py - - repo: sdk-typescript - path: strands-ts/src/mcp.ts - - repo: sdk-typescript - path: strands-ts/src/tools/mcp-tool.ts --- The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is an open protocol that standardizes how applications provide context to Large Language Models. Strands Agents integrates with MCP to extend agent capabilities through external tools and services. diff --git a/src/content/docs/user-guide/concepts/tools/vended-tools.mdx b/src/content/docs/user-guide/concepts/tools/vended-tools.mdx index 1ce077164..f50cd23bb 100644 --- a/src/content/docs/user-guide/concepts/tools/vended-tools.mdx +++ b/src/content/docs/user-guide/concepts/tools/vended-tools.mdx @@ -5,15 +5,6 @@ sidebar: label: "Vended Tools" languages: [typescript] tags: [tools, typescript] -sourceLinks: - - repo: sdk-typescript - path: strands-ts/src/vended-tools/bash/bash.ts - - repo: sdk-typescript - path: strands-ts/src/vended-tools/file-editor/file-editor.ts - - repo: sdk-typescript - path: strands-ts/src/vended-tools/http-request/http-request.ts - - repo: sdk-typescript - path: strands-ts/src/vended-tools/notebook/notebook.ts --- Vended tools are pre-built tools included directly in the Strands SDK for common agent tasks like file operations, shell commands, HTTP requests, and persistent notes. diff --git a/src/content/docs/user-guide/observability-evaluation/logs.mdx b/src/content/docs/user-guide/observability-evaluation/logs.mdx index 04b5223be..e99ba4c90 100644 --- a/src/content/docs/user-guide/observability-evaluation/logs.mdx +++ b/src/content/docs/user-guide/observability-evaluation/logs.mdx @@ -3,9 +3,6 @@ title: Logging sidebar: label: "Logs" tags: [observability] -sourceLinks: - - repo: sdk-typescript - path: strands-ts/src/logging/logger.ts --- The Strands SDK provides logging infrastructure to give visibility into its operations. diff --git a/src/content/docs/user-guide/observability-evaluation/metrics.mdx b/src/content/docs/user-guide/observability-evaluation/metrics.mdx index 9abe0e6ab..3c38b2695 100644 --- a/src/content/docs/user-guide/observability-evaluation/metrics.mdx +++ b/src/content/docs/user-guide/observability-evaluation/metrics.mdx @@ -1,11 +1,6 @@ --- title: Metrics tags: [observability] -sourceLinks: - - repo: sdk-python - path: src/strands/telemetry/metrics.py - - repo: sdk-typescript - path: strands-ts/src/telemetry/meter.ts --- Metrics are essential for understanding agent performance, optimizing behavior, and monitoring resource usage. The Strands Agents SDK provides comprehensive metrics tracking capabilities that give you visibility into how your agents operate. diff --git a/src/content/docs/user-guide/observability-evaluation/observability.mdx b/src/content/docs/user-guide/observability-evaluation/observability.mdx index fadd643fb..b45cf940c 100644 --- a/src/content/docs/user-guide/observability-evaluation/observability.mdx +++ b/src/content/docs/user-guide/observability-evaluation/observability.mdx @@ -2,11 +2,6 @@ title: Observability description: "Monitor AI agents with OpenTelemetry traces, metrics, and logs. Debug agent behavior and measure performance in production." tags: [observability, production] -sourceLinks: - - repo: sdk-python - path: src/strands/telemetry/config.py - - repo: sdk-typescript - path: strands-ts/src/telemetry/config.ts --- In the Strands Agents SDK, observability refers to the ability to measure system behavior and performance. Observability is the combination of instrumentation, data collection, and analysis techniques that provide insights into an agent's behavior and performance. It enables Strands Agents developers to effectively build, debug and maintain agents to better serve their unique customer needs and reliably complete their tasks. This guide provides background on what type of data (or "Primitives") makes up observability as well as best practices for implementing agent observability with the Strands Agents SDK. diff --git a/src/content/docs/user-guide/observability-evaluation/traces.mdx b/src/content/docs/user-guide/observability-evaluation/traces.mdx index 00b80f77e..d098c5279 100644 --- a/src/content/docs/user-guide/observability-evaluation/traces.mdx +++ b/src/content/docs/user-guide/observability-evaluation/traces.mdx @@ -1,11 +1,6 @@ --- title: Traces tags: [observability] -sourceLinks: - - repo: sdk-python - path: src/strands/telemetry/tracer.py - - repo: sdk-typescript - path: strands-ts/src/telemetry/tracer.ts --- Tracing is a fundamental component of the Strands SDK's observability framework, providing detailed insights into your agent's execution. Using the OpenTelemetry standard, Strands traces capture the complete journey of a request through your agent, including LLM interactions, retrievers, tool usage, and event loop processing. diff --git a/src/content/docs/user-guide/safety-security/guardrails.mdx b/src/content/docs/user-guide/safety-security/guardrails.mdx index 8e70a4df4..191c3e12f 100644 --- a/src/content/docs/user-guide/safety-security/guardrails.mdx +++ b/src/content/docs/user-guide/safety-security/guardrails.mdx @@ -2,9 +2,6 @@ title: Guardrails description: "Add safety guardrails to AI agents. Control tool permissions, validate outputs, and enforce responsible AI policies in production." tags: [safety, guardrails, bedrock, production] -sourceLinks: - - repo: sdk-python - path: src/strands/models/bedrock.py --- Strands Agents SDK provides seamless integration with guardrails, enabling you to implement content filtering, topic blocking, PII protection, and other safety measures in your AI applications. diff --git a/src/util/related-docs.ts b/src/util/related-docs.ts index 78d761c11..07fb1c82a 100644 --- a/src/util/related-docs.ts +++ b/src/util/related-docs.ts @@ -40,15 +40,17 @@ export function relatedUserGuideFor( allDocs: readonly CollectionEntry<'docs'>[], ): RelatedLink[] { if (!isUserGuide(current)) return [] - const currentTags = current.data.tags + // `?? []` guards non-docs Starlight routes (blog, StarlightPage) that flow + // through the same components but whose synthetic entry.data lacks `tags`. + const currentTags = current.data.tags ?? [] if (currentTags.length === 0) return [] const tagSet = new Set(currentTags) return allDocs - .filter((d) => d.id !== current.id && isUserGuide(d) && d.data.tags.length > 0) + .filter((d) => d.id !== current.id && isUserGuide(d) && (d.data.tags ?? []).length > 0) .map((d) => ({ doc: d, - overlap: d.data.tags.reduce((n, t) => n + (tagSet.has(t) ? 1 : 0), 0), + overlap: (d.data.tags ?? []).reduce((n, t) => n + (tagSet.has(t) ? 1 : 0), 0), })) .filter((s) => s.overlap > 0) .sort((a, b) => b.overlap - a.overlap || a.doc.data.title.localeCompare(b.doc.data.title)) diff --git a/test/content-collection.test.ts b/test/content-collection.test.ts index 5cb891381..c347ae159 100644 --- a/test/content-collection.test.ts +++ b/test/content-collection.test.ts @@ -62,4 +62,32 @@ describe('Content Collections', () => { expect(invalidSlugs).toEqual([]) }) + + it('has unique titles across user-guide pages', async () => { + // Related-pages output and JSON-LD `headline` use `title` verbatim. Two + // user-guide pages with the same title produce ambiguous links that look + // like duplicates (e.g. a "Hooks" that could mean the agents or bidi one). + // Set `sidebar.label` if you want the sidebar to stay terse while the page + // title remains unambiguous out-of-context. + const docs = await getCollection('docs') + const userGuide = docs.filter((d) => d.id.startsWith('docs/user-guide/')) + + const titleMap = new Map() + for (const doc of userGuide) { + const slugs = titleMap.get(doc.data.title) ?? [] + slugs.push(doc.id) + titleMap.set(doc.data.title, slugs) + } + + const collisions = [...titleMap.entries()].filter(([, slugs]) => slugs.length > 1) + if (collisions.length > 0) { + console.log('\n=== Duplicate user-guide titles ===\n') + for (const [title, slugs] of collisions) { + console.log(`"${title}"`) + for (const s of slugs) console.log(` ${s}`) + } + } + + expect(collisions).toEqual([]) + }) }) From f8fea4df6bda3366f26a8171d16b61863488c414 Mon Sep 17 00:00:00 2001 From: notowen333 Date: Wed, 13 May 2026 22:12:39 -0400 Subject: [PATCH 3/5] feat: tag-driven Related Pages with specificity-weighted scoring MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replaces the earlier raw-overlap algorithm with a specificity-weighted Jaccard scorer plus a confidence floor for the human-facing surface. Algorithm (src/util/related-docs.ts): - Score is rarity-weighted Jaccard: each shared tag's contribution scales with its rarity in the corpus (1 - freq/N), so a shared `bedrock` (8/108) outweighs a shared `aws` (14/108). Self-correcting if a tag bloats over time — its weight automatically drops. - Headless surface (//index.md, /llms-full.txt, JSON-LD relatedLink): top 10, no floor. LLMs benefit from wider recall and self-filter. - Human surface ("See also" pill row): top 6 with score >= 0.4 floor. Empty strip is strictly better than a misleading one; the floor catches the spurious 1-broad-tag matches that earlier audits kept finding by hand. - Specificity table memoized on the input array (cheap WeakMap hit). Vocabulary (src/config/tags.yml): - 32-tag registry organized by axis (topics / capabilities / lifecycle). - Inline rule and authoring checklist at the head of the YAML — "tag = teaches, not mentions" with concrete failure-pattern examples drawn from earlier audit rounds. - Build-time Zod validation (src/config/tags.ts); unknown tags fail. Content: - 108 of 123 user-guide pages tagged; 15 deliberately untagged (umbrella/policy pages and known structural cases). - Two audit passes done; broad-tag misuses (production, aws on session-management, tool-execution on model providers, etc.) stripped. Surface design (src/components/RelatedPagesInline.astro): - Outlined pills wrapping to fit content. Small "Related" caption above. - Mounted in MarkdownContent.astro above Starlight's Prev/Next pagination. - No surface-aware filtering — algorithm is unaware of Pagination. Lint: - Title-uniqueness check in test/content-collection.test.ts catches cross-section title collisions (the kind that produce ambiguous "Hooks" pills). 311 tests pass; 14 cover the algorithm directly. --- src/components/RelatedPagesInline.astro | 81 +++++---- src/components/overrides/Head.astro | 11 +- src/config/tags.yml | 57 ++++-- src/content/docs/user-guide/build-with-ai.mdx | 1 + .../user-guide/concepts/agents/agent-loop.mdx | 1 + .../agents/conversation-management.mdx | 2 +- .../docs/user-guide/concepts/agents/hooks.mdx | 2 +- .../user-guide/concepts/agents/prompts.mdx | 1 + .../concepts/agents/retry-strategies.mdx | 2 +- .../concepts/agents/session-management.mdx | 2 +- .../docs/user-guide/concepts/agents/state.mdx | 2 +- .../bidirectional-streaming/agent.mdx | 2 +- .../bidirectional-streaming/events.mdx | 2 +- .../bidirectional-streaming/hooks.mdx | 2 +- .../bidirectional-streaming/interruption.mdx | 2 +- .../concepts/bidirectional-streaming/io.mdx | 2 +- .../models/gemini_live.mdx | 2 +- .../models/nova_sonic.mdx | 2 +- .../models/openai_realtime.mdx | 2 +- .../bidirectional-streaming/quickstart.mdx | 1 + .../session-management.mdx | 2 +- .../concepts/experimental/agent-config.mdx | 1 + .../docs/user-guide/concepts/interrupts.mdx | 1 + .../model-providers/amazon-bedrock.mdx | 2 +- .../concepts/model-providers/amazon-nova.mdx | 2 +- .../concepts/model-providers/anthropic.mdx | 1 + .../model-providers/custom_model_provider.mdx | 1 + .../concepts/model-providers/google.mdx | 1 + .../concepts/model-providers/litellm.mdx | 1 + .../concepts/model-providers/llamaapi.mdx | 1 + .../concepts/model-providers/llamacpp.mdx | 1 + .../concepts/model-providers/ollama.mdx | 1 + .../model-providers/openai-responses.mdx | 1 + .../concepts/model-providers/openai.mdx | 1 + .../concepts/model-providers/sagemaker.mdx | 1 - .../concepts/model-providers/vercel.mdx | 1 + .../concepts/model-providers/writer.mdx | 1 + .../concepts/multi-agent/agents-as-tools.mdx | 2 +- .../concepts/plugins/context-offloader.mdx | 1 + .../user-guide/concepts/plugins/index.mdx | 1 + .../user-guide/concepts/plugins/skills.mdx | 1 + .../user-guide/concepts/plugins/steering.mdx | 1 + .../tools/community-tools-package.mdx | 1 + .../concepts/tools/custom-tools.mdx | 2 +- .../user-guide/concepts/tools/executors.mdx | 2 +- .../docs/user-guide/concepts/tools/index.mdx | 2 +- .../user-guide/concepts/tools/mcp-tools.mdx | 2 +- .../concepts/tools/vended-tools.mdx | 2 +- .../deploy/deploy_to_amazon_ec2.mdx | 2 +- .../deploy/deploy_to_amazon_eks.mdx | 2 +- .../deploy/deploy_to_aws_apprunner.mdx | 2 +- .../deploy/deploy_to_aws_fargate.mdx | 2 +- .../deploy/deploy_to_aws_lambda.mdx | 2 +- .../deploy_to_bedrock_agentcore/index.mdx | 2 +- .../deploy_to_bedrock_agentcore/python.mdx | 2 +- .../typescript.mdx | 2 +- .../deploy/deploy_to_docker/index.mdx | 2 +- .../deploy/deploy_to_docker/python.mdx | 2 +- .../deploy/deploy_to_docker/typescript.mdx | 2 +- .../deploy/deploy_to_kubernetes.mdx | 2 +- .../user-guide/deploy/deploy_to_terraform.mdx | 2 +- .../deploy/operating-agents-in-production.mdx | 2 +- .../evals-sdk/detectors/diagnosis.mdx | 1 + .../evals-sdk/detectors/failure_detection.mdx | 1 + .../user-guide/evals-sdk/detectors/index.mdx | 1 + .../detectors/root_cause_analysis.mdx | 1 + .../evaluators/coherence_evaluator.mdx | 1 + .../evaluators/conciseness_evaluator.mdx | 1 + .../evaluators/deterministic_evaluators.mdx | 1 + .../goal_success_rate_evaluator.mdx | 1 + .../evaluators/harmfulness_evaluator.mdx | 1 + .../evaluators/helpfulness_evaluator.mdx | 1 + .../instruction_following_evaluator.mdx | 1 + .../evaluators/interactions_evaluator.mdx | 1 + .../multimodal_correctness_evaluator.mdx | 1 + .../multimodal_faithfulness_evaluator.mdx | 1 + ...imodal_instruction_following_evaluator.mdx | 1 + .../multimodal_output_evaluator.mdx | 1 + .../multimodal_overall_quality_evaluator.mdx | 1 + .../evals-sdk/evaluators/output_evaluator.mdx | 1 + .../evaluators/refusal_evaluator.mdx | 1 + .../evaluators/stereotyping_evaluator.mdx | 1 + .../evaluators/tool_parameter_evaluator.mdx | 1 + .../evaluators/tool_selection_evaluator.mdx | 1 + .../evaluators/trajectory_evaluator.mdx | 1 + .../evals-sdk/experiment_generator.mdx | 1 + .../how-to/agentcore_evaluation_dashboard.mdx | 1 + .../user-guide/evals-sdk/how-to/eval_task.mdx | 1 + .../evals-sdk/how-to/result_caching.mdx | 1 + .../evals-sdk/how-to/serialization.mdx | 1 + .../evals-sdk/how-to/trace_providers.mdx | 1 + .../docs/user-guide/evals-sdk/quickstart.mdx | 1 + .../user-guide/evals-sdk/simulators/index.mdx | 1 + .../evals-sdk/simulators/tool_simulation.mdx | 1 + .../evals-sdk/simulators/user_simulation.mdx | 1 + .../observability-evaluation/evaluation.mdx | 2 +- .../observability-evaluation/logs.mdx | 2 +- .../observability.mdx | 2 +- .../docs/user-guide/quickstart/python.mdx | 2 +- .../docs/user-guide/quickstart/typescript.mdx | 2 +- .../user-guide/safety-security/guardrails.mdx | 2 +- .../safety-security/pii-redaction.mdx | 2 +- .../safety-security/prompt-engineering.mdx | 2 +- src/util/related-docs.ts | 170 +++++++++++++++--- test/related-docs.test.ts | 68 ++++++- 105 files changed, 405 insertions(+), 126 deletions(-) diff --git a/src/components/RelatedPagesInline.astro b/src/components/RelatedPagesInline.astro index 7bf1d6d4d..759bcf4f5 100644 --- a/src/components/RelatedPagesInline.astro +++ b/src/components/RelatedPagesInline.astro @@ -1,34 +1,33 @@ --- /** - * Quiet "See also" list rendered at the end of the article body, above - * Starlight's Prev/Next pagination. Reads as a caption, not navigation — - * complements the linear Prev/Next with lateral topical jumps. - * - * Display cap (4) differs from the headless cap (10) in related-docs.ts: - * humans can only scan a handful of links before it becomes noise. + * "See also" pill row at the end of the article body, above Starlight's + * Prev/Next pagination. Renders as outlined pills that wrap to fit content. + * No box, no border, no fill on the container — only the pills themselves + * have outlines, so this doesn't compete with the Prev/Next cards below. */ import { getCollection } from 'astro:content' -import { relatedUserGuideFor } from '../util/related-docs' +import { humanRelatedUserGuideFor } from '../util/related-docs' import { pathWithBase } from '../util/links' -const MAX_DISPLAY = 4 - const { starlightRoute } = Astro.locals const entry = starlightRoute.entry + // Non-docs routes (blog pages, StarlightPage splashes) flow through // MarkdownContent too — short-circuit before calling into the util. const related = entry.collection === 'docs' - ? relatedUserGuideFor(entry, await getCollection('docs')).slice(0, MAX_DISPLAY) + ? humanRelatedUserGuideFor(entry, await getCollection('docs')) : [] --- {related.length > 0 && ( -