AI docs updates

[Matanga1-2]

User description

Description

Updates AI interfaces documentation: all features moved to open beta, added Haiku-4.5 model support, and updated MCP tools.

Added docs pages

• AI Documentation Maintenance Guide (/docs/ai-interfaces/AGENTS.md)

Updated docs pages

• AI Interfaces Overview (/docs/ai-interfaces/overview.md)
• AI Agents Overview (/docs/ai-interfaces/ai-agents/overview.md)
• Build an AI Agent (/docs/ai-interfaces/ai-agents/build-an-ai-agent.md)
• Interact with AI Agents (/docs/ai-interfaces/ai-agents/interact-with-ai-agents.md)
• Port AI API Interaction (/docs/ai-interfaces/port-ai/api-interaction.md)
• LLM Provider Management Overview (/docs/ai-interfaces/port-ai/llm-providers-management/overview.md)
• Security and Data Controls (/docs/ai-interfaces/port-ai/security-and-data-controls.md)
• Port MCP Server Overview (/docs/ai-interfaces/port-mcp-server/overview-and-installation.md)
• Slack App (/docs/ai-interfaces/slack-app.md)
• MCP Tools Data (/src/data/mcpTools.js)

Key changes:

• All AI features now documented as open beta
• Added haiku-4.5 model for Anthropic and AWS Bedrock
• Added count_entities tool and renamed search_port_docs_sources to search_port_sources

---

PR Type

Documentation, Enhancement

---

Description

• Transition all AI features from closed beta to open beta status

• Add count_entities MCP tool and rename documentation search tool

• Introduce context-aware AI Chat Widget with automatic page/entity understanding

• Add Feature Support Matrix table showing capabilities across AI interfaces

• Increase monthly AI invocation quota from 20 to 50

• Remove limited availability restrictions on LLM provider configuration

• Create comprehensive AI Documentation Maintenance Guide for agents

---

Diagram Walkthrough

flowchart LR
  A["AI Features Status"] -->|"Update to Open Beta"| B["All Interfaces"]
  C["MCP Tools"] -->|"Add count_entities"| D["Enhanced Capabilities"]
  E["Chat Widget"] -->|"Add Context Awareness"| F["Improved UX"]
  G["Documentation"] -->|"Add Support Matrix"| H["Feature Clarity"]
  I["Quota"] -->|"Increase to 50"| J["Higher Limits"]
  K["LLM Providers"] -->|"Remove Restrictions"| L["Full Availability"]

Loading

File Walkthrough

	Relevant files
Enhancement	1 files mcpTools.js Add count_entities tool and rename documentation search    +8/-7
Documentation	15 files AGENTS.md Create comprehensive AI documentation maintenance guide    +148/-0  overview.md Update AI Agents to open beta status                                          +2/-4      build-an-ai-agent.md Replace closed beta notice with open beta component            +4/-5      interact-with-ai-agents.md Add context awareness feature and update beta status          +5/-4      ai-chat-widget.md Document context-aware functionality with examples              +25/-0    overview.md Add Feature Support Matrix and update beta statuses            +22/-5    api-interaction.md Update quota to 50 and add count_entities to examples        +18/-16  overview.md Update monthly quota documentation to 50 invocations          +2/-2      security-and-data-controls.md Remove closed beta references from performance section      +2/-2      overview.md Remove limited availability restrictions and add Haiku model +11/-14  setup-and-configuration.md Add UI configuration instructions for LLM providers            +25/-0    overview-and-installation.md Update MCP Server and AI Agents beta status alignment        +2/-2      slack-app.md Update Slack app to open beta and clarify AI capabilities +5/-11    _mcp-installation.md Remove outdated warnings about authentication and VSCode issues +0/-14    send-slack-message-to-user.md Remove AI program access requirement from prerequisites    +0/-4

---

[aws-amplify-eu-west-1]

This pull request is automatically being deployed by Amplify Hosting (learn more).

