diff --git a/.agents/references/mdx-authoring.md b/.agents/references/mdx-authoring.md index 89479fa547..aa82117ddc 100644 --- a/.agents/references/mdx-authoring.md +++ b/.agents/references/mdx-authoring.md @@ -22,6 +22,21 @@ Practical reference for writing documentation in this repo. This site uses Astro ``` +`` is also globally available. Use it when shared prose needs to reference a language-specific identifier — any method name, parameter, class name, or short expression that differs between Python and TypeScript: + +```mdx +Use to customize the tool name. +The parameter controls retry behavior. +``` + +Renders as inline `` by default. Pass `plain` for plain text. Reacts live to the global language toggle — no page reload. + +**When to use `` vs ``:** +- ``: single identifier or short expression that differs by language, embedded in a prose sentence. +- ``: code blocks, multi-line examples, or content that's structurally different between languages. + +Never spell out both language variants manually in prose. Use `` instead. + For other Starlight components (`Aside`, `Card`, `CardGrid`, `LinkCard`, `Icon`, `Badge`), use explicit imports: ```mdx diff --git a/.agents/references/voice-guide.md b/.agents/references/voice-guide.md index b619000de1..740ac53a4b 100644 --- a/.agents/references/voice-guide.md +++ b/.agents/references/voice-guide.md @@ -322,7 +322,7 @@ Strands ships both a Python and TypeScript SDK. Most doc pages show code in both - Python has `from strands import Agent`, TypeScript has `import { Agent } from '@strands-agents/sdk'` (verify current package name) - Error handling differs: Python raises exceptions, TypeScript may use different patterns -**Prose between tabs should be language-neutral.** Don't write "Pass the `retry_strategy` parameter..." when the tabs show both Python and TypeScript. Write "Configure a retry strategy:" and let the code speak for itself. Language-specific parameter names belong in the code blocks, not in the prose. +**Prose between tabs should be language-neutral — or use ``.** When shared prose needs to reference a language-specific identifier, use the `` component rather than spelling out both variants manually. This adapts to the reader's language selection and keeps prose clean. For introductory sentences before tabs, you can also write language-neutral prose ("Configure a retry strategy:") and let the code speak for itself. **Never name the language inside its own tab.** The reader selected the tab; they know which language they're reading. State facts directly without prefixing the language name. The tab itself provides that context. diff --git a/.agents/skills/docs-audit/SKILL.md b/.agents/skills/docs-audit/SKILL.md index 8c91a21026..e1f77838af 100644 --- a/.agents/skills/docs-audit/SKILL.md +++ b/.agents/skills/docs-audit/SKILL.md @@ -59,6 +59,7 @@ Specific checks: - Is essential context at the top? - Is inline code properly formatted with backticks? - Is terminology consistent with the terminology lock? +- Are language-specific identifiers in shared prose using the `` component rather than being spelled out manually with language labels? ### Step 5: Competitive comparison (optional) diff --git a/.agents/skills/docs-reviewer/SKILL.md b/.agents/skills/docs-reviewer/SKILL.md index 6dba0d7940..04be361b18 100644 --- a/.agents/skills/docs-reviewer/SKILL.md +++ b/.agents/skills/docs-reviewer/SKILL.md @@ -27,7 +27,7 @@ Reference `../../references/voice-guide.md` for the full layer definitions. Chec - **Narrative flow:** Start with why the topic matters and what use-case problems it solves. Throughout, show how to implement using Strands SDK in a self-contained, concise way. - **Framing:** Does the first sentence of every section describe the developer's goal? Flag sections leading with API descriptions. - **Register:** Is the tone appropriate for the content type? -- **Constraints:** Scan for banned phrases, em-dashes, passive voice, hedging. Apply type-aware overrides (passive in reference is fine; longer sentences in explanation are fine). Flag any prose inside a `` that names the language of that tab (e.g., "Python requires..." inside the Python tab, "In TypeScript..." inside the TypeScript tab). The reader chose the tab; they know what language they're reading. +- **Constraints:** Scan for banned phrases, em-dashes, passive voice, hedging. Apply type-aware overrides (passive in reference is fine; longer sentences in explanation are fine). Flag any prose inside a `` that names the language of that tab (e.g., "Python requires..." inside the Python tab, "In TypeScript..." inside the TypeScript tab). The reader chose the tab; they know what language they're reading. Flag language-specific identifiers spelled out manually in shared prose — these should use the `` component to adapt to the reader's language selection. - **Authenticity:** Structural variety, visible editorial choices, concision. ### 2. Terminology Consistency diff --git a/.agents/skills/docs-writer/SKILL.md b/.agents/skills/docs-writer/SKILL.md index a2df46706a..c33d3a6642 100644 --- a/.agents/skills/docs-writer/SKILL.md +++ b/.agents/skills/docs-writer/SKILL.md @@ -52,7 +52,9 @@ Write each section following the outline. ### Step 3b: Apply MDX formatting -Apply MDX formatting patterns from `../../references/mdx-authoring.md` — especially Tabs/Tab syntax, snippet includes, and callout syntax. +Apply MDX formatting patterns from `../../references/mdx-authoring.md` — especially Tabs/Tab syntax, the `` component for inline language-specific identifiers, snippet includes, and callout syntax. + +When shared prose needs to reference a language-specific identifier (method name, parameter, class, etc.), use ``. This keeps prose clean and adapts to the reader's language selection. Never spell out both variants manually in prose. Code examples longer than a few lines live in runnable `.ts`/`.py` source files alongside the MDX page, not inline. Pull them in via the `--8<--` include syntax. See "Snippet Inclusion" and "TypeScript Snippet Scoping" in `mdx-authoring.md` for the imports/body file pattern and naming conventions. diff --git a/site/CONTRIBUTING.md b/site/CONTRIBUTING.md index 45dbc37337..9b245a05da 100644 --- a/site/CONTRIBUTING.md +++ b/site/CONTRIBUTING.md @@ -28,6 +28,7 @@ npm run build # generates static site - Content lives in `docs/` as standard Markdown files - Navigation structure is defined in `src/config/navigation.yml` - Use `` / `` for Python/TypeScript code tabs (auto-imported) +- Use `` for inline language-specific identifiers in prose (auto-imported). Renders as `` by default; pass `plain` for plain text. Reacts live to the global language toggle. - Use `--8<-- "path/to/file.ts:snippet_name"` to pull in code snippets from external files - Relative file links (e.g. `../tools/index.md`) resolve automatically — no need to use slugs - Link to API reference pages with the `@api` shorthand: `[@api/python/strands.agent.agent](#Class)` diff --git a/site/SITE-ARCHITECTURE.md b/site/SITE-ARCHITECTURE.md index 980ea7a6e8..3fdea50d0e 100644 --- a/site/SITE-ARCHITECTURE.md +++ b/site/SITE-ARCHITECTURE.md @@ -246,7 +246,7 @@ Available: `Tabs`/`TabItem`, `Aside`, `Card`/`CardGrid`, `LinkCard`, `Icon`, `Ba ### Auto-Imported Components -We use [astro-auto-import](https://github.com/delucis/astro-auto-import) to make `Tabs` and `Tab` available globally without explicit imports. Since language tabs appear on nearly every page, this reduces boilerplate. +We use [astro-auto-import](https://github.com/delucis/astro-auto-import) to make `Tabs`, `Tab`, and `Syntax` available globally without explicit imports. Since language tabs and inline language-specific identifiers appear on nearly every page, this reduces boilerplate. ```mdx @@ -266,6 +266,25 @@ For other components, use [explicit imports](https://starlight.astro.build/compo A wrapper around Starlight's `Tabs` that auto-generates a `syncKey` from tab labels. Tabs with identical label sets automatically sync together across the page. Auto-imported as `Tabs` (see above). +### `Syntax` + +Inline component for language-specific identifiers in prose. Renders the Python or TypeScript variant based on the global language toggle, avoiding the `"python_name (Python) or tsName (TypeScript)"` pattern. Auto-imported. + +```mdx +Pass to configure... +``` + +Props: +- `py` (required): Python syntax variant +- `ts` (required): TypeScript syntax variant +- `plain` (default: `false`): Renders as plain text instead of ``. + +The component reads the same `localStorage` key as the language toggle and swaps live without page reload. + +**When to use:** Any time a single identifier, method name, or parameter differs between Python and TypeScript and you're writing shared prose (not inside a `` section). + +**When NOT to use:** For code blocks (use ``), for conceptual differences between SDKs that aren't simple name swaps, or for content that only applies to one language. + ### `PageLink` Replaces the default anchor element to enable MkDocs-style relative linking. Resolves relative hrefs against the current page's path and validates against the content collection. Logs warnings in development for broken links. Auto-imported as the default `a` element. diff --git a/site/astro.config.mjs b/site/astro.config.mjs index 8292b12397..4aa6e932ac 100644 --- a/site/astro.config.mjs +++ b/site/astro.config.mjs @@ -101,6 +101,9 @@ export default defineConfig({ ], './src/components/AutoSyncTabs.astro': [ ['default', "Tabs"] + ], + './src/components/Syntax.astro': [ + ['default', 'Syntax'] ] }, ], diff --git a/site/src/components/Syntax.astro b/site/src/components/Syntax.astro new file mode 100644 index 0000000000..1c025ba971 --- /dev/null +++ b/site/src/components/Syntax.astro @@ -0,0 +1,69 @@ +--- +interface Props { + py: string; + ts: string; + plain?: boolean; +} + +const { py, ts, plain = false } = Astro.props; +--- + + + {plain ? ( + <> + {py} + {ts} + + ) : ( + <> + {py} + {ts} + + )} + + + + + diff --git a/site/src/content/docs/contribute/contributing/documentation.mdx b/site/src/content/docs/contribute/contributing/documentation.mdx index fdada4cbdf..96d8a569d2 100644 --- a/site/src/content/docs/contribute/contributing/documentation.mdx +++ b/site/src/content/docs/contribute/contributing/documentation.mdx @@ -6,6 +6,27 @@ sidebar: Good documentation helps developers succeed with Strands. We welcome contributions that make our docs clearer, more complete, or more helpful. Our documentation lives in the `site/` directory of the [Strands SDK repository](https://github.com/strands-agents/harness-sdk). +## Agent skills + +The repository ships agent skills in `.agents/skills/` that encode our documentation conventions, site components, and quality standards. If you're using an AI coding assistant, activate these skills before making documentation changes — they'll produce output that matches our style without you needing to internalize everything on this page. + +| Skill | What it does | +|-------|--------------| +| `docs-writer` | Drafts or rewrites documentation pages following site conventions | +| `docs-reviewer` | Reviews drafts for voice, structure, and terminology before PR | +| `docs-audit` | Assesses a page for quality, accuracy, and voice compliance | +| `docs-planner` | Identifies documentation gaps and prioritizes the backlog | + +Use them by giving your agent a goal that references the skill: + +``` +Write a new doc page for the retry strategies feature. Use the docs-writer skill. +``` + +``` +Audit the context management page for accuracy and voice issues. Use the docs-audit skill. +``` + ## What we accept We're looking for contributions that improve the developer experience. Documentation changes can range from small typo fixes to complete new guides. @@ -115,3 +136,4 @@ agent("What's the weather like?") + diff --git a/site/src/content/docs/user-guide/concepts/agents/agent-loop.mdx b/site/src/content/docs/user-guide/concepts/agents/agent-loop.mdx index 1ae27948a2..dd723aa7d4 100644 --- a/site/src/content/docs/user-guide/concepts/agents/agent-loop.mdx +++ b/site/src/content/docs/user-guide/concepts/agents/agent-loop.mdx @@ -87,9 +87,9 @@ Each model invocation ends with a stop reason that determines what happens next: - **End turn**: The model has finished its response and has no further actions to take. This is the normal successful termination. The loop exits and returns the model's final message. - **Tool use**: The model wants to execute one or more tools before continuing. The loop executes the requested tools, appends the results to the conversation history, and invokes the model again. - **Cancelled**: The agent was stopped externally via `agent.cancel()`. See [Cancellation](#cancellation) below. -- **Limit turns** (`limit_turns` / `limitTurns`): The per-invocation turn budget was exhausted. See [Invocation Limits](#invocation-limits). -- **Limit total tokens** (`limit_total_tokens` / `limitTotalTokens`): The cumulative token budget was exhausted. See [Invocation Limits](#invocation-limits). -- **Limit output tokens** (`limit_output_tokens` / `limitOutputTokens`): The output token budget was exhausted. See [Invocation Limits](#invocation-limits). +- **Limit turns** (): The per-invocation turn budget was exhausted. See [Invocation Limits](#invocation-limits). +- **Limit total tokens** (): The cumulative token budget was exhausted. See [Invocation Limits](#invocation-limits). +- **Limit output tokens** (): The output token budget was exhausted. See [Invocation Limits](#invocation-limits). - **Max tokens**: The model's response was truncated because it hit the token limit. This is unrecoverable within the current loop. The model cannot continue from a partial response, and the loop terminates with an error. - **Stop sequence**: The model encountered a configured stop sequence. Like end turn, this terminates the loop normally. - **Content filtered**: The response was blocked by safety mechanisms. diff --git a/site/src/content/docs/user-guide/concepts/agents/conversation-management.mdx b/site/src/content/docs/user-guide/concepts/agents/conversation-management.mdx index cd54b5e012..0e30750c09 100644 --- a/site/src/content/docs/user-guide/concepts/agents/conversation-management.mdx +++ b/site/src/content/docs/user-guide/concepts/agents/conversation-management.mdx @@ -100,7 +100,7 @@ Key features of the `SlidingWindowConversationManager`: - **Maintains Window Size**: Automatically removes messages from the window if the number of messages exceeds the limit. - **Dangling Message Cleanup**: Removes incomplete message sequences to maintain valid conversation state. - **Overflow Trimming**: In the case of a context window overflow, it will trim the oldest messages from history until the request fits in the models context window. -- **Configurable Tool Result Truncation**: Enable or disable truncation of tool results when the message exceeds context window limits. When enabled (the default; `should_truncate_results=True` in Python, `shouldTruncateResults: true` in TypeScript), the oldest message with tool results is truncated first so recent context is preserved as long as possible. Truncation depends on content type: +- **Configurable Tool Result Truncation**: Enable or disable truncation of tool results when the message exceeds context window limits. When enabled (the default; ), the oldest message with tool results is truncated first so recent context is preserved as long as possible. Truncation depends on content type: - Text payloads keep their head and tail, separated by a `` marker. - Images, videos, binary documents, and oversized JSON are replaced by a typed placeholder, for example `[image: png, source: bytes, 12345 bytes]`. - The tool result's original `status` and `error` fields are preserved. diff --git a/site/src/content/docs/user-guide/concepts/agents/hooks.mdx b/site/src/content/docs/user-guide/concepts/agents/hooks.mdx index 8f9cc4e926..9f0d0c21ba 100644 --- a/site/src/content/docs/user-guide/concepts/agents/hooks.mdx +++ b/site/src/content/docs/user-guide/concepts/agents/hooks.mdx @@ -28,7 +28,7 @@ Hook callbacks are registered against specific event types and receive strongly- ### Registering Individual Hook Callbacks -The simplest way to register a hook callback is using the `agent.add_hook()` method: +The simplest way to register a hook callback is using the method: diff --git a/site/src/content/docs/user-guide/concepts/agents/prompts.mdx b/site/src/content/docs/user-guide/concepts/agents/prompts.mdx index e2843c71c9..8dbd091b0e 100644 --- a/site/src/content/docs/user-guide/concepts/agents/prompts.mdx +++ b/site/src/content/docs/user-guide/concepts/agents/prompts.mdx @@ -110,7 +110,7 @@ result = agent.tool.current_time(timezone="US/Pacific") -Direct tool calls bypass the natural language interface and execute the tool using specified parameters. These calls are added to the conversation history by default. However, you can opt out of this behavior by setting `record_direct_tool_call=False` in Python. +Direct tool calls bypass the natural language interface and execute the tool using specified parameters. These calls are added to the conversation history by default. However, you can opt out of this behavior by setting . ## Prompt Engineering diff --git a/site/src/content/docs/user-guide/concepts/agents/retry-strategies.mdx b/site/src/content/docs/user-guide/concepts/agents/retry-strategies.mdx index 36e0957c76..1623a10de7 100644 --- a/site/src/content/docs/user-guide/concepts/agents/retry-strategies.mdx +++ b/site/src/content/docs/user-guide/concepts/agents/retry-strategies.mdx @@ -3,7 +3,7 @@ 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 throttled responses automatically with exponential backoff. The `Agent.retry_strategy` (Python) or `Agent.retryStrategy` (TypeScript) parameter lets you customize this behavior. +Model providers occasionally encounter errors such as rate limits, service unavailability, or network timeouts. By default, the agent retries throttled responses automatically with exponential backoff. The parameter lets you customize this behavior. ## Default Behavior @@ -129,7 +129,7 @@ agent = Agent( ## When Retries Occur -Default retry strategies handle throttling errors (`ModelThrottledException` in Python, `ModelThrottledError` in TypeScript) raised by model providers for rate-limiting. Other exceptions propagate immediately without retry. +Default retry strategies handle throttling errors () raised by model providers for rate-limiting. Other exceptions propagate immediately without retry. To extend or narrow the retryable set, see [Custom Retry Logic](#custom-retry-logic). diff --git a/site/src/content/docs/user-guide/concepts/agents/snapshots.mdx b/site/src/content/docs/user-guide/concepts/agents/snapshots.mdx index efc96d26e8..77e84f1e6e 100644 --- a/site/src/content/docs/user-guide/concepts/agents/snapshots.mdx +++ b/site/src/content/docs/user-guide/concepts/agents/snapshots.mdx @@ -144,7 +144,7 @@ snapshot = agent.take_snapshot(preset="session", exclude=["interrupt_state"]) ## Application Data -Snapshots support an `app_data` (Python) / `appData` (TypeScript) field for storing application-owned data alongside the agent state. Strands does not read or modify this data — it's passed through verbatim. +Snapshots support an field for storing application-owned data alongside the agent state. Strands does not read or modify this data — it's passed through verbatim. This is useful for attaching metadata like a display name for the snapshot, the current step in a workflow, user preferences, or any other context your application needs to associate with a particular point in time. diff --git a/site/src/content/docs/user-guide/concepts/agents/state.mdx b/site/src/content/docs/user-guide/concepts/agents/state.mdx index acb6ee147a..2680d6eb20 100644 --- a/site/src/content/docs/user-guide/concepts/agents/state.mdx +++ b/site/src/content/docs/user-guide/concepts/agents/state.mdx @@ -318,7 +318,7 @@ print(result.state) -Invocation state (`invocationState` in TypeScript, `invocation_state` / `request_state` in Python): +Invocation state (): - Is initialized at the beginning of each agent invocation (defaults to `{}` when omitted) - Persists through recursive event loop cycles within a single invocation diff --git a/site/src/content/docs/user-guide/concepts/agents/structured-output.mdx b/site/src/content/docs/user-guide/concepts/agents/structured-output.mdx index 184dff90b9..950379f062 100644 --- a/site/src/content/docs/user-guide/concepts/agents/structured-output.mdx +++ b/site/src/content/docs/user-guide/concepts/agents/structured-output.mdx @@ -28,7 +28,7 @@ Key benefits: ## Basic Usage -Define an output structure using a schema. In Python, use a Pydantic model and pass it to `structured_output_model`. In TypeScript, use a Zod schema and pass it to `structuredOutputSchema`. Then, access the validated output from the `AgentResult`. +Define an output structure using a schema and pass it to . Then, access the validated output from the `AgentResult`. @@ -97,7 +97,7 @@ result = asyncio.run( The structured output system converts your schema definitions into tool specifications that guide the language model to produce correctly formatted responses. All of the model providers supported in Strands can work with Structured Output. -In Python, Strands accepts the `structured_output_model` parameter in agent invocations, which manages the conversion, validation, and response processing automatically. In TypeScript, the `structuredOutputSchema` parameter (either at agent initialization or per-invocation) handles this process. The validated result is available in the `AgentResult.structured_output` (Python) or `AgentResult.structuredOutput` (TypeScript) field. +Strands accepts the parameter in agent invocations, which manages the conversion, validation, and response processing automatically. The validated result is available in the field. ### Error Handling diff --git a/site/src/content/docs/user-guide/concepts/context-management.mdx b/site/src/content/docs/user-guide/concepts/context-management.mdx index 610d0624a5..1778ebde35 100644 --- a/site/src/content/docs/user-guide/concepts/context-management.mdx +++ b/site/src/content/docs/user-guide/concepts/context-management.mdx @@ -14,7 +14,7 @@ The SDK provides several layers of context management that you can use independe ## Automatic context management -For most agents with multi-turn conversations, you don't need to configure conversation management and context offloading separately. Pass `context_manager="auto"` (Python) or `contextManager: "auto"` (TypeScript) and the SDK wires up both with tuned defaults: +For most agents with multi-turn conversations, you don't need to configure conversation management and context offloading separately. Pass and the SDK wires up both with tuned defaults: @@ -48,7 +48,7 @@ For full details on each component, see [Conversation Management](./agents/conve Your own settings take precedence when you need fine-grained control: -- **Custom conversation manager**: If you also pass `conversation_manager` / `conversationManager`, your manager replaces the auto-composed `SummarizingConversationManager`. The SDK still adds the `ContextOffloader` plugin. +- **Custom conversation manager**: If you also pass , your manager replaces the auto-composed `SummarizingConversationManager`. The SDK still adds the `ContextOffloader` plugin. - **Existing ContextOffloader**: If your `plugins` list already contains a `ContextOffloader` instance, no duplicate is added. Your configuration is preserved. @@ -82,6 +82,6 @@ agent = Agent( ### Limitations -**Stateful models**: Stateful models manage conversation state server-side. Setting `context_manager="auto"` with a stateful model raises a `ValueError` (Python) or `Error` (TypeScript). +**Stateful models**: Stateful models manage conversation state server-side. Setting with a stateful model raises a . The auto-composed offloader uses in-memory storage that does not persist across process restarts. If your agent uses session management and needs durable offloaded content, configure an explicit `ContextOffloader` with `FileStorage` or `S3Storage`. See [Storage Backends](./plugins/context-offloader#storage-backends). diff --git a/site/src/content/docs/user-guide/concepts/model-providers/google.mdx b/site/src/content/docs/user-guide/concepts/model-providers/google.mdx index 0925d2f576..5078744074 100644 --- a/site/src/content/docs/user-guide/concepts/model-providers/google.mdx +++ b/site/src/content/docs/user-guide/concepts/model-providers/google.mdx @@ -221,7 +221,7 @@ If you encounter import errors for `@google/genai`, ensure the package is instal ### API Key Issues -Make sure your Google AI API key is properly set via `client_args` (Python) or `apiKey` (TypeScript), or as the `GOOGLE_API_KEY` / `GEMINI_API_KEY` environment variable. You can obtain an API key from the [Google AI Studio](https://aistudio.google.com/app/apikey). +Make sure your Google AI API key is properly set via , or as the `GOOGLE_API_KEY` / `GEMINI_API_KEY` environment variable. You can obtain an API key from the [Google AI Studio](https://aistudio.google.com/app/apikey). ### Rate Limiting and Safety Issues diff --git a/site/src/content/docs/user-guide/concepts/multi-agent/agents-as-tools.mdx b/site/src/content/docs/user-guide/concepts/multi-agent/agents-as-tools.mdx index 9926f2525b..4b8edb8884 100644 --- a/site/src/content/docs/user-guide/concepts/multi-agent/agents-as-tools.mdx +++ b/site/src/content/docs/user-guide/concepts/multi-agent/agents-as-tools.mdx @@ -34,7 +34,7 @@ When implementing the "Agents as Tools" pattern with Strands Agents SDK: ## Implementing Agents as Tools with Strands Agents SDK -Strands Agents SDK provides three ways to implement the "Agents as Tools" pattern: passing agents directly in the `tools` array for the simplest setup, `.as_tool()`/`.asTool()` when you need to customize tool name, description, or context behavior, and the `@tool` decorator or `tool()` function for full control over how the agent is invoked. +Strands Agents SDK provides three ways to implement the "Agents as Tools" pattern: passing agents directly in the `tools` array for the simplest setup, when you need to customize tool name, description, or context behavior, and the `@tool` decorator or `tool()` function for full control over how the agent is invoked. ```mermaid flowchart TD @@ -102,7 +102,7 @@ orchestrator = Agent( ### Customizing Agent Tools -When you need to customize the tool name, description, or context behavior, use `.as_tool()` (Python) or `.asTool()` (TypeScript) explicitly: +When you need to customize the tool name, description, or context behavior, use explicitly: @@ -129,7 +129,7 @@ orchestrator = Agent( #### Context Management -By default, both direct passing and `.as_tool()`/`.asTool()` reset the agent's conversation context between invocations, ensuring every call starts from a clean baseline. To preserve the agent's conversation history across invocations: +By default, both direct passing and reset the agent's conversation context between invocations, ensuring every call starts from a clean baseline. To preserve the agent's conversation history across invocations: diff --git a/site/src/content/docs/user-guide/concepts/plugins/context-offloader.mdx b/site/src/content/docs/user-guide/concepts/plugins/context-offloader.mdx index 068d6b6b74..219656a1e7 100644 --- a/site/src/content/docs/user-guide/concepts/plugins/context-offloader.mdx +++ b/site/src/content/docs/user-guide/concepts/plugins/context-offloader.mdx @@ -19,12 +19,12 @@ The default [`SlidingWindowConversationManager`](../agents/conversation-manageme ## How It Works -After each tool call, the plugin estimates the result's token count and compares it against the `max_result_tokens` threshold (default: 2,500 tokens). If the result exceeds it, the plugin: +After each tool call, the plugin estimates the result's token count and compares it against the threshold (default: 2,500 tokens). If the result exceeds it, the plugin: 1. Stores each content block individually in the configured storage backend, preserving its content type -2. Replaces the in-context result with the first `preview_tokens` tokens (default: 1,000) plus per-block storage references +2. Replaces the in-context result with the first tokens (default: 1,000) plus per-block storage references -Token estimation uses `model.count_tokens()`, which delegates to the model provider's native counting API if available, otherwise falling back to a character-based heuristic (chars/4 for text, chars/2 for JSON). +Token estimation uses , which delegates to the model provider's native counting API if available, otherwise falling back to a character-based heuristic (chars/4 for text, chars/2 for JSON). Results under the threshold pass through unchanged. @@ -43,7 +43,7 @@ For non-text content, the plugin replaces the result with a descriptive placehol | Content Type | What the agent sees | |-------------|----------| -| Text / JSON | First `preview_tokens` tokens + storage reference | +| Text / JSON | First tokens + storage reference | | Image | `[image: format, N bytes]` placeholder + storage reference | | Document | `[document: format, name, N bytes]` placeholder + storage reference | diff --git a/site/src/content/docs/user-guide/concepts/plugins/index.mdx b/site/src/content/docs/user-guide/concepts/plugins/index.mdx index d1f1c7bc09..ed0d06b818 100644 --- a/site/src/content/docs/user-guide/concepts/plugins/index.mdx +++ b/site/src/content/docs/user-guide/concepts/plugins/index.mdx @@ -4,7 +4,7 @@ tags: [hooks, event-loop] description: "Extend agent behavior with plugins. Add steering, guardrails, and custom capabilities that hook into the agent lifecycle." --- -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. +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`, , `messages`, `tools`, and `hooks`—and executing logic to improve an agent's behavior. The Strands SDK provides built-in plugins that you can use out of the box: @@ -176,7 +176,7 @@ TypeScript plugins register hooks manually in the `initAgent` method using `agen ### Manual Hook and Tool Registration -For more control, you can manually register hooks and tools in the `init_agent` method: +For more control, you can manually register hooks and tools in the method: diff --git a/site/src/content/docs/user-guide/concepts/plugins/skills.mdx b/site/src/content/docs/user-guide/concepts/plugins/skills.mdx index 5e8a6e5a5f..8edd7ea4f3 100644 --- a/site/src/content/docs/user-guide/concepts/plugins/skills.mdx +++ b/site/src/content/docs/user-guide/concepts/plugins/skills.mdx @@ -62,7 +62,7 @@ The injected system prompt metadata looks like this: ``` -This XML block is refreshed before each invocation, so changes to available skills (through `set_available_skills` / `setAvailableSkills`) take effect immediately. Activated skills are tracked in [agent state](../agents/state.mdx) for session persistence. +This XML block is refreshed before each invocation, so changes to available skills (through ) take effect immediately. Activated skills are tracked in [agent state](../agents/state.mdx) for session persistence. ## Usage @@ -263,7 +263,7 @@ The `allowed-tools` field is currently informational. When a skill is activated, ::: :::note[Name validation] -Skill names must match the parent directory name. By default, validation issues produce warnings rather than errors. Pass `strict=True` (Python) or `strict: true` (TypeScript) to raise exceptions instead. +Skill names must match the parent directory name. By default, validation issues produce warnings rather than errors. Pass to raise exceptions instead. ::: ### Resource directories diff --git a/site/src/content/docs/user-guide/concepts/tools/index.mdx b/site/src/content/docs/user-guide/concepts/tools/index.mdx index 0d0e60a6d7..c11ada9ebe 100644 --- a/site/src/content/docs/user-guide/concepts/tools/index.mdx +++ b/site/src/content/docs/user-guide/concepts/tools/index.mdx @@ -478,7 +478,7 @@ For more information on using MCP tools, see [MCP Tools](mcp-tools.md). ### 4. Agents as Tools -Agents can be passed directly in another agent's `tools` array — the SDK automatically converts them into tools. Use `.as_tool()` (Python) or `.asTool()` (TypeScript) when you need to customize the tool name, description, or context behavior. For full details, see [Agents as Tools](../multi-agent/agents-as-tools.md). +Agents can be passed directly in another agent's `tools` array — the SDK automatically converts them into tools. Use when you need to customize the tool name, description, or context behavior. For full details, see [Agents as Tools](../multi-agent/agents-as-tools.md). diff --git a/site/src/content/docs/user-guide/observability-evaluation/traces.mdx b/site/src/content/docs/user-guide/observability-evaluation/traces.mdx index d098c5279d..48d00fe924 100644 --- a/site/src/content/docs/user-guide/observability-evaluation/traces.mdx +++ b/site/src/content/docs/user-guide/observability-evaluation/traces.mdx @@ -414,7 +414,7 @@ with tracer.start_as_current_span("my-custom-operation") as span: :::tip -`getTracer()` (TypeScript) and `trace.get_tracer()` (Python) use the global tracer provider. When you use `setupTracer()` or `StrandsTelemetry()` without a custom provider, it's automatically registered as global — so your custom spans will use the same provider as the agent's auto-instrumented spans. + uses the global tracer provider. When you use without a custom provider, it's automatically registered as global — so your custom spans will use the same provider as the agent's auto-instrumented spans. ::: ### Configuring the exporters from source code