Skip to main content

Check out Port for yourself 

Set up the Service Explorer AI agent

Overview​

This guide will walk you through setting up a "Service Explorer" AI agent in Port. This agent helps developers discover services, understand ownership, and access documentation for quick onboarding. By the end of this guide, your developers will be able to get information about your services via Port's AI chat.

Common use cases​

  • Quick service discovery for new developers.
  • Understanding service ownership and team responsibilities.
  • Accessing service documentation and READMEs.
  • Checking service compliance and production readiness.
  • Finding the right team to contact about a service.

Prerequisites​

This guide assumes you have:

Set up​

To create a Service Explorer AI agent in Port, we'll need to configure two main components as described in our Build an AI agent guide:

  • The data sources it will use to answer questions.
  • The agent configuration that defines its capabilities and conversation starters.

Create the agent configuration​

  1. Go to the AI Agents page of your portal.

  2. Click on + AI Agent.

  3. Toggle Json mode on.

  4. Copy and paste the following JSON schema:

    Service Explorer agent configuration (Click to expand)
    {
      "identifier": "service_ownership_onboarding",
      "title": "Service Explorer",
      "icon": "Service",
      "properties": {
        "description": "Helps developers discover services, understand ownership, and access documentation for quick onboarding",
        "status": "active",
        "allowed_blueprints": [
          "service",
          "githubRepository",
          "_team",
          "_user",
          "githubTeam",
          "githubUser"
        ],
        "prompt": "You are an agent responsible for helping developers understand the service landscape, ownership, and onboarding information.\n\n### Guidelines\n- Provide clear information about service ownership (teams and individuals)\n- Explain what services do based on their README and description\n- Identify service dependencies and relationships\n- Share service quality metrics and scorecard compliance\n- Help new developers understand which team owns which services\n- When asked about a service, always include: owner, team, description, and key technical details\n- If a service has a README, prioritize information from there\n- Mention service tier/criticality when relevant",
        "execution_mode": "Approval Required",
        "conversation_starters": [
          "Who owns the oauth service?",
          "What is the payments service about?",
          "Which services does the platform team own?",
          "Show me all services that don't have a README",
          "Which services are failing their production readiness scorecard?"
        ]
      }
    }

  5. Click on Create to save the agent.

Blueprint Configuration​

Minimum Configuration​

The guide's configuration provides a good starting point. The minimum configuration for the Service Explorer agent requires the service and githubRepository blueprints. This provides the agent with basic information about your services and their corresponding code repositories.

Enhancing the Agent with More Blueprints​

To make the Service Explorer more powerful, you can add more blueprints to the allowed_blueprints array in the agent's configuration. The more context you provide, the more detailed and accurate the agent's responses will be.

Here are some examples of how you can enhance the agent by adding more blueprints:

  • PagerDuty (pagerdutyService, pagerdutyIncident): Adds incident history, on-call information, and service health.
  • Kubernetes (workload, argocdApplication): Shows deployment status, pod health, and runtime information.
  • Monitoring (newRelicService, newRelicAlert): Provides performance metrics and alert status.
  • Feature Flags (launchDarklyFeatureFlag): Shows which features are enabled for each service.
  • Documentation (jiraProject, jiraIssue): Links to project documentation and known issues.

Customizing Blueprint Access​

You can modify the allowed_blueprints array at any time to add or remove blueprints.

For example, if you want to give the agent access to Kubernetes information, you would add "workload" and "argocdApplication" to the array:

"allowed_blueprints": [
  "service",
  "githubRepository",
  // ... other blueprints
  "workload",
  "argocdApplication"
]

Keep in mind that there is a trade-off between context richness and response time. The more blueprints the agent has access to, the longer it may take to generate a response. It's best to start with a minimal set of blueprints and add more as needed.

Interact with the Service Explorer​

You can interact with the Service Explorer AI agent in several ways. This guide will demonstrate the two main ways.

The Service Explorer AI agent can be accessed through an AI Agent widget in your Port dashboard. Follow the steps below to set it up:

  1. Go to the homepage of your portal.
  2. Click on + Widget.
  3. Choose AI agent.
  4. Type Service Explorer for Title.
  5. Select Service Explorer from the Agent dropdown.
  6. Click on Save.

Once the widget is set up, you can ask questions directly in the chat field.

Example questions​

Here are some questions you can ask the Service Explorer agent:

  • "Who owns the oauth service?"
  • "What is the payments service about?"
  • "Which services does the platform team own?"
  • "Show me all tier 1 services"
  • "Which services don't have a README?"
  • "What services is John Smith responsible for?"
  • "Show me all services with active incidents"
  • "Which services are failing their production readiness scorecard?"

Possible enhancements​

You can further enhance the Service Explorer setup by:

  • Adding more service context: Include additional blueprints like workload, newRelicService, or argocdApplication.
  • Enriching with incidents: Add the pagerdutyIncident blueprint to see the incident history for each service.
  • Including deployments: Add deployment-related blueprints for release information.
  • Adding custom metadata: Add organization-specific properties to the service blueprint to provide more context.