Access this pull request here: https://pr-2989.d2ngvl90zqbob8.amplifyapp.com

[qodo-merge-pro]

PR Compliance Guide 🔍

(Compliance updated until commit 4cb5c31)

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: No runtime changes: The PR only updates documentation and static tool metadata; no new critical actions or runtime logic were added in the shown diff to assess audit trail coverage. Referred Code { name: 'count_entities', description: 'Count entities matching specified filters without retrieving entity data. Returns only the count number for efficient queries like "how many services are in production?"', apiReference: '/api-reference/get-all-entities-of-a-blueprint', roles: ['developer', 'builder'] }, Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Docs only changes: The changes introduce examples and quota values but add no executable error handling paths in the diff, so robustness cannot be validated from documentation updates alone. Referred Code "remainingTimeMs": 903 }, "monthlyQuotaUsage": { "monthlyLimit": 50, "remainingQuota": 49, "month": "2025-09", "remainingTimeMs": 1766899073 } Learn more about managing compliance generic rules or creating your own custom rules

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

---

Previous compliance checks

Compliance check up to commit 2f17a87

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: No runtime logging: The PR only updates documentation and static tool metadata without adding or modifying any critical action paths, so audit logging cannot be verified from this diff. Referred Code { name: 'count_entities', description: 'Count entities matching specified filters without retrieving entity data. Returns only the count number for efficient queries like "how many services are in production?"', apiReference: '/api-reference/get-all-entities-of-a-blueprint', roles: ['developer', 'builder'] },
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: No error paths: Added examples and documentation (including JSON snippets) do not implement executable error handling, so robustness cannot be assessed from this diff. Referred Code - These limits reset hourly. ### Monthly Quota - **Default quota**: 50 AI invocations per month. - Each interaction with Port AI counts as one request against your quota. - Quota resets monthly.
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Input validation N/A: Changes introduce new tool names and regex usage in docs, but no input handling code is added; validation of external inputs cannot be assessed from this diff. Referred Code { name: 'count_entities', description: 'Count entities matching specified filters without retrieving entity data. Returns only the count number for efficient queries like "how many services are in production?"', apiReference: '/api-reference/get-all-entities-of-a-blueprint', roles: ['developer', 'builder'] },

