From 94d4d95def17a9c268a78e895846f51502b0bc81 Mon Sep 17 00:00:00 2001 From: Jaroslav Pantsjoha Date: Sat, 18 Oct 2025 13:21:49 +0100 Subject: [PATCH 1/3] docs(tools): add best practices guide for function tools Add comprehensive best practices guide covering: - File upload handling patterns (both uploaded files and file paths) - Type annotation requirements - Tool naming conventions - Docstring standards - Error handling patterns - Structured return values Addresses common pitfalls and provides examples for building robust function tools in ADK. Relocates content from google/adk-python#3193 as requested by @boyangsvl. --- docs/tools/best-practices.md | 256 +++++++++++++++++++++++++++++++++++ 1 file changed, 256 insertions(+) create mode 100644 docs/tools/best-practices.md diff --git a/docs/tools/best-practices.md b/docs/tools/best-practices.md new file mode 100644 index 000000000..6834c39d7 --- /dev/null +++ b/docs/tools/best-practices.md @@ -0,0 +1,256 @@ +# Best Practices for Function Tools + +This guide provides best practices and common patterns for building robust and user-friendly function tools in ADK. + +## Handling File Uploads + +When building agents that process files, you often need to handle both: + +1. Files uploaded directly through the chat interface +2. File paths provided as text by the user + +### Problem + +Without explicit handling, agents may: + +- Ask for file paths even when files are already uploaded +- Fail to recognize uploaded files as attachments +- Pass incorrect parameters to parsing tools + +### Solution: Flexible File Path Handling + +Design your tools to accept both display names (from uploaded files) and full file paths. + +???+ example "File Upload Tool Pattern" + === "Python" + ```python + import os + + def parse_document(doc_path: str = "uploaded_document") -> str: + """Parses a document (uploaded file or file path). + + Args: + doc_path: Display name of uploaded file or full file path. + + Returns: + Success message with output path. + """ + # Handle both uploaded file identifiers and full paths + if '/' in doc_path: + # Full path provided + run_id = os.path.basename(os.path.dirname(doc_path)) + else: + # Uploaded file display name or simple identifier + run_id = doc_path.replace('.', '_') + + output_path = f"output/{run_id}.xml" + os.makedirs(os.path.dirname(output_path), exist_ok=True) + + # ... your parsing logic here + + return f"Successfully parsed document to {output_path}" + ``` + +### Agent Instructions + +Your agent instructions should explicitly guide the LLM on how to handle both upload methods: + +???+ example "Agent Instructions for File Handling" + === "Python" + ```python + from google.adk import Agent + + agent = Agent( + name="DocumentParser", + model="gemini-2.0-flash", + instruction=""" + You are a document parsing agent. + + When the user provides files: + 1. If files are uploaded directly in the chat: + - Acknowledge them by their display names + - Call parsing tools with their display names or identifiers + - You can identify uploaded files by their presence as attachments + 2. If file paths are provided in text: + - Call parsing tools with the exact paths provided + + Do not ask for file paths if files are already uploaded. + """, + tools=[parse_document] + ) + ``` + +### Why This Matters + +This pattern ensures your agent gracefully handles both upload methods, providing a better user experience. + +#### Example Usage + +**Uploaded File**: +``` +User: [Uploads: report.pdf] + Parse this document + +Agent: [Calls parse_document("report.pdf")] +``` + +**File Path**: +``` +User: Parse the document at /path/to/reports/quarterly_report.pdf + +Agent: [Calls parse_document("/path/to/reports/quarterly_report.pdf")] +``` + +## Type Annotations + +Always use explicit type annotations for function tool parameters to ensure proper schema generation. + +!!! warning "Use Explicit Types" + Bare `list` and `dict` types can cause schema validation errors. Always specify item types. + +???+ example "Proper Type Annotations" + === "❌ Invalid" + ```python + def process_items(items: list) -> str: + """This causes Gemini schema validation errors.""" + pass + ``` + === "✅ Valid" + ```python + from typing import List + + def process_items(items: List[str]) -> str: + """Properly typed for Gemini schema generation.""" + pass + ``` + +## Tool Naming + +Use clear, descriptive names for your tools that indicate their purpose: + +- ✅ `get_weather_forecast` +- ✅ `parse_pdf_document` +- ✅ `calculate_tax_liability` +- ❌ `tool1` +- ❌ `process` +- ❌ `do_thing` + +## Docstrings + +Provide comprehensive docstrings with `Args` and `Returns` sections. The LLM uses these to understand when and how to use your tool. + +???+ example "Well-Documented Tool" + === "Python" + ```python + def get_weather(city: str, unit: str = "celsius") -> dict: + """Retrieves current weather for a specified city. + + This function fetches real-time weather data including temperature, + humidity, and conditions for the requested city. + + Args: + city: The name of the city (e.g., "London", "New York"). + unit: Temperature unit, either "celsius" or "fahrenheit". + Defaults to "celsius". + + Returns: + A dictionary containing: + - temperature: Current temperature as a float + - humidity: Humidity percentage as an integer + - conditions: Weather conditions as a string + - timestamp: UTC timestamp of the reading + + Example: + >>> get_weather("Paris", "celsius") + { + "temperature": 18.5, + "humidity": 65, + "conditions": "Partly cloudy", + "timestamp": "2025-10-18T10:30:00Z" + } + """ + # ... implementation + ``` + +## Error Handling + +Return clear, actionable error messages that help the LLM understand what went wrong and how to fix it. + +???+ example "Error Handling" + === "❌ Poor Error Handling" + ```python + def validate_email(email: str) -> bool: + if "@" not in email: + raise ValueError("Invalid") + return True + ``` + === "✅ Good Error Handling" + ```python + def validate_email(email: str) -> dict: + """Validates an email address format. + + Args: + email: The email address to validate. + + Returns: + A dictionary with 'valid' (bool) and 'message' (str) fields. + """ + if "@" not in email: + return { + "valid": False, + "message": f"Email '{email}' is missing '@' symbol. " + "Expected format: user@domain.com" + } + + if "." not in email.split("@")[1]: + return { + "valid": False, + "message": f"Email '{email}' domain is missing a TLD. " + "Expected format: user@domain.com" + } + + return { + "valid": True, + "message": f"Email '{email}' is valid." + } + ``` + +## Return Values + +Structure return values consistently and include enough context for the LLM to provide useful responses to the user. + +???+ tip "Structured Returns" + Return dictionaries with clear field names rather than plain strings or tuples when you have multiple pieces of information to convey. + + === "❌ Unclear Return" + ```python + def search_products(query: str) -> str: + return "Found 3 items: item1, item2, item3" + ``` + === "✅ Structured Return" + ```python + def search_products(query: str) -> dict: + """Searches for products matching the query. + + Returns: + A dictionary containing: + - count: Number of products found + - products: List of product dictionaries + - query: The original search query + """ + return { + "count": 3, + "products": [ + {"id": 1, "name": "item1", "price": 19.99}, + {"id": 2, "name": "item2", "price": 29.99}, + {"id": 3, "name": "item3", "price": 39.99} + ], + "query": query + } + ``` + +## See Also + +- [Function Tools](function-tools.md) - Learn how to create function tools +- [Long Running Tools](function-tools.md#long-run-tool) - Handle tools that take time to execute +- [Tool Performance](performance.md) - Optimize tool execution From b351dfca55185fb0f7a2e2862d6f5850a22a1b3d Mon Sep 17 00:00:00 2001 From: Jaroslav Pantsjoha Date: Sat, 18 Oct 2025 13:21:49 +0100 Subject: [PATCH 2/3] docs: add best-practices.md to navigation Add new best practices guide to mkdocs.yml navigation under 'Custom Tools > Function tools' section. Fixes mkdocs build warning about page not in nav configuration. --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index 2d731c2f5..4cdc2b553 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -192,6 +192,7 @@ nav: - tools-custom/index.md - Function tools: - Overview: tools-custom/function-tools.md + - Best practices: tools/best-practices.md - Tool performance: tools-custom/performance.md - Action confirmations: tools-custom/confirmation.md - MCP tools: tools-custom/mcp-tools.md From 4bd12ff5c837679323ebc092c1e950163f976647 Mon Sep 17 00:00:00 2001 From: JP Date: Wed, 19 Nov 2025 12:16:17 +0000 Subject: [PATCH 3/3] fix: move best-practices.md to correct directory structure - Move from tools/ to tools-custom/ to match existing Custom Tools organization - Update navigation path in mkdocs.yml to maintain structural consistency - Addresses path inconsistency while preserving approved content --- .../{tools => tools-custom}/best-practices.md | 0 mkdocs.yml | 2 +- mkdocs.yml.backup | 394 ++++++++++++++++++ mkdocs_fixed.yml | 138 ++++++ 4 files changed, 533 insertions(+), 1 deletion(-) rename docs/{tools => tools-custom}/best-practices.md (100%) create mode 100644 mkdocs.yml.backup create mode 100644 mkdocs_fixed.yml diff --git a/docs/tools/best-practices.md b/docs/tools-custom/best-practices.md similarity index 100% rename from docs/tools/best-practices.md rename to docs/tools-custom/best-practices.md diff --git a/mkdocs.yml b/mkdocs.yml index 4cdc2b553..7333f50fe 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -192,7 +192,7 @@ nav: - tools-custom/index.md - Function tools: - Overview: tools-custom/function-tools.md - - Best practices: tools/best-practices.md + - Best practices: tools-custom/best-practices.md - Tool performance: tools-custom/performance.md - Action confirmations: tools-custom/confirmation.md - MCP tools: tools-custom/mcp-tools.md diff --git a/mkdocs.yml.backup b/mkdocs.yml.backup new file mode 100644 index 000000000..620d6b476 --- /dev/null +++ b/mkdocs.yml.backup @@ -0,0 +1,394 @@ +# Project information +site_name: Agent Development Kit +site_url: https://google.github.io/adk-docs +site_description: >- + Build powerful multi-agent systems with Agent Development Kit +site_dir: site +exclude_docs: + api-reference/java/legal/* + +# Repository +repo_name: adk-docs +repo_url: https://github.com/google/adk-docs +edit_uri: edit/main/docs/ + +# Copyright +copyright: Copyright Google 2025  |  Terms  |  Privacy  |  Manage cookies + +# Custom CSS +extra_css: + - stylesheets/custom.css + - stylesheets/language-tags.css + +extra: + first_repo_url: https://github.com/google/adk-python + first_repo_name: adk-python + first_repo_icon: fontawesome/brands/github + second_repo_url: https://github.com/google/adk-go + second_repo_name: adk-go + second_repo_icon: fontawesome/brands/github + third_repo_url: https://github.com/google/adk-java + third_repo_name: adk-java + third_repo_icon: fontawesome/brands/github + analytics: + provider: google + property: G-DKHZS27PHP + consent: + title: Cookie consent + description: >- + We use cookies to recognize repeated visits and preferences, + as well as to measure the effectiveness of our documentation and + whether users find the information they need. With your consent, + you're helping us to make our documentation better. + +# Configuration +theme: + name: material + font: + text: Google Sans + code: Roboto Mono + logo: assets/agent-development-kit.png + favicon: assets/agent-development-kit.png + icon: + repo: fontawesome/brands/github + custom_dir: overrides + palette: + - scheme: default + primary: white + accent: white + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - scheme: slate + primary: white + accent: white + toggle: + icon: material/brightness-4 + name: Switch to light mode + features: + - content.action.edit + - content.action.view + - content.code.annotate + - content.code.copy + - content.code.select + - content.tabs.link + - content.tooltips + - navigation.footer + - navigation.indexes + - navigation.instant + - navigation.instant.progress + - navigation.path + - navigation.sections + - navigation.top + - navigation.tracking + - toc.follow + +# Extensions +markdown_extensions: + - admonition + - attr_list + - md_in_html + - pymdownx.details + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets: + dedent_subsections: true + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: + alternate_style: true + slugify: !!python/object/apply:pymdownx.slugs.slugify + kwds: + case: lower + - toc: + permalink: true + + +# Plugins +plugins: + - search + - redirects: + redirect_maps: + 'get-started/local-testing.md': 'runtime/api-server.md' + 'get-started/tutorial.md': 'tutorials/index.md' + 'guides/responsible-agents.md': 'safety/index.md' + 'tools/third-party-tools.md': 'tools/third-party/index.md' + 'tools/third-party/openapi-tools.md': 'tools-custom/openapi-tools.md' + 'tools/openapi-tools.md': 'tools-custom/openapi-tools.md' + 'tutorials/ag-ui.md': 'tools/third-party/ag-ui.md' + 'tools/third-party/langchain.md': 'tools/index.md' + 'tools/third-party/crewai.md': 'tools/index.md' + 'get-started/testing.md': 'runtime/api-server.md' + 'tools/authentication.md': 'tools-custom/authentication.md' + 'tools/function-tools.md': 'tools-custom/function-tools.md' + 'tools/confirmation.md': 'tools-custom/confirmation.md' + 'tools/performance.md': 'tools-custom/performance.md' + 'tools/mcp-tools.md': 'tools-custom/mcp-tools.md' + +# Navigation +nav: +<<<<<<< HEAD + - Home: + - index.md + - Build Agents: + - Get Started: + - get-started/index.md + - Python: get-started/python.md + - Go: get-started/go.md + - Java: get-started/java.md + - Build your Agent: + - tutorials/index.md + - Multi-tool agent: get-started/quickstart.md + - Agent team: tutorials/agent-team.md + - Streaming agent: + - get-started/streaming/index.md + - Python: get-started/streaming/quickstart-streaming.md + - Java: get-started/streaming/quickstart-streaming-java.md + - Visual Builder: visual-builder/index.md + - Advanced setup: get-started/installation.md + - Agents: + - agents/index.md + - LLM agents: agents/llm-agents.md + - Workflow agents: + - agents/workflow-agents/index.md + - Sequential agents: agents/workflow-agents/sequential-agents.md + - Loop agents: agents/workflow-agents/loop-agents.md + - Parallel agents: agents/workflow-agents/parallel-agents.md + - Custom agents: agents/custom-agents.md + - Multi-agent systems: agents/multi-agents.md + - Agent Config: agents/config.md + - Models & Authentication: agents/models.md + - Tools for Agents: + - tools/index.md + - Built-in tools: tools/built-in-tools.md + - Gemini API tools: + - Computer use: tools/gemini-api/computer-use.md + - Google Cloud tools: + - Overview: tools/google-cloud-tools.md + - MCP Toolbox for Databases: tools/google-cloud/mcp-toolbox-for-databases.md + - BigQuery Agent Analytics: tools/google-cloud/bigquery-agent-analytics.md + - Code Execution with Agent Engine: tools/google-cloud/code-exec-agent-engine.md + - Third-party tools: + - tools/third-party/index.md + - AgentQL: tools/third-party/agentql.md + - Bright Data: tools/third-party/bright-data.md + - Browserbase: tools/third-party/browserbase.md + - Exa: tools/third-party/exa.md + - Firecrawl: tools/third-party/firecrawl.md + - GitHub: tools/third-party/github.md + - Hugging Face: tools/third-party/hugging-face.md + - Notion: tools/third-party/notion.md + - Tavily: tools/third-party/tavily.md + - Agentic UI (AG-UI): tools/third-party/ag-ui.md + - Custom Tools: + - tools-custom/index.md + - Function tools: + - Overview: tools-custom/function-tools.md + - Tool performance: tools-custom/performance.md + - Action confirmations: tools-custom/confirmation.md + - MCP tools: tools-custom/mcp-tools.md + - OpenAPI tools: tools-custom/openapi-tools.md + - Authentication: tools-custom/authentication.md + - Run Agents: + - Agent Runtime: + - Agent Runtime: runtime/index.md + - Runtime Config: runtime/runconfig.md + - API Server: runtime/api-server.md + - Resume Agents: runtime/resume.md + - Deployment: + - deploy/index.md + - Agent Engine: deploy/agent-engine.md + - Cloud Run: deploy/cloud-run.md + - GKE: deploy/gke.md + - Observability: + - Logging: observability/logging.md + - Cloud Trace: observability/cloud-trace.md + - AgentOps: observability/agentops.md + - Arize AX: observability/arize-ax.md + - Freeplay: observability/freeplay.md + - Monocle: observability/monocle.md + - Phoenix: observability/phoenix.md + - W&B Weave: observability/weave.md + - Evaluation: + - evaluate/index.md + - Criteria: evaluate/criteria.md + - User Simulation: evaluate/user-sim.md + - Safety and Security: + - safety/index.md + - Components: + - Technical Overview: get-started/about.md + - Context: + - context/index.md + - Context caching: context/caching.md + - Context compression: context/compaction.md + - Sessions & Memory: + - sessions/index.md + - Session: sessions/session.md + - State: sessions/state.md + - Memory: sessions/memory.md + - Vertex AI Express Mode: sessions/express-mode.md + - Callbacks: + - callbacks/index.md + - Types of callbacks: callbacks/types-of-callbacks.md + - Callback patterns: callbacks/design-patterns-and-best-practices.md + - Artifacts: + - artifacts/index.md + - Events: + - events/index.md + - Apps: + - apps/index.md + - Plugins: + - plugins/index.md + - Reflect and retry: plugins/reflect-and-retry.md + - MCP: + - mcp/index.md + - A2A Protocol: + - a2a/index.md + - Introduction to A2A: a2a/intro.md + - A2A Quickstart (Exposing): + - Python: a2a/quickstart-exposing.md + - Go: a2a/quickstart-exposing-go.md + - A2A Quickstart (Consuming): + - Python: a2a/quickstart-consuming.md + - Go: a2a/quickstart-consuming-go.md + - Bidi-streaming (live): + - streaming/index.md + - Custom Audio Bidi-streaming app sample (WebSockets): streaming/custom-streaming-ws.md + - Bidi-streaming development guide series: streaming/dev-guide/part1.md + - Streaming Tools: streaming/streaming-tools.md + - Configurating Bidi-streaming behaviour: streaming/configuration.md + - Grounding: + - Understanding Google Search Grounding: grounding/google_search_grounding.md + - Understanding Vertex AI Search Grounding: grounding/vertex_ai_search_grounding.md + - Reference: + - API Reference: + - api-reference/index.md + - Python ADK: api-reference/python/index.html + - Go ADK: https://pkg.go.dev/google.golang.org/adk" target="_blank + - Java ADK: api-reference/java/index.html + - CLI Reference: api-reference/cli/index.html + - Agent Config reference: api-reference/agentconfig/index.html + - REST API: api-reference/rest/index.md + - Community Resources: community.md + - Contributing Guide: contributing-guide.md +======= + - Home: index.md + - Get started: + - get-started/index.md + - Python: get-started/python.md + - Java: get-started/java.md + - Build your agent: + - tutorials/index.md + - Multi-tool agent: get-started/quickstart.md + - Agent team: tutorials/agent-team.md + - Streaming agent: + - get-started/streaming/index.md + - Python: get-started/streaming/quickstart-streaming.md + - Java: get-started/streaming/quickstart-streaming-java.md + - Testing: get-started/testing.md + - Code samples: https://github.com/google/adk-samples + - Advanced setup: get-started/installation.md + - Technical overview: get-started/about.md + - Agents: + - agents/index.md + - LLM agents: agents/llm-agents.md + - Workflow agents: + - agents/workflow-agents/index.md + - Sequential agents: agents/workflow-agents/sequential-agents.md + - Loop agents: agents/workflow-agents/loop-agents.md + - Parallel agents: agents/workflow-agents/parallel-agents.md + - Custom agents: agents/custom-agents.md + - Multi-agent systems: agents/multi-agents.md + - Agent Config: agents/config.md + - Models & Authentication: agents/models.md + - Tools for Agents: + - tools/index.md + - Built-in tools: tools/built-in-tools.md + - Google Cloud tools: tools/google-cloud-tools.md + - Third party tools: tools/third-party-tools.md + - OpenAPI tools: tools/openapi-tools.md + - Custom Tools: + - tools-custom/index.md + - Function tools: + - Overview: tools/function-tools.md + - Best practices: tools/best-practices.md + - Tool performance: tools/performance.md + - Action confirmations: tools/confirmation.md + - MCP tools: tools/mcp-tools.md + - Authentication: tools/authentication.md + - Running Agents: + - Agent Runtime: runtime/index.md + - Runtime Config: runtime/runconfig.md + - Resume Agents: runtime/resume.md + - Deploy: + - deploy/index.md + - Agent Engine: deploy/agent-engine.md + - Cloud Run: deploy/cloud-run.md + - GKE: deploy/gke.md + - Sessions & Memory: + - sessions/index.md + - Session: sessions/session.md + - State: sessions/state.md + - Memory: sessions/memory.md + - Vertex AI Express Mode: sessions/express-mode.md + - Callbacks: + - callbacks/index.md + - Types of callbacks: callbacks/types-of-callbacks.md + - Callback patterns: callbacks/design-patterns-and-best-practices.md + - Artifacts: + - artifacts/index.md + - Events: + - events/index.md + - Context: + - context/index.md + - Observability: + - Logging: observability/logging.md + - Cloud Trace: observability/cloud-trace.md + - AgentOps: observability/agentops.md + - Arize AX: observability/arize-ax.md + - Phoenix: observability/phoenix.md + - W&B Weave: observability/weave.md + - Evaluate: + - evaluate/index.md + - Criteria: evaluate/criteria.md + - MCP: + - mcp/index.md + - Plugins: + - plugins/index.md + - Bidi-streaming (live): + - streaming/index.md + - Custom Audio Bidi-streaming app sample (SSE): streaming/custom-streaming.md + - Custom Audio Bidi-streaming app sample (WebSockets): streaming/custom-streaming-ws.md + - Bidi-streaming development guide series: streaming/dev-guide/part1.md + - Streaming Tools: streaming/streaming-tools.md + - Configurating Bidi-streaming behaviour: streaming/configuration.md + - Google ADK + Vertex AI Live API (blog post): https://medium.com/google-cloud/google-adk-vertex-ai-live-api-125238982d5e + - Grounding: + - Understanding Google Search Grounding: grounding/google_search_grounding.md + - Understanding Vertex AI Search Grounding: grounding/vertex_ai_search_grounding.md + - Safety and Security: safety/index.md + - A2A Protocol: + - a2a/index.md + - Introduction to A2A: a2a/intro.md + - A2A Quickstart (Exposing): a2a/quickstart-exposing.md + - A2A Quickstart (Consuming): a2a/quickstart-consuming.md + - A2A Protocol Documentation: https://a2a-protocol.org + - Community Resources: community.md + - Contributing Guide: contributing-guide.md + - API Reference: + - api-reference/index.md + - Python ADK: api-reference/python/index.html + - Java ADK: api-reference/java/index.html + - CLI Reference: api-reference/cli/index.html + - Agent Config reference: api-reference/agentconfig/index.html + - REST API: api-reference/rest/index.md +>>>>>>> 48a18a8 (docs: add best-practices.md to navigation) diff --git a/mkdocs_fixed.yml b/mkdocs_fixed.yml new file mode 100644 index 000000000..f96475ec7 --- /dev/null +++ b/mkdocs_fixed.yml @@ -0,0 +1,138 @@ +# Project information +site_name: Agent Development Kit +site_url: https://google.github.io/adk-docs +site_description: >- + Build powerful multi-agent systems with Agent Development Kit +site_dir: site +exclude_docs: + api-reference/java/legal/* + +# Repository +repo_name: adk-docs +repo_url: https://github.com/google/adk-docs +edit_uri: edit/main/docs/ + +# Copyright +copyright: Copyright Google 2025  |  Terms  |  Privacy  |  Manage cookies + +# Custom CSS +extra_css: + - stylesheets/custom.css + - stylesheets/language-tags.css + +extra: + first_repo_url: https://github.com/google/adk-python + first_repo_name: adk-python + first_repo_icon: fontawesome/brands/github + second_repo_url: https://github.com/google/adk-go + second_repo_name: adk-go + second_repo_icon: fontawesome/brands/github + third_repo_url: https://github.com/google/adk-java + third_repo_name: adk-java + third_repo_icon: fontawesome/brands/github + analytics: + provider: google + property: G-DKHZS27PHP + consent: + title: Cookie consent + description: >- + We use cookies to recognize repeated visits and preferences, + as well as to measure the effectiveness of our documentation and + whether users find the information they need. With your consent, + you're helping us to make our documentation better. + +# Configuration +theme: + name: material + font: + text: Google Sans + code: Roboto Mono + logo: assets/agent-development-kit.png + favicon: assets/agent-development-kit.png + icon: + repo: fontawesome/brands/github + custom_dir: overrides + palette: + - scheme: default + primary: white + accent: white + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - scheme: slate + primary: white + accent: white + toggle: + icon: material/brightness-4 + name: Switch to light mode + features: + - content.action.edit + - content.action.view + - content.code.annotate + - content.code.copy + - content.code.select + - content.tabs.link + - content.tooltips + - navigation.footer + - navigation.indexes + - navigation.instant + - navigation.instant.progress + - navigation.path + - navigation.sections + - navigation.top + - navigation.tracking + - toc.follow + +# Extensions +markdown_extensions: + - admonition + - attr_list + - md_in_html + - pymdownx.details + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets: + dedent_subsections: true + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: + alternate_style: true + slugify: !!python/object/apply:pymdownx.slugs.slugify + kwds: + case: lower + - toc: + permalink: true + + +# Plugins +plugins: + - search + - redirects: + redirect_maps: + 'get-started/local-testing.md': 'runtime/api-server.md' + 'get-started/tutorial.md': 'tutorials/index.md' + 'guides/responsible-agents.md': 'safety/index.md' + 'tools/third-party-tools.md': 'tools/third-party/index.md' + 'tools/third-party/openapi-tools.md': 'tools-custom/openapi-tools.md' + 'tools/openapi-tools.md': 'tools-custom/openapi-tools.md' + 'tutorials/ag-ui.md': 'tools/third-party/ag-ui.md' + 'tools/third-party/langchain.md': 'tools/index.md' + 'tools/third-party/crewai.md': 'tools/index.md' + 'get-started/testing.md': 'runtime/api-server.md' + 'tools/authentication.md': 'tools-custom/authentication.md' + 'tools/function-tools.md': 'tools-custom/function-tools.md' + 'tools/confirmation.md': 'tools-custom/confirmation.md' + 'tools/performance.md': 'tools-custom/performance.md' + 'tools/mcp-tools.md': 'tools-custom/mcp-tools.md' + +# Navigation +nav: