diff --git a/src/components/overrides/Head.astro b/src/components/overrides/Head.astro index 7f9ce3f62..30320c997 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,46 @@ 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. +// +// Schema reference for the fields used below: +// TechArticle: https://schema.org/TechArticle +// keywords: https://schema.org/keywords +// relatedLink: https://schema.org/relatedLink +// isBasedOn: https://schema.org/isBasedOn +// SoftwareSourceCode: https://schema.org/SoftwareSourceCode +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 +109,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..3f0a66f91 --- /dev/null +++ b/src/config/tags.yml @@ -0,0 +1,66 @@ +# Allowed tag vocabulary for user-guide pages. Drives the headless +# "Related pages" block (in //index.md, /llms-full.txt, and JSON-LD +# `relatedLink`). Not surfaced on the rendered HTML — agent-facing only. +# Validated by Zod (src/content.config.ts) — unknown tags fail the build. +# +# THE RULE: a tag means "this page TEACHES the named thing." Not "mentions +# it" or "has a section labeled with it." If a reader landed on the page +# looking to learn the tagged topic, they should leave understanding it. +# +# Common traps to avoid: +# - Section heading matches tag name. A model provider with a "Streaming" +# section is not teaching streaming — the section says "yes, this +# provider supports it." Don't tag the provider page with `streaming`. +# - Page mentions X in passing. References to other pages don't warrant +# tags. Tag for what the page IS, not what it links to. +# - Lifecycle bloat. Words like "production" feel applicable to anything +# serious. We removed `production` for this reason — it labeled a +# property, not a topic. +# - Over-tagging. 6+ tags dilutes the page's coordinates and makes it +# match too broadly. Aim for 2-4 tags that each name a primary topic. +# +# Authoring checklist: +# 1. Does this page TEACH the tag? If not, leave it off. +# 2. Would this page be a useful related-link for every other tag-mate? +# 3. Is the tag a primary topic, or just mentioned? Tag only primaries. +# 4. When in doubt, leave the tag off. Empty related-links beat misleading. +# +# Adding a new tag = PR editing this file. Every tag must apply to ≥2 +# pages and meaningfully bridge across sidebar sections. + +# Topics / domains — specific products, protocols, data types +- agentcore +- aws +- bedrock +- mcp +- pii +- vision + +# Capabilities — what the page teaches the reader to do +- bidi-streaming +- caching +- conversation-management +- error-handling +- event-loop +- failure-diagnosis +- hooks +- local-models +- multi-agent +- multimodal-evaluation +- prompt-authoring +- session-management +- simulation +- snapshots +- state +- streaming +- structured-output +- token-management +- tool-authoring +- tool-evaluation +- tool-execution + +# Lifecycle / practice — where in the dev lifecycle this sits +- deployment +- observability +- quickstart +- safety 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/build-with-ai.mdx b/src/content/docs/user-guide/build-with-ai.mdx index 3f2a85230..befaab13c 100644 --- a/src/content/docs/user-guide/build-with-ai.mdx +++ b/src/content/docs/user-guide/build-with-ai.mdx @@ -1,5 +1,6 @@ --- title: Build with AI +tags: [mcp, tool-authoring] description: Use AI coding assistants to build Strands Agents projects with up-to-date documentation context. redirectFrom: - docs/llms 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..ff28c8abc 100644 --- a/src/content/docs/user-guide/concepts/agents/agent-loop.mdx +++ b/src/content/docs/user-guide/concepts/agents/agent-loop.mdx @@ -1,5 +1,6 @@ --- title: Agent Loop +tags: [event-loop, tool-execution, hooks] description: "How Strands agents reason, plan, and act. Understand the model-driven loop that orchestrates tool use, reflection, and goal completion." --- 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..2cb285603 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,6 @@ --- title: Conversation Management +tags: [conversation-management, session-management, token-management] --- 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..0c4700a26 100644 --- a/src/content/docs/user-guide/concepts/agents/hooks.mdx +++ b/src/content/docs/user-guide/concepts/agents/hooks.mdx @@ -1,6 +1,7 @@ --- 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, event-loop, tool-execution] --- diff --git a/src/content/docs/user-guide/concepts/agents/prompts.mdx b/src/content/docs/user-guide/concepts/agents/prompts.mdx index aff56a6b5..e2843c71c 100644 --- a/src/content/docs/user-guide/concepts/agents/prompts.mdx +++ b/src/content/docs/user-guide/concepts/agents/prompts.mdx @@ -1,5 +1,6 @@ --- title: Prompts +tags: [safety, conversation-management, prompt-authoring] --- 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..0267b2d36 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,6 @@ --- title: Retry Strategies +tags: [event-loop, error-handling] --- 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..3163f17ab 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,7 @@ --- 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, snapshots, state] --- 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..f56c931c1 100644 --- a/src/content/docs/user-guide/concepts/agents/state.mdx +++ b/src/content/docs/user-guide/concepts/agents/state.mdx @@ -2,6 +2,7 @@ title: State Management sidebar: label: "State" +tags: [state, snapshots, session-management] --- 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..184dff90b 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,7 @@ --- 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] --- ## 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..3dbf95a28 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,7 @@ --- title: BidiAgent experimental: true +tags: [bidi-streaming] --- 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..96ba5ee1a 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,7 @@ --- title: Events experimental: true +tags: [bidi-streaming] --- 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..90006e3db 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,9 @@ --- -title: Hooks +title: Bidirectional Streaming Hooks +sidebar: + label: "Hooks" experimental: true +tags: [bidi-streaming, hooks] --- 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..40c119a87 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,7 @@ --- title: Interruptions experimental: true +tags: [bidi-streaming] --- 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..30a5ce51d 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,7 @@ title: I/O Channels experimental: true sidebar: label: "IO" +tags: [bidi-streaming] --- 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..467697da6 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,7 @@ --- title: Gemini Live experimental: true +tags: [bidi-streaming] --- 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..f7c50b05e 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,7 @@ --- title: Nova Sonic experimental: true +tags: [bidi-streaming, aws, bedrock] --- 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..96b901102 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,7 @@ --- title: OpenAI Realtime experimental: true +tags: [bidi-streaming] --- diff --git a/src/content/docs/user-guide/concepts/bidirectional-streaming/quickstart.mdx b/src/content/docs/user-guide/concepts/bidirectional-streaming/quickstart.mdx index e18e485e1..b5869f60d 100644 --- a/src/content/docs/user-guide/concepts/bidirectional-streaming/quickstart.mdx +++ b/src/content/docs/user-guide/concepts/bidirectional-streaming/quickstart.mdx @@ -1,5 +1,6 @@ --- title: Quickstart +tags: [bidi-streaming, quickstart] description: "Build voice-enabled AI agents with real-time audio streaming. Works with Amazon Nova Sonic, Gemini Live, and OpenAI Realtime." experimental: true --- 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..a212410ce 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,9 @@ --- -title: Session Management +title: Bidirectional Streaming Session Management +sidebar: + label: "Session Management" experimental: true +tags: [bidi-streaming, session-management, snapshots] --- diff --git a/src/content/docs/user-guide/concepts/experimental/agent-config.mdx b/src/content/docs/user-guide/concepts/experimental/agent-config.mdx index 56337206a..6aa61857f 100644 --- a/src/content/docs/user-guide/concepts/experimental/agent-config.mdx +++ b/src/content/docs/user-guide/concepts/experimental/agent-config.mdx @@ -1,5 +1,6 @@ --- title: Agent Configuration +tags: [tool-authoring, bedrock, prompt-authoring] experimental: true sidebar: label: "AgentConfig" diff --git a/src/content/docs/user-guide/concepts/interrupts.mdx b/src/content/docs/user-guide/concepts/interrupts.mdx index 0ffd16005..890e34fa2 100644 --- a/src/content/docs/user-guide/concepts/interrupts.mdx +++ b/src/content/docs/user-guide/concepts/interrupts.mdx @@ -1,5 +1,6 @@ --- title: Interrupts +tags: [event-loop, hooks, tool-execution, error-handling] description: "Pause AI agents mid-execution for human approval, input, or review. Build human-in-the-loop workflows with interrupt and resume patterns." --- 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..a8ec287cb 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,7 @@ --- title: Amazon Bedrock integrationType: model-provider +tags: [bedrock, aws, vision, safety, caching] --- 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..f039ae37c 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,7 @@ title: Amazon Nova languages: Python integrationType: model-provider +tags: [bedrock, aws, vision] --- [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..0c820e7cc 100644 --- a/src/content/docs/user-guide/concepts/model-providers/anthropic.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/anthropic.mdx @@ -1,5 +1,6 @@ --- title: Anthropic +tags: [structured-output, caching] integrationType: model-provider --- 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..fe29c1e45 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 @@ -1,5 +1,6 @@ --- title: Creating a Custom Model Provider +tags: [tool-execution] sidebar: label: "Custom Providers" integrationType: model-provider 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..385f8f65e 100644 --- a/src/content/docs/user-guide/concepts/model-providers/google.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/google.mdx @@ -1,5 +1,6 @@ --- title: Google +tags: [vision] integrationType: model-provider redirectFrom: - docs/user-guide/concepts/model-providers/gemini 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..480378dfe 100644 --- a/src/content/docs/user-guide/concepts/model-providers/litellm.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/litellm.mdx @@ -1,5 +1,6 @@ --- title: LiteLLM +tags: [structured-output] languages: Python integrationType: model-provider --- 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..a131cd07d 100644 --- a/src/content/docs/user-guide/concepts/model-providers/llamaapi.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/llamaapi.mdx @@ -1,5 +1,6 @@ --- title: Llama API +tags: [local-models] languages: Python sidebar: label: "LlamaAPI" 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..1e8f7eb79 100644 --- a/src/content/docs/user-guide/concepts/model-providers/llamacpp.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/llamacpp.mdx @@ -1,5 +1,6 @@ --- title: llama.cpp +tags: [local-models] languages: Python integrationType: model-provider --- 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..bbdaaa83d 100644 --- a/src/content/docs/user-guide/concepts/model-providers/ollama.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/ollama.mdx @@ -1,5 +1,6 @@ --- title: Ollama +tags: [local-models] languages: Python integrationType: model-provider --- 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..4fefbeedb 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,5 +1,6 @@ --- title: OpenAI Responses API +tags: [mcp, state] integrationType: model-provider --- 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..3b6c9feed 100644 --- a/src/content/docs/user-guide/concepts/model-providers/openai.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/openai.mdx @@ -1,5 +1,6 @@ --- title: OpenAI +tags: [vision, structured-output] integrationType: model-provider --- 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..a6c38f58a 100644 --- a/src/content/docs/user-guide/concepts/model-providers/vercel.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/vercel.mdx @@ -1,5 +1,6 @@ --- title: Vercel +tags: [vision] languages: TypeScript integrationType: 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..190696922 100644 --- a/src/content/docs/user-guide/concepts/model-providers/writer.mdx +++ b/src/content/docs/user-guide/concepts/model-providers/writer.mdx @@ -1,5 +1,6 @@ --- title: Writer +tags: [vision, structured-output] languages: Python integrationType: model-provider --- 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..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 @@ -2,6 +2,7 @@ title: Agent-to-Agent (A2A) Protocol sidebar: label: "Agent2Agent (A2A)" +tags: [multi-agent] --- 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..cbc59e91a 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,7 @@ title: Agents as Tools with Strands Agents SDK sidebar: label: "Agents as Tools" +tags: [multi-agent, tool-authoring, tool-execution] --- ## 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..e528d6955 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,7 @@ title: Graph Multi-Agent Pattern sidebar: label: "Graph" +tags: [multi-agent] --- 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..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 @@ -1,6 +1,7 @@ --- 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] --- 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..5feffc0b8 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,7 @@ title: Swarm Multi-Agent Pattern sidebar: label: "Swarm" +tags: [multi-agent] --- 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..553b68eba 100644 --- a/src/content/docs/user-guide/concepts/plugins/context-offloader.mdx +++ b/src/content/docs/user-guide/concepts/plugins/context-offloader.mdx @@ -1,5 +1,6 @@ --- title: Context Offloader +tags: [conversation-management, hooks, token-management] sidebar: badge: text: New diff --git a/src/content/docs/user-guide/concepts/plugins/index.mdx b/src/content/docs/user-guide/concepts/plugins/index.mdx index 1453806a2..d1f1c7bc0 100644 --- a/src/content/docs/user-guide/concepts/plugins/index.mdx +++ b/src/content/docs/user-guide/concepts/plugins/index.mdx @@ -1,5 +1,6 @@ --- title: Plugins +tags: [hooks, event-loop] description: "Extend agent behavior with plugins. Add steering, guardrails, and custom capabilities that hook into the agent lifecycle." --- diff --git a/src/content/docs/user-guide/concepts/plugins/skills.mdx b/src/content/docs/user-guide/concepts/plugins/skills.mdx index 6c50bfeb0..5e8a6e5a5 100644 --- a/src/content/docs/user-guide/concepts/plugins/skills.mdx +++ b/src/content/docs/user-guide/concepts/plugins/skills.mdx @@ -1,5 +1,6 @@ --- title: Skills +tags: [token-management, prompt-authoring] sidebar: badge: text: New diff --git a/src/content/docs/user-guide/concepts/plugins/steering.mdx b/src/content/docs/user-guide/concepts/plugins/steering.mdx index 318eef162..a00c691ae 100644 --- a/src/content/docs/user-guide/concepts/plugins/steering.mdx +++ b/src/content/docs/user-guide/concepts/plugins/steering.mdx @@ -1,5 +1,6 @@ --- title: Steering +tags: [hooks, conversation-management, prompt-authoring] languages: [python] --- 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..c53d178c5 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,7 @@ title: Async Iterators for Streaming sidebar: label: "Async Iterators" +tags: [streaming] --- 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..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,5 +1,6 @@ --- title: Callback Handlers +tags: [streaming] --- :::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..e3636f182 100644 --- a/src/content/docs/user-guide/concepts/streaming/index.mdx +++ b/src/content/docs/user-guide/concepts/streaming/index.mdx @@ -3,6 +3,7 @@ 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] --- 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/community-tools-package.mdx b/src/content/docs/user-guide/concepts/tools/community-tools-package.mdx index 8af6b2c4f..c4df85d01 100644 --- a/src/content/docs/user-guide/concepts/tools/community-tools-package.mdx +++ b/src/content/docs/user-guide/concepts/tools/community-tools-package.mdx @@ -1,5 +1,6 @@ --- title: Community Built Tools +tags: [tool-authoring] sidebar: label: "Community Tools Package" --- 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..1bbe6d91c 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,7 @@ --- 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: [tool-authoring] --- 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..02d6fc206 100644 --- a/src/content/docs/user-guide/concepts/tools/executors.mdx +++ b/src/content/docs/user-guide/concepts/tools/executors.mdx @@ -2,6 +2,7 @@ title: Tool Executors sidebar: label: "Executors" +tags: [tool-execution, event-loop] --- 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..8fef0b3b0 100644 --- a/src/content/docs/user-guide/concepts/tools/index.mdx +++ b/src/content/docs/user-guide/concepts/tools/index.mdx @@ -3,6 +3,7 @@ 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: [tool-authoring, mcp] --- 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..324ee24ab 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,7 @@ 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: [tool-authoring, mcp] --- 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..fd2e90346 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,7 @@ description: "Pre-built tools included in the TypeScript SDK for common agent ta sidebar: label: "Vended Tools" languages: [typescript] +tags: [tool-authoring] --- 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..942ebd3d9 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] --- 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..d51e504b6 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] --- 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..edc4f589e 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] --- 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..6b31bf0b5 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] --- 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..f29a62a12 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] --- 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..276162646 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] --- 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..924e03652 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] --- 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..88d8c1207 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] --- 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..123f1e0ee 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] --- 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..0feac072a 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] --- 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..25b908730 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] --- 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..8fa6bc419 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] --- 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..5bca43bc3 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] --- 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..5255c5e84 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: [observability, deployment, error-handling] --- 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/evals-sdk/detectors/diagnosis.mdx b/src/content/docs/user-guide/evals-sdk/detectors/diagnosis.mdx index b98f593e8..65aacc08d 100644 --- a/src/content/docs/user-guide/evals-sdk/detectors/diagnosis.mdx +++ b/src/content/docs/user-guide/evals-sdk/detectors/diagnosis.mdx @@ -1,5 +1,6 @@ --- title: Session Diagnosis +tags: [failure-diagnosis, observability, error-handling] sidebar: label: "Session Diagnosis" --- diff --git a/src/content/docs/user-guide/evals-sdk/detectors/failure_detection.mdx b/src/content/docs/user-guide/evals-sdk/detectors/failure_detection.mdx index 6ccde79be..2cffa1075 100644 --- a/src/content/docs/user-guide/evals-sdk/detectors/failure_detection.mdx +++ b/src/content/docs/user-guide/evals-sdk/detectors/failure_detection.mdx @@ -1,5 +1,6 @@ --- title: Failure Detection +tags: [failure-diagnosis, error-handling] sidebar: label: "Failure Detection" --- diff --git a/src/content/docs/user-guide/evals-sdk/detectors/index.mdx b/src/content/docs/user-guide/evals-sdk/detectors/index.mdx index 84cb4a8df..93ee8b5db 100644 --- a/src/content/docs/user-guide/evals-sdk/detectors/index.mdx +++ b/src/content/docs/user-guide/evals-sdk/detectors/index.mdx @@ -1,5 +1,6 @@ --- title: Detectors +tags: [failure-diagnosis, error-handling] sidebar: label: "Overview" --- diff --git a/src/content/docs/user-guide/evals-sdk/detectors/root_cause_analysis.mdx b/src/content/docs/user-guide/evals-sdk/detectors/root_cause_analysis.mdx index 3d0a7bcfc..b8f0e1fb6 100644 --- a/src/content/docs/user-guide/evals-sdk/detectors/root_cause_analysis.mdx +++ b/src/content/docs/user-guide/evals-sdk/detectors/root_cause_analysis.mdx @@ -1,5 +1,6 @@ --- title: Root Cause Analysis +tags: [failure-diagnosis, observability, error-handling] sidebar: label: "Root Cause Analysis" --- diff --git a/src/content/docs/user-guide/evals-sdk/evaluators/coherence_evaluator.mdx b/src/content/docs/user-guide/evals-sdk/evaluators/coherence_evaluator.mdx index e9933a368..108293fac 100644 --- a/src/content/docs/user-guide/evals-sdk/evaluators/coherence_evaluator.mdx +++ b/src/content/docs/user-guide/evals-sdk/evaluators/coherence_evaluator.mdx @@ -1,5 +1,6 @@ --- title: Coherence Evaluator +tags: [conversation-management] sidebar: label: "Coherence" --- diff --git a/src/content/docs/user-guide/evals-sdk/evaluators/conciseness_evaluator.mdx b/src/content/docs/user-guide/evals-sdk/evaluators/conciseness_evaluator.mdx index a701fc210..f2d544d52 100644 --- a/src/content/docs/user-guide/evals-sdk/evaluators/conciseness_evaluator.mdx +++ b/src/content/docs/user-guide/evals-sdk/evaluators/conciseness_evaluator.mdx @@ -1,5 +1,6 @@ --- title: Conciseness Evaluator +tags: [conversation-management] sidebar: label: "Conciseness" --- diff --git a/src/content/docs/user-guide/evals-sdk/evaluators/deterministic_evaluators.mdx b/src/content/docs/user-guide/evals-sdk/evaluators/deterministic_evaluators.mdx index cfe7f15a5..fc9fd5ca2 100644 --- a/src/content/docs/user-guide/evals-sdk/evaluators/deterministic_evaluators.mdx +++ b/src/content/docs/user-guide/evals-sdk/evaluators/deterministic_evaluators.mdx @@ -1,5 +1,6 @@ --- title: Deterministic Evaluators +tags: [tool-evaluation] sidebar: label: "Deterministic" --- diff --git a/src/content/docs/user-guide/evals-sdk/evaluators/goal_success_rate_evaluator.mdx b/src/content/docs/user-guide/evals-sdk/evaluators/goal_success_rate_evaluator.mdx index f149554c9..a1242bd2c 100644 --- a/src/content/docs/user-guide/evals-sdk/evaluators/goal_success_rate_evaluator.mdx +++ b/src/content/docs/user-guide/evals-sdk/evaluators/goal_success_rate_evaluator.mdx @@ -1,5 +1,6 @@ --- title: Goal Success Rate Evaluator +tags: [conversation-management] sidebar: label: "Goal Success Rate" --- diff --git a/src/content/docs/user-guide/evals-sdk/evaluators/harmfulness_evaluator.mdx b/src/content/docs/user-guide/evals-sdk/evaluators/harmfulness_evaluator.mdx index 09d1d2a5f..34b2ba1bf 100644 --- a/src/content/docs/user-guide/evals-sdk/evaluators/harmfulness_evaluator.mdx +++ b/src/content/docs/user-guide/evals-sdk/evaluators/harmfulness_evaluator.mdx @@ -1,5 +1,6 @@ --- title: Harmfulness Evaluator +tags: [safety] sidebar: label: "Harmfulness" --- diff --git a/src/content/docs/user-guide/evals-sdk/evaluators/helpfulness_evaluator.mdx b/src/content/docs/user-guide/evals-sdk/evaluators/helpfulness_evaluator.mdx index 06cd18d08..eb977f58c 100644 --- a/src/content/docs/user-guide/evals-sdk/evaluators/helpfulness_evaluator.mdx +++ b/src/content/docs/user-guide/evals-sdk/evaluators/helpfulness_evaluator.mdx @@ -1,5 +1,6 @@ --- title: Helpfulness Evaluator +tags: [conversation-management] sidebar: label: "Helpfulness" --- diff --git a/src/content/docs/user-guide/evals-sdk/evaluators/instruction_following_evaluator.mdx b/src/content/docs/user-guide/evals-sdk/evaluators/instruction_following_evaluator.mdx index 7b1e0a19f..6125f207f 100644 --- a/src/content/docs/user-guide/evals-sdk/evaluators/instruction_following_evaluator.mdx +++ b/src/content/docs/user-guide/evals-sdk/evaluators/instruction_following_evaluator.mdx @@ -1,5 +1,6 @@ --- title: Instruction Following Evaluator +tags: [safety, prompt-authoring] sidebar: label: "Instruction Following" --- diff --git a/src/content/docs/user-guide/evals-sdk/evaluators/interactions_evaluator.mdx b/src/content/docs/user-guide/evals-sdk/evaluators/interactions_evaluator.mdx index 50a2c2420..ec792565a 100644 --- a/src/content/docs/user-guide/evals-sdk/evaluators/interactions_evaluator.mdx +++ b/src/content/docs/user-guide/evals-sdk/evaluators/interactions_evaluator.mdx @@ -1,5 +1,6 @@ --- title: Interactions Evaluator +tags: [conversation-management] sidebar: label: "Interactions" --- diff --git a/src/content/docs/user-guide/evals-sdk/evaluators/multimodal_correctness_evaluator.mdx b/src/content/docs/user-guide/evals-sdk/evaluators/multimodal_correctness_evaluator.mdx index d59d048fd..c9f798a07 100644 --- a/src/content/docs/user-guide/evals-sdk/evaluators/multimodal_correctness_evaluator.mdx +++ b/src/content/docs/user-guide/evals-sdk/evaluators/multimodal_correctness_evaluator.mdx @@ -1,5 +1,6 @@ --- title: Multimodal Correctness Evaluator +tags: [multimodal-evaluation, vision] sidebar: label: "Multimodal Correctness" --- diff --git a/src/content/docs/user-guide/evals-sdk/evaluators/multimodal_faithfulness_evaluator.mdx b/src/content/docs/user-guide/evals-sdk/evaluators/multimodal_faithfulness_evaluator.mdx index c5d62103a..a540f8aa5 100644 --- a/src/content/docs/user-guide/evals-sdk/evaluators/multimodal_faithfulness_evaluator.mdx +++ b/src/content/docs/user-guide/evals-sdk/evaluators/multimodal_faithfulness_evaluator.mdx @@ -1,5 +1,6 @@ --- title: Multimodal Faithfulness Evaluator +tags: [multimodal-evaluation, vision] sidebar: label: "Multimodal Faithfulness" --- diff --git a/src/content/docs/user-guide/evals-sdk/evaluators/multimodal_instruction_following_evaluator.mdx b/src/content/docs/user-guide/evals-sdk/evaluators/multimodal_instruction_following_evaluator.mdx index d1a72425c..04f4f89c7 100644 --- a/src/content/docs/user-guide/evals-sdk/evaluators/multimodal_instruction_following_evaluator.mdx +++ b/src/content/docs/user-guide/evals-sdk/evaluators/multimodal_instruction_following_evaluator.mdx @@ -1,5 +1,6 @@ --- title: Multimodal Instruction Following Evaluator +tags: [multimodal-evaluation, vision] sidebar: label: "Multimodal Instruction Following" --- diff --git a/src/content/docs/user-guide/evals-sdk/evaluators/multimodal_output_evaluator.mdx b/src/content/docs/user-guide/evals-sdk/evaluators/multimodal_output_evaluator.mdx index 8034ea874..bad524044 100644 --- a/src/content/docs/user-guide/evals-sdk/evaluators/multimodal_output_evaluator.mdx +++ b/src/content/docs/user-guide/evals-sdk/evaluators/multimodal_output_evaluator.mdx @@ -1,5 +1,6 @@ --- title: Multimodal Output Evaluator +tags: [multimodal-evaluation, vision] sidebar: label: "Multimodal Output" --- diff --git a/src/content/docs/user-guide/evals-sdk/evaluators/multimodal_overall_quality_evaluator.mdx b/src/content/docs/user-guide/evals-sdk/evaluators/multimodal_overall_quality_evaluator.mdx index 985aa86d3..81fb314b6 100644 --- a/src/content/docs/user-guide/evals-sdk/evaluators/multimodal_overall_quality_evaluator.mdx +++ b/src/content/docs/user-guide/evals-sdk/evaluators/multimodal_overall_quality_evaluator.mdx @@ -1,5 +1,6 @@ --- title: Multimodal Overall Quality Evaluator +tags: [multimodal-evaluation, vision] sidebar: label: "Multimodal Overall Quality" --- diff --git a/src/content/docs/user-guide/evals-sdk/evaluators/output_evaluator.mdx b/src/content/docs/user-guide/evals-sdk/evaluators/output_evaluator.mdx index 23b49515b..2033f9a1f 100644 --- a/src/content/docs/user-guide/evals-sdk/evaluators/output_evaluator.mdx +++ b/src/content/docs/user-guide/evals-sdk/evaluators/output_evaluator.mdx @@ -1,5 +1,6 @@ --- title: Output Evaluator +tags: [conversation-management] sidebar: label: "Output" --- diff --git a/src/content/docs/user-guide/evals-sdk/evaluators/refusal_evaluator.mdx b/src/content/docs/user-guide/evals-sdk/evaluators/refusal_evaluator.mdx index 6a2449119..b3f4e3b4e 100644 --- a/src/content/docs/user-guide/evals-sdk/evaluators/refusal_evaluator.mdx +++ b/src/content/docs/user-guide/evals-sdk/evaluators/refusal_evaluator.mdx @@ -1,5 +1,6 @@ --- title: Refusal Evaluator +tags: [safety] sidebar: label: "Refusal" --- diff --git a/src/content/docs/user-guide/evals-sdk/evaluators/stereotyping_evaluator.mdx b/src/content/docs/user-guide/evals-sdk/evaluators/stereotyping_evaluator.mdx index 4e42dfaa5..43cc7b601 100644 --- a/src/content/docs/user-guide/evals-sdk/evaluators/stereotyping_evaluator.mdx +++ b/src/content/docs/user-guide/evals-sdk/evaluators/stereotyping_evaluator.mdx @@ -1,5 +1,6 @@ --- title: Stereotyping Evaluator +tags: [safety] sidebar: label: "Stereotyping" --- diff --git a/src/content/docs/user-guide/evals-sdk/evaluators/tool_parameter_evaluator.mdx b/src/content/docs/user-guide/evals-sdk/evaluators/tool_parameter_evaluator.mdx index 9bb2bb3b0..2de3ea70c 100644 --- a/src/content/docs/user-guide/evals-sdk/evaluators/tool_parameter_evaluator.mdx +++ b/src/content/docs/user-guide/evals-sdk/evaluators/tool_parameter_evaluator.mdx @@ -1,5 +1,6 @@ --- title: Tool Parameter Accuracy Evaluator +tags: [tool-evaluation] sidebar: label: "Tool Parameter Accuracy" --- diff --git a/src/content/docs/user-guide/evals-sdk/evaluators/tool_selection_evaluator.mdx b/src/content/docs/user-guide/evals-sdk/evaluators/tool_selection_evaluator.mdx index 774e7fcaa..f90796695 100644 --- a/src/content/docs/user-guide/evals-sdk/evaluators/tool_selection_evaluator.mdx +++ b/src/content/docs/user-guide/evals-sdk/evaluators/tool_selection_evaluator.mdx @@ -1,5 +1,6 @@ --- title: Tool Selection Accuracy Evaluator +tags: [tool-evaluation] sidebar: label: "Tool Selection Accuracy" --- diff --git a/src/content/docs/user-guide/evals-sdk/evaluators/trajectory_evaluator.mdx b/src/content/docs/user-guide/evals-sdk/evaluators/trajectory_evaluator.mdx index 8eb5cba4c..6f43ae321 100644 --- a/src/content/docs/user-guide/evals-sdk/evaluators/trajectory_evaluator.mdx +++ b/src/content/docs/user-guide/evals-sdk/evaluators/trajectory_evaluator.mdx @@ -1,5 +1,6 @@ --- title: Trajectory Evaluator +tags: [tool-evaluation] sidebar: label: "Trajectory" --- diff --git a/src/content/docs/user-guide/evals-sdk/experiment_generator.mdx b/src/content/docs/user-guide/evals-sdk/experiment_generator.mdx index f83a50985..dc4094cd7 100644 --- a/src/content/docs/user-guide/evals-sdk/experiment_generator.mdx +++ b/src/content/docs/user-guide/evals-sdk/experiment_generator.mdx @@ -1,5 +1,6 @@ --- title: Experiment Generator +tags: [simulation] --- ## Overview diff --git a/src/content/docs/user-guide/evals-sdk/how-to/agentcore_evaluation_dashboard.mdx b/src/content/docs/user-guide/evals-sdk/how-to/agentcore_evaluation_dashboard.mdx index f02498713..cd662547e 100644 --- a/src/content/docs/user-guide/evals-sdk/how-to/agentcore_evaluation_dashboard.mdx +++ b/src/content/docs/user-guide/evals-sdk/how-to/agentcore_evaluation_dashboard.mdx @@ -1,5 +1,6 @@ --- title: AgentCore Evaluation Dashboard Configuration +tags: [agentcore, aws, bedrock, observability] --- This guide explains how to configure AWS Distro for OpenTelemetry (ADOT) to send Strands evaluation results to Amazon CloudWatch, enabling visualization in the **GenAI Observability: Bedrock AgentCore Observability** dashboard. diff --git a/src/content/docs/user-guide/evals-sdk/how-to/eval_task.mdx b/src/content/docs/user-guide/evals-sdk/how-to/eval_task.mdx index 0ab082784..343f93494 100644 --- a/src/content/docs/user-guide/evals-sdk/how-to/eval_task.mdx +++ b/src/content/docs/user-guide/evals-sdk/how-to/eval_task.mdx @@ -1,5 +1,6 @@ --- title: Task Decorator +tags: [observability] sidebar: label: "Task Decorator" --- diff --git a/src/content/docs/user-guide/evals-sdk/how-to/result_caching.mdx b/src/content/docs/user-guide/evals-sdk/how-to/result_caching.mdx index 77239112b..460427254 100644 --- a/src/content/docs/user-guide/evals-sdk/how-to/result_caching.mdx +++ b/src/content/docs/user-guide/evals-sdk/how-to/result_caching.mdx @@ -1,5 +1,6 @@ --- title: Result Caching +tags: [caching] sidebar: label: "Result Caching" --- diff --git a/src/content/docs/user-guide/evals-sdk/how-to/serialization.mdx b/src/content/docs/user-guide/evals-sdk/how-to/serialization.mdx index de421bd9c..390d88b6d 100644 --- a/src/content/docs/user-guide/evals-sdk/how-to/serialization.mdx +++ b/src/content/docs/user-guide/evals-sdk/how-to/serialization.mdx @@ -1,5 +1,6 @@ --- title: Serialization +tags: [snapshots] --- ## Overview diff --git a/src/content/docs/user-guide/evals-sdk/how-to/trace_providers.mdx b/src/content/docs/user-guide/evals-sdk/how-to/trace_providers.mdx index 1f34ecba1..96dd6dc65 100644 --- a/src/content/docs/user-guide/evals-sdk/how-to/trace_providers.mdx +++ b/src/content/docs/user-guide/evals-sdk/how-to/trace_providers.mdx @@ -1,5 +1,6 @@ --- title: Evaluating Remote Traces +tags: [observability] --- Trace providers fetch agent execution data from observability backends and convert it into the format the evaluation pipeline expects. This lets you run evaluators against traces from production or staging agents without re-running them. diff --git a/src/content/docs/user-guide/evals-sdk/quickstart.mdx b/src/content/docs/user-guide/evals-sdk/quickstart.mdx index 5d769b152..e4adbf169 100644 --- a/src/content/docs/user-guide/evals-sdk/quickstart.mdx +++ b/src/content/docs/user-guide/evals-sdk/quickstart.mdx @@ -1,5 +1,6 @@ --- title: Strands Evaluation Quickstart +tags: [quickstart] sidebar: label: "Getting Started" --- diff --git a/src/content/docs/user-guide/evals-sdk/simulators/index.mdx b/src/content/docs/user-guide/evals-sdk/simulators/index.mdx index 6d7593c42..6cc82ccb6 100644 --- a/src/content/docs/user-guide/evals-sdk/simulators/index.mdx +++ b/src/content/docs/user-guide/evals-sdk/simulators/index.mdx @@ -1,5 +1,6 @@ --- title: Simulators +tags: [simulation] sidebar: label: "Overview" --- diff --git a/src/content/docs/user-guide/evals-sdk/simulators/tool_simulation.mdx b/src/content/docs/user-guide/evals-sdk/simulators/tool_simulation.mdx index b60ac6136..4951263b8 100644 --- a/src/content/docs/user-guide/evals-sdk/simulators/tool_simulation.mdx +++ b/src/content/docs/user-guide/evals-sdk/simulators/tool_simulation.mdx @@ -1,5 +1,6 @@ --- title: Tool Simulation +tags: [simulation, tool-evaluation] --- ## Overview diff --git a/src/content/docs/user-guide/evals-sdk/simulators/user_simulation.mdx b/src/content/docs/user-guide/evals-sdk/simulators/user_simulation.mdx index e5db836ce..0133d4a9b 100644 --- a/src/content/docs/user-guide/evals-sdk/simulators/user_simulation.mdx +++ b/src/content/docs/user-guide/evals-sdk/simulators/user_simulation.mdx @@ -1,5 +1,6 @@ --- title: User Simulation +tags: [simulation, conversation-management] --- ## Overview diff --git a/src/content/docs/user-guide/observability-evaluation/evaluation.mdx b/src/content/docs/user-guide/observability-evaluation/evaluation.mdx index 504a2b6c2..a0bcf52c1 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: [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..6592b031c 100644 --- a/src/content/docs/user-guide/observability-evaluation/logs.mdx +++ b/src/content/docs/user-guide/observability-evaluation/logs.mdx @@ -2,6 +2,7 @@ title: Logging sidebar: label: "Logs" +tags: [observability, pii] --- 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..3c38b2695 100644 --- a/src/content/docs/user-guide/observability-evaluation/metrics.mdx +++ b/src/content/docs/user-guide/observability-evaluation/metrics.mdx @@ -1,5 +1,6 @@ --- title: Metrics +tags: [observability] --- 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..ccdd05d9c 100644 --- a/src/content/docs/user-guide/observability-evaluation/observability.mdx +++ b/src/content/docs/user-guide/observability-evaluation/observability.mdx @@ -1,6 +1,7 @@ --- title: Observability description: "Monitor AI agents with OpenTelemetry traces, metrics, and logs. Debug agent behavior and measure performance in production." +tags: [observability] --- 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..d098c5279 100644 --- a/src/content/docs/user-guide/observability-evaluation/traces.mdx +++ b/src/content/docs/user-guide/observability-evaluation/traces.mdx @@ -1,5 +1,6 @@ --- title: Traces +tags: [observability] --- 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..4901a96c4 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] --- 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..c576a6fde 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] --- 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..7e17751e5 100644 --- a/src/content/docs/user-guide/safety-security/guardrails.mdx +++ b/src/content/docs/user-guide/safety-security/guardrails.mdx @@ -1,6 +1,7 @@ --- title: Guardrails description: "Add safety guardrails to AI agents. Control tool permissions, validate outputs, and enforce responsible AI policies in production." +tags: [safety, bedrock, aws] --- 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..5ab693d8e 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, observability, aws] --- 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..14c48e05f 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, conversation-management, prompt-authoring] --- 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..95fc1a4b1 --- /dev/null +++ b/src/util/related-docs.ts @@ -0,0 +1,140 @@ +/** + * Compute "Related pages" for user-guide docs. Headless-only — surfaced in + * //index.md, /llms-full.txt, and JSON-LD `relatedLink`. Not rendered + * on the HTML page itself. + * + * Called from src/util/render-to-markdown.ts (markdown/llms surfaces) and + * src/components/overrides/Head.astro (JSON-LD). + * + * --- Scoring --- + * + * For each candidate page, we ask: "of all the distinct tags between this + * page and the candidate, what fraction are in common?" Pages with more + * tags in common (relative to their combined tag set) score higher. + * + * The catch: not all shared tags are equally meaningful. A shared `aws` + * tag (used by 14 pages) tells us much less than a shared `bedrock` tag + * (used by 8) — the rarer tag is more topical. So we weight each tag by + * its *rarity*, computed as `1 - (pages_with_tag / total_tagged_pages)`. + * Common tags weight near 0; rare tags weight near 1. + * + * Putting it together — a candidate's score is: + * + * sum of rarity-weights of TAGS_IN_BOTH_PAGES + * ──────────────────────────────────────────── + * sum of rarity-weights of TAGS_IN_EITHER_PAGE + * + * Range is 0 (no shared tags) to 1 (identical tag sets). The denominator + * is what penalizes "this candidate matched on one tag but has 7 unrelated + * ones": adding extra tags to the candidate inflates the denominator and + * drops the score. + * + * --- Why this shape --- + * + * - A 1-tag match on a broad tag (e.g. just `aws`) ranks below any 2-tag + * specific match. Coincidental connections sink naturally. + * - Self-correcting as the corpus grows. If a tag bloats from 8 to 30 + * pages over time, its weight drops automatically and its 1-tag matches + * stop dominating — no manual audit needed to react. + * - Score is a ratio, so the threshold remains stable as the corpus grows + * roughly proportionally. Uneven growth (e.g. a flood of `aws`-tagged + * pages) does shift the meaning of the threshold and may warrant review. + * + * Tie-breaking on score: alphabetical by title. Deterministic. + */ +import type { CollectionEntry } from 'astro:content' + +export interface RelatedLink { + slug: string + title: string + /** Raw count of shared tags. Surfaced in the headless output as a hint. */ + overlap: number +} + +const HEADLESS_MAX = 10 +const USER_GUIDE_PREFIX = 'docs/user-guide/' + +function isUserGuide(entry: CollectionEntry<'docs'>): boolean { + return entry.id.startsWith(USER_GUIDE_PREFIX) +} + +interface ScoredCandidate { + doc: CollectionEntry<'docs'> + overlap: number + score: number +} + +/** + * Build a tag → specificity map for the user-guide corpus. + * specificity = 1 - freq/N, so rare tags weight heavier than common ones. + * + * Memoized on the `allDocs` array. Astro's `getCollection` returns a stable + * reference within a build, so successive calls (one per page render across + * Head.astro and render-to-markdown) hit the cache. + */ +const specificityCache = new WeakMap[], Map>() + +function tagSpecificity(allDocs: readonly CollectionEntry<'docs'>[]): Map { + const cached = specificityCache.get(allDocs) + if (cached) return cached + + const freq = new Map() + let totalTagged = 0 + for (const d of allDocs) { + if (!isUserGuide(d)) continue + const tags = d.data.tags ?? [] + if (tags.length === 0) continue + totalTagged++ + for (const t of tags) freq.set(t, (freq.get(t) ?? 0) + 1) + } + const specificity = new Map() + for (const [tag, count] of freq) { + specificity.set(tag, totalTagged > 0 ? 1 - count / totalTagged : 0) + } + specificityCache.set(allDocs, specificity) + return specificity +} + +/** + * All tagged user-guide candidates with non-zero overlap, sorted best-first. + */ +function rankedCandidates( + current: CollectionEntry<'docs'>, + allDocs: readonly CollectionEntry<'docs'>[], +): ScoredCandidate[] { + if (!isUserGuide(current)) return [] + const currentTags = current.data.tags ?? [] + if (currentTags.length === 0) return [] + const tagSet = new Set(currentTags) + const specificity = tagSpecificity(allDocs) + const weightOf = (t: string) => specificity.get(t) ?? 0 + + return allDocs + .filter((d) => d.id !== current.id && isUserGuide(d) && (d.data.tags ?? []).length > 0) + .map((d) => { + const otherTags = d.data.tags ?? [] + const sharedTags = otherTags.filter((t) => tagSet.has(t)) + const unionTags = [...new Set([...currentTags, ...otherTags])] + const sharedWeight = sharedTags.reduce((s, t) => s + weightOf(t), 0) + const unionWeight = unionTags.reduce((s, t) => s + weightOf(t), 0) + return { + doc: d, + overlap: sharedTags.length, + score: unionWeight === 0 ? 0 : sharedWeight / unionWeight, + } + }) + .filter((s) => s.overlap > 0) + .sort((a, b) => b.score - a.score || a.doc.data.title.localeCompare(b.doc.data.title)) +} + +function toLink({ doc, overlap }: ScoredCandidate): RelatedLink { + return { slug: doc.id, title: doc.data.title, overlap } +} + +/** Headless surface: top 10 by specificity-weighted Jaccard. */ +export function relatedUserGuideFor( + current: CollectionEntry<'docs'>, + allDocs: readonly CollectionEntry<'docs'>[], +): RelatedLink[] { + return rankedCandidates(current, allDocs).slice(0, HEADLESS_MAX).map(toLink) +} 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/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([]) + }) }) diff --git a/test/related-docs.test.ts b/test/related-docs.test.ts new file mode 100644 index 000000000..d11db29d3 --- /dev/null +++ b/test/related-docs.test.ts @@ -0,0 +1,100 @@ +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 (headless: top 10, specificity-weighted Jaccard)', () => { + it('ranks pages by score, 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 score 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 }, + ]) + }) + + it('prefers a focused match over a coincidental multi-tag match', () => { + // current shares 1 of its 2 tags with `focused` + // current shares 1 of its 2 tags with `coincidental` but `coincidental` + // has 6 unrelated tags. Specificity-weighted Jaccard correctly puts the + // focused match first because the union is much smaller. + const current = doc('docs/user-guide/a', 'A', ['bedrock', 'aws']) + const focused = doc('docs/user-guide/b', 'Focused', ['bedrock']) + const coincidental = doc('docs/user-guide/c', 'Coincidental', ['aws', 'multi-agent', 'observability', 'deployment', 'tools', 'hooks', 'event-loop']) + + const result = relatedUserGuideFor(current, [current, focused, coincidental]) + expect(result.map((r) => r.title)).toEqual(['Focused', 'Coincidental']) + }) +}) +