[qodo-merge-pro]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Adopt a structured data approach for documentation Replace the natural language AI maintenance guide (AGENTS.md) with structured data files (e.g., YAML/JSON). This would create a single source of truth for documentation variables like feature status and supported models, making the system more robust and less prone to breaking from minor changes. Examples: docs/ai-interfaces/AGENTS.md [1-148] --- sidebar_class_name: hidden title: AGENTS.md - AI Documentation Maintenance Guide --- # AGENTS.md - AI Documentation Maintenance Guide This is a hidden guide for AI agents to understand how to maintain and update the AI interfaces documentation in Port Docs. ## File Structure ... (clipped 138 lines) Solution Walkthrough: Before: // file: docs/ai-interfaces/AGENTS.md # AGENTS.md - AI Documentation Maintenance Guide This is a hidden guide for AI agents... ## Common Tasks ### Update MCP Tools To add, update, or remove MCP tools: 1. **Update the file**: `src/data/mcpTools.js` ... ### Set Feature Beta Status When asked to mark a feature as **open beta**... use the `BetaFeatureNotice` component: ```markdown import BetaFeatureNotice from '/docs/generalTemplates/_beta_feature_notice.md' <BetaFeatureNotice id="ai-form" /> #### After: ```markdown # A structured data file would define documentation variables # file: src/data/features.yaml ai_agents: status: open_beta notice_id: ai-form slack_app: status: open_beta notice_id: ai-form # ... other features # The AGENTS.md file would be removed. # Documentation pages would then consume this structured data, # for example, via a component that renders the correct notice # based on the feature's status in the YAML file. # This creates a single source of truth. Suggestion importance[1-10]: 9 __ Why: The suggestion correctly identifies the fragility of using a natural language markdown file (AGENTS.md) as a maintenance guide for an AI and proposes a more robust, scalable, and standard architectural pattern using structured data as a single source of truth.	High
Enhancement	Improve clarity of configuration instructions Reorder and clarify the instructions for configuring LLM providers to improve logical flow and user understanding. docs/ai-interfaces/port-ai/llm-providers-management/overview.md [140-150] <summary><b>How do I configure my own LLM providers? (Click to expand)</b></summary> To configure your own LLM providers: -1. **Configure your providers** - Set up your preferred LLM providers using the [Create or connect an LLM provider](/api-reference/create-or-connect-an-llm-provider) API endpoint. -2. **Select defaults** - Once providers are configured, you can view and select default providers and models through the UI (**Builder** → **Organization Settings** → **AI** tab) or via the [Change default LLM provider and model](/api-reference/change-default-llm-provider-and-model) API. +1. **Add a custom provider** - Use the [Create or connect an LLM provider](/api-reference/create-or-connect-an-llm-provider) API endpoint to add a new provider configuration. +2. **Select the default provider** - Once configured, you can select the default provider and model for your organization. This can be done in two ways: + - **UI**: Go to **Builder** → **Organization Settings** → **AI** tab to view and select defaults. + - **API**: Use the [Change default LLM provider and model](/api-reference/change-default-llm-provider-and-model) API. :::info UI vs API -- **Viewing and selecting defaults**: Available in both UI and API. -- **Adding new custom providers**: Requires the API. +- **Adding new custom providers**: Requires using the API. +- **Viewing and selecting defaults**: Can be done through both the UI and the API. ::: Apply / Chat Suggestion importance[1-10]: 6 __ Why: The suggestion improves the logical flow and clarity of the LLM provider configuration steps, making the documentation easier for users to follow.	Low
	Complete the documentation update instructions Complete the instruction for updating the main documentation file in AGENTS.md by specifying the action to take. docs/ai-interfaces/AGENTS.md [63-65] 2. **Update the main documentation file**: Edit `docs/ai-interfaces/port-ai/llm-providers-management/overview.md`: + - Add the new model to the list under the correct provider in the "Supported LLMs and Providers" section. 3. **Note about API reference files**: The API reference files in `docs/api-reference/` (like `general-purpose-ai-interactions.api.mdx`, `invoke-a-specific-agent.api.mdx`, etc.) are auto-generated from OpenAPI specifications. These will be updated automatically when the backend API is updated. You don't need to manually edit these files. Apply / Chat Suggestion importance[1-10]: 5 __ Why: The suggestion correctly identifies an incomplete instruction in the new AGENTS.md guide and provides a clear, actionable step to complete it, improving the document's clarity.	Low
Organization best practice	Use sentence case for heading Use sentence case for headers; change "Context Awareness" to "Context awareness" to follow the docs style guide. docs/ai-interfaces/ai-chat-widget.md [86] -### Context Awareness +### Context awareness Apply / Chat Suggestion importance[1-10]: 6 __ Why: Relevant best practice - Pattern 2: Enforce sentence case in headings.	Low
	Standardize collapsible summary casing Use consistent "(click to expand)" casing and placement in collapsible summaries. Change "Click" to lowercase to match the standardized pattern. docs/ai-interfaces/ai-agents/build-an-ai-agent.md [117-121] <details> -<summary><b>I don't see an option to add an AI agent (Click to expand)</b></summary> +<summary><b>I don't see an option to add an AI agent (click to expand)</b></summary> Make sure you have [access to the AI agents feature](/ai-interfaces/ai-agents/overview#access-to-the-feature). If you believe you should have access, please contact our support. </details> Apply / Chat Suggestion importance[1-10]: 5 __ Why: Relevant best practice - Pattern 1: Standardize collapsible details with bold titles and "(click to expand)".	Low
More