Skip to main content

Check out Port for yourself 

Build an AI agent

Closed Beta

Port's AI offerings are currently in closed beta and will be gradually rolled out to users by the end of 2025.

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 tools are created dynamically based on your Port self-service actions. When you configure an action for the agent, it becomes available as a tool the agent can use. Here's how to add an action to the agent:

  1. Get the action identifier from the self-service page.
  2. Add it to your agent's configuration as an available tool with a syntax like run_{action_identifier}.
  3. Decide whether the agent can run the action automatically or requires approval.

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

Step 4: 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.

Step 5: Activate your agent​

When you feel your agent is ready:

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

Evaluating your agent performance​

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

  1. Weekly reviews: Set aside time each week to review agent interactions
  2. Identify patterns: Look for recurring issues or misunderstandings in how the agent interprets queries
  3. 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 in Port AI.

Examples​

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

Infrastructure & Operations:

Development Workflow:

Platform Operations:

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)

Troubleshooting & FAQ​

I don't see an option to add an AI agent (Click to expand)

Make sure you have access to the AI agents feature. Note that it's currently in closed beta and requires special access. If you believe you should have access, please contact our support.

How do I configure which tools my agent can access? (Click to expand)

Configure tools in two categories:

  • Data access tools: Add Port AI tools for retrieving information from your catalog
  • Action tools: Add action execution tools for running your self-service actions

For comprehensive tool details, see Port MCP Server documentation.

My agent can't access the data I need - what's wrong? (Click to expand)

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? (Click to expand)

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 tools and execution modes.

My agent isn't performing well - how do I improve it? (Click to expand)
  1. Review agent interactions through AI Invocations
  2. Refine your prompt based on common issues you identify
  3. Ensure your agent has access to the right tools for its domain
  4. Check our Context Engineering guide for prompt optimization

Start with simple prompts and iterate based on actual usage patterns.