I don't see an option to add an AI agent

Make sure you have access to the AI agents feature. If you believe you should have access, please contact our support.

My agent can't access the data I need - what's wrong?

Check that you've configured the correct data access tools for your agent. Ensure you've added the appropriate Port AI tools to give your agent access to Port data. As Port AI agents act based on their permissions, ensure the right access to your resources.

How can I make sure the agent doesn't run actions without approval?

When configuring actions for your agent, set the approval mode to "manual" instead of "automatic". This ensures the agent creates draft actions that require your review before execution. For details, see Port AI tool execution modes.

My agent isn't performing well - how do I improve it?

Review agent interactions through AI invocations. Refine your prompt based on common issues you identify. Ensure your agent has access to the right tools for its domain. Check our Context Engineering guide for prompt optimization. Start with simple prompts and iterate based on actual usage patterns.

Users can see the agent but get an error when invoking it

The most common cause is missing permissions on the _ai_invocation blueprint. Users need Read, Register, and Update permissions on this blueprint to invoke any Port AI feature. To grant access: Go to Builder → Data model. Find the _ai_invocation blueprint. Click the Permissions tab. Grant Read, Register, and Update permissions to the relevant roles or teams. See Controlling access to Port AI for full details.

My agent is active but doesn't appear in the AI chat for my users

Two things must both be true for an agent to be visible and invokable: The agent's Status must be set to Active. The user must have Read, Register, and Update permissions on the _ai_invocation blueprint. If both conditions are met and the agent still doesn't appear, check whether the agent has team ownership configured. Team-owned agents are only visible to members of that team.

I configured actions for my agent but it won't execute them

Check two things: Action permissions: The agent executes actions on behalf of the invoking user. If the user doesn't have permission to run the action directly, the agent cannot run it either. Execution mode: If the execution mode is set to manual (approval required), the agent creates a draft run that waits for approval rather than executing immediately. Switch to automatic if you want immediate execution without approval.

Build agents

Built on Port AI

AI Agents are built on top of Port AI and leverage its underlying capabilities for data access, security, and execution. This guide focuses on agent-specific building techniques.

Getting started

Building an AI agent in Port involves several key steps.
Let's walk through the process of creating an agent that can assist your developers with finding information and completing tasks.

Create a new AI agent

To create a new agent, head to the AI Agents catalog page (this page will be created for you when you activate the feature).

Click on the "New AI Agent" button and fill the form with the agent details.

We recommend following the steps below.

Step 1: Define your agent's purpose

The first step in building an AI agent is deciding on its purpose.
Here we will determine whether the agent will:

Answer questions about your development environment.
Help run actions and complete tasks.

We recommend starting with a simple use case that a junior assistant with access to your data could assist with.

For inspiration, check our AI agents guides.

Step 2: Configure data access tools

Configure which data tools your agent can access. Configure access to Port data through Port AI tools. Available tools include data query tools for retrieving information from your catalog, as well as running self-service actions.

Step 3: Configure actions access

Actions are executed through the run_action tool, which dynamically handles all available actions in your Port instance. When you configure an action for the agent, it becomes available as a tool the agent can use.

Provide action access in one of these ways:

Allowed Actions input (recommended) - Add the specific actions this agent can execute in the Allowed Actions input in the AI agent form.
Advanced mode (regex) - Switch to Advanced mode (regex) if you need full control over the tools list (for example, mixed custom patterns). In this mode, you can add action tools using patterns such as run_{action_identifier}.
Choose the execution mode (automatic or approval-required) for the selected actions.

To find an action identifier, open the self-service page and copy the action identifier.

While the underlying implementation uses the unified run_action tool, you can still reference specific actions with run_{action_identifier} for clarity and backward compatibility.

For details on manual approval vs automatic execution patterns, see Port AI tool execution modes.

Step 4: Configure MCP server access

You can give your agent access to tools from external systems through MCP connectors. This lets the agent query or act on data that does not live in your Port catalog (for example, Notion, Linear, or Slack).

MCP connectors configured on the agent entity work in interactive chat when the user connects to each server. They do not run in automations or AI_AGENT workflow nodes. For workflow external MCP, see use MCP connectors in workflows.

In the MCP servers relation field, select which MCP servers this agent can use.
In the Allowed MCP tools section, choose which tools the agent may use for each selected server. You can toggle individual tools, or use All / None for a server.
Save is available only when every selected server is connected and has at least one tool enabled.

For connector setup and authentication, see MCP connectors.

Step 5: Define the prompt

The prompt is your main tool for influencing your agent's success. You will likely iterate on it as you observe how the agent responds to different queries.

For comprehensive guidance on crafting effective prompts, see Context Engineering. This covers prompt design principles, examples, and best practices for creating prompts that leverage your organization's specific data and terminology.

Edit Prompt dialog with markdown editor preview

Step 6: Activate your agent

When you feel your agent is ready:

Set its status to "Active".
Start interacting with it through the available interfaces.

Step 7: Configure user permissions

Creating and activating an agent is not enough for your users to interact with it. Access to Port AI features is controlled separately through the _ai_invocation blueprint's permissions.

Permissions required

Users need the Read, Register, and Update permissions on the _ai_invocation blueprint to invoke and interact with any Port AI feature, including your newly created agent.

Learn how to configure access to Port AI →

Evaluating your agent performance

Continuous evaluation and improvement are essential for maintaining effective AI agents. We recommend implementing a regular review process:

Weekly reviews: Set aside time each week to review agent interactions
Identify patterns: Look for recurring issues or misunderstandings in how the agent interprets queries
Refine the prompt: Update your agent's prompt based on your findings to address common issues

For details on how to analyze agent behavior and view execution plans, see AI invocations.

Examples

For comprehensive examples of AI agents in action, see our practical implementation guides:

Infrastructure & Operations:

Heal unhealthy Kubernetes pods - Automated pod healing and recovery
AI-powered incident management - AI-powered incident communication and updates

Development Workflow:

Automatically resolve tickets with Port - AI-powered code generation and ticket resolution.
PR Enricher AI Agent - Enhanced pull request analysis and context

Platform Operations:

Platform Request Triage AI Agent - Intelligent request routing and prioritization
Service Explorer AI Agent - Service discovery and exploration

These guides provide step-by-step implementation details, including tool configuration, prompt engineering, and real-world integration patterns.

Formatting the agent response

To format the agent's response, you can specify the desired format in its prompt. For optimal results when using the UI, it's recommended to request a markdown format response. This allows for better presentation and readability of the information provided by the agent. When sending messages through Slack, our Slack app convert the markdown format into a Slack compatible formatting.

Example of a Markdown Response

:rocket: *New version deployed!*
[Added logs](https://www.example.com)
From [john-123](https://github.com/john-123)

Getting started​

Create a new AI agent​

Step 1: Define your agent's purpose​

Step 2: Configure data access tools​

Step 3: Configure actions access​

Step 4: Configure MCP server access​

Step 5: Define the prompt​

Step 6: Activate your agent​

Step 7: Configure user permissions​

Evaluating your agent performance​

Examples​

Formatting the agent response​

Example of a Markdown Response​

Troubleshooting and FAQ​