Port AI Assistant

The Port AI Assistant is the fastest way to start using AI with Port - no configuration required. Available through the button, it provides instant, intelligent answers about your software catalog, actions, and Port's capabilities.

What is the Port AI Assistant?

The Port AI Assistant is an out-of-the-box chat interface that:

• Requires no setup: Start asking questions immediately without defining agents or configurations.
• Always accessible: Available through the button whenever you have access to Port AI.
• Comprehensive knowledge: Understands your catalog, actions, and Port documentation.
• Flexible chat modes: Switch between ask, plan, and build modes to explore data, analyze larger changes, or make scoped edits.
• Configurable tool approval: Control whether each tool runs automatically, pauses for your approval, or is disabled entirely.
• Fastest experience: Get answers without the customization overhead of AI Agents.

Built on Port AI, the assistant uses Port AI's developer tools and Port documentation through a dedicated MCP tool. By default, ask mode limits the assistant to read-only tools. In plan and build modes, write tools are available and governed by your per-tool approval settings.

How to use the Port AI Assistant

The Port AI Assistant is available through the button in the Port interface, or from Port AI in the navigation. Simply click either to open the chat interface and start asking questions.

Once you ask a question, the assistant analyzes your request and uses the appropriate tools to provide a comprehensive response.

After processing your request, you'll receive a detailed answer along with any relevant actions or next steps.

Chat modes

The Port AI side chat supports three modes that control which tools the assistant can use. Select a mode from the chat input area before you send a message.

Mode	Best for	Tool access
Ask	Exploring your data and configuration without making edits	Read-only Port tools (get_*, list_*, search_*, and similar) plus run_action and trigger_auto_discovery. Write tools never appear, even if you set them to automate.
Plan	Bigger changes that require deeper analysis across multiple components	Full tool set (minus tools you have disabled), including plan-specific tools for multi-step analysis. Approval and automate settings apply per tool.
Build	Scoped changes in your environment	Full tool set (minus tools you have disabled). Approval and automate settings apply per tool.

When to use each mode

Ask is the safest starting point. Use it when you want to understand your catalog, investigate a problem, or learn how Port is configured without risking unintended changes. Examples include "Who owns the payment service?" or "Which services are failing security checks?"

Plan is for complex work that spans multiple parts of your environment. Use it when you need the assistant to analyze dependencies, compare options, or draft a multi-step approach before anything is changed. Examples include "Design a rollout plan for migrating our auth service" or "What would we need to change to add a new scorecard across all microservices?"

Build is for focused, scoped changes you are ready to execute. Use it when you know what you want to change and the assistant should take action in your environment. Examples include "Create an incident for the payment service outage" or "Update the owner on the checkout service."

Start with ask

If you are unsure which mode to use, start in ask mode. You can always switch to plan or build once you understand the scope of the work.

Chat mode vs. invocation reasoning

Chat plan mode is different from the reasoning plan shown in AI invocation records. Chat plan mode controls which tools are available during a conversation. The invocation reasoning plan is a log of how Port AI decided to approach a specific request.

Tool approval settings

Port AI uses two separate mechanisms to control how tools run. In the side chat, per-tool approval settings are what matter most.

Layer	What it controls	Where it lives
Per-tool approval settings	Whether a specific tool pauses for your confirmation before it runs	Your user preferences, configured in the chat + menu
Execution mode (Automatic / Approval Required)	API and agent-level behavior, mainly how run_action runs Port self-service actions	Agent entity or API request body

The side chat does not send an executionMode in the request, so your saved per-tool settings drive the pause-and-approve flow. Learn more in API interaction.

The three per-tool options

Each tool can be configured in one of three ways:

1. Approval - the model can use the tool, but execution pauses until you approve, edit the arguments, or reject the call.
2. Automate (automatic) - the tool runs without pausing for confirmation.
3. Disabled - the tool is removed from the model's tool list. The model never sees it.

Default behavior when you have not customized a tool:

• Port read-only tools (get_*, list_*, and similar, plus run_action): Automate.
• Port write tools (create, update, delete, and similar): Approval.
• External MCP tools: Approval.

Where to configure tool approval

In the side chat, click the + button next to the input field, then open Port Tools or Connectors and select a connector.

For each tool you can:

• Toggle the tool on or off (disabled tools are not available to the model).
• Switch between Approval and Automate to control whether the tool pauses before running.
• Use the Enable all master toggle to enable or disable all tools at once (shown as N/total).

Settings are per user, persisted server-side, and synced when tools or MCP servers change.

Agent chat is read-only

When you are chatting with a specific AI Agent, tool approval controls are read-only. You can see what the agent is allowed to use, but you cannot change your personal approval preferences from that view.

What happens at runtime

When you send a message in the side chat:

1. The backend loads your saved preferences and builds the tool list (disabled tools are filtered out).
2. The model selects tools for your request.
3. For each tool call, the backend checks whether approval is required:
   • An explicit approval setting pauses execution.
   • An explicit automatic setting runs the tool immediately.
   • Otherwise, read-only tools run automatically and write tools require approval.
4. If any tool needs approval, the stream pauses and a tool approval card appears showing how many tools were requested.
5. You approve, decline, or edit the arguments, and the chat resumes.

Tools set to Automate in the same batch still run immediately. Only tools in Approval mode block the turn.

How chat mode interacts with tool approval

Chat mode controls which tools exist, not whether they pause:

• Ask restricts tools to read-only operations. Write tools never appear, regardless of your automate settings.
• Plan and Build expose the full tool set (minus your disabled tools). Your per-tool approval and automate settings apply.

In short: ask enforces safety by limiting tools, while plan and build expose the full tool set with your approval preferences.

Using AI agents in the assistant

While the Port AI Assistant provides comprehensive out-of-the-box capabilities, you can also select specific AI Agents to leverage their specialized expertise and custom configurations directly from the chat interface.

Selecting an agent

To select an agent, click the + button next to the input field:

This opens the categories menu where you can browse different options:

From the categories menu, select the agents option to view all your active agents:

Once you select an agent, it will be indicated in the chat interface, and your conversation will use that agent's specialized capabilities:

Switching between agents

You can switch between different agents at any time during your conversation. Simply click the + button again to select a different agent or return to the default Port AI Assistant. This flexibility allows you to leverage different specialized agents as your needs change throughout a conversation.

When to use specific agents

Consider selecting a specific agent when:

• Domain expertise needed: You have a question that requires specialized knowledge (e.g., security, compliance, deployment workflows).
• Custom tools: The agent has access to custom tools or integrations not available in the default assistant.
• Specific prompts: The agent is configured with specific instructions or context for your team's workflows.
• Consistent behavior: You want responses aligned with a particular agent's configuration and personality.

For general questions about your catalog, Port features, or exploratory queries, the default Port AI Assistant provides the fastest and most flexible experience.

Example Questions

The Port AI Assistant can help with a wide variety of questions out of the box:

Service Ownership & Information

• "Who owns the payment service?"
• "What services does the platform team own?"
• "Show me all microservices owned by the Backend team"
• "What is the checkout service about?"
• "What are the dependencies of the OrderProcessing service?"

Deployment & Operations

• "How do I deploy the auth service to production?"
• "When was the last successful deployment of the payment service?"
• "Show me failed deployments from last week"
• "What's deployed in production today?"
• "What's the deployment frequency of team X?"

Quality & Compliance

• "Which services are failing security checks?"
• "Give me a weekly summary of open bugs"
• "What's preventing the InventoryService from reaching Gold level?"
• "Show me services with high bug counts"
• "What's our overall security score?"

Incidents & Monitoring

• "Show me active incidents"
• "Which services had an incident in the last 30 days?"
• "Who is on call for the payment service?"
• "What is our mean time to resolution?"

Tasks & Workflow

• "What tasks are assigned to me?"
• "Show me my urgent Jira tickets"
• "How many issues were closed by the frontend team this month?"
• "What PRs are waiting for my review?"

Port Usage & Help

• "How do I create a new blueprint?"
• "What's the best way to set up scorecards?"
• "How can I trigger an action via API?"
• "Show me how to configure RBAC permissions"

External Tools (via MCP Connectors)

If your admin has configured MCP Connectors, you can also query external tools:

• "Search Notion for our API authentication documentation"
• "Find the deployment runbook in Confluence"
• "Show me open Jira tickets for the payments service"
• "What's in the architecture decisions page?"

Security & Permissions

The Port AI Assistant respects your organization's security controls:

• RBAC compliance: Only accesses data you have permissions to view.
• Chat mode guardrails: Ask mode limits the assistant to read-only tools so you can explore without edits.
• Per-tool approval: Configure each tool to require approval, run automatically, or be disabled entirely. Write tools default to requiring approval.
• Audit trail: All interactions are logged as AI invocations.
• Access control: Access to the Port AI Assistant is controlled through the _ai_invocation blueprint permissions. Learn more about controlling access to Port AI.

For comprehensive security information, see AI Security and Data Controls.

Frequently Asked Questions

What display modes does the Port AI Assistant support? (Click to expand)

Port AI supports three display modes. Switch between them from the layout menu in the chat header.

• Sidebar - chat opens in a panel beside your current page so you can keep working in context.
• Floating - a draggable, resizable window you can place anywhere on screen. Port remembers position and size between sessions.
• Full page - a dedicated chat experience at /chat (or /chat/:conversationId for a specific conversation). Open it by clicking Port AI in the navigation, or switch via the layout menu. Best for longer Plan or Build sessions.

Do I need to configure anything to use the Port AI Assistant? (Click to expand)

No! The Port AI Assistant works out of the box. As soon as you have access to Port AI, you can start asking questions through the button. No setup, no configuration, no agent definitions required.

Can the Port AI Assistant run actions on my behalf? (Click to expand)

Yes, in plan or build mode the assistant can run actions and use write tools on your behalf. How each tool behaves depends on your tool approval settings:

• Tools set to Approval pause before running so you can review, edit arguments, or decline.
• Tools set to Automate run immediately without pausing.
• Tools set to Disabled are not available to the model at all.

In ask mode, only read-only tools are available, so the assistant cannot make changes to your environment. This keeps exploration safe while still letting you query your catalog and documentation.

What are ask, plan, and build modes? (Click to expand)

These modes control which tools the side chat can use:

• Ask - explore your data and configuration without edits (read-only tools only).
• Plan - analyze bigger changes that span multiple components before executing them.
• Build - make scoped changes in your environment.

See Chat modes for details and examples of when to use each mode.

How do I control which tools require approval? (Click to expand)

Click the + button in the side chat, open Port Tools or Connectors, and configure each tool as Approval, Automate, or Disabled. Settings are saved per user and apply to future conversations.

See Tool approval settings for defaults, runtime behavior, and how chat modes interact with approval settings.

What's the difference between Port AI Assistant and AI Agents? (Click to expand)

Port AI Assistant is designed for:

• Immediate use with zero configuration
• General-purpose questions across your entire catalog
• Interactive exploration and ad-hoc queries
• Human interaction and learning

AI Agents are designed for:

• Domain-specific expertise and workflows
• Machine-to-machine communication
• Autonomous operations and automations
• Customized behavior for specific use cases

The assistant is the fastest way to get started, while agents provide advanced customization for specialized needs.

What data can the Port AI Assistant access? (Click to expand)

The assistant uses Port AI's developer tools, which include read-only access to your data model, entities, scorecards, self-service actions, and Port documentation. All data access respects your organization's RBAC policies - you can only access data you have permissions to view. Learn more about Port AI's security controls.

Can the Port AI Assistant help me learn how to use Port? (Click to expand)

Yes! The assistant has comprehensive knowledge of Port's documentation and can help you:

• Understand how features work
• Learn best practices
• Troubleshoot issues
• Discover new capabilities

Try asking questions like "How do I create a blueprint?" or "What's the best way to set up scorecards?"

When should I use the Port AI Assistant vs other AI interfaces? (Click to expand)

Use the Port AI Assistant when you want immediate AI access with zero configuration. It's perfect for quick questions, exploratory queries, learning Port, and ad-hoc analysis.

Use AI Chat Widgets (with AI Agents) when you need customized AI experiences embedded in dashboards - configure prompts, conversation starters, and specific tool selections for team-specific workflows.

Use AI Agents for domain-specific expertise, machine-to-machine communication, and autonomous operations that require advanced customization.

Can I select a specific AI Agent in the Port AI Assistant? (Click to expand)

Yes! You can select any of your active AI Agents directly from the Port AI Assistant by clicking the + button next to the input field. This allows you to leverage specialized agents with domain-specific expertise, custom tools, or specific configurations.

You can also switch between different agents at any time during your conversation, giving you the flexibility to use the right agent for each part of your workflow. Up to 50 agents are displayed in the selector, and you can use the search function to quickly find a specific agent if you have more.

For more details, see the Using AI Agents in the Assistant section above.

Are there usage limits for the Port AI Assistant? (Click to expand)

Yes, the Port AI Assistant uses the same usage limits as Port AI. These limits are at the organization level and include per-minute rate limits and monthly quotas.

Monitor your usage through AI invocations in your Port catalog.