Skip to content

Commit 55d07f5

Browse files
kodjomileskodjomiles
committed
docs: update Service Explorer AI agent setup guide to clarify data model and enhance configuration instructions
1 parent 629cfd4 commit 55d07f5

File tree

1 file changed

+33
-68
lines changed

1 file changed

+33
-68
lines changed

‎docs/guides/all/setup-service-explorer-ai-agent.md‎

Lines changed: 33 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ This guide assumes you have:
4141
- [Kubernetes](/build-your-software-catalog/sync-data-to-catalog/kubernetes-stack/kubernetes/) tools for deployment information.
4242
- Monitoring tools (e.g., [New Relic](/build-your-software-catalog/sync-data-to-catalog/apm-alerting/newrelic/)) for service health.
4343

44-
## Set up
44+
## Set up data model
4545

4646
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](/ai-interfaces/ai-agents/build-an-ai-agent) guide:
4747
- The data sources it will use to answer questions.
@@ -50,8 +50,11 @@ To create a Service Explorer AI agent in Port, we'll need to configure two main
5050
### Create the agent configuration
5151

5252
1. Go to the [AI Agents](https://app.getport.io/_ai_agents) page of your portal.
53+
5354
2. Click on `+ AI Agent`.
55+
5456
3. Toggle `Json mode` on.
57+
5558
4. Copy and paste the following JSON schema:
5659

5760
<details>
@@ -63,72 +66,30 @@ To create a Service Explorer AI agent in Port, we'll need to configure two main
6366
"title": "Service Explorer",
6467
"icon": "Service",
6568
"properties": {
66-
"description": "Helps developers discover services, understand ownership, and access documentation for quick onboarding",
67-
"status": "active",
68-
"allowed_blueprints": [
69-
"service",
70-
"githubRepository",
71-
"_team",
72-
"_user",
73-
"githubTeam",
74-
"githubUser"
75-
],
76-
"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",
77-
"execution_mode": "Approval Required",
78-
"conversation_starters": [
79-
"Who owns the oauth service?",
80-
"What is the payments service about?",
81-
"Which services does the platform team own?",
82-
"Show me all services that don't have a README",
83-
"Which services are failing their production readiness scorecard?"
84-
]
85-
}
69+
"description": "Helps developers discover services, understand ownership, and access documentation for quick onboarding",
70+
"status": "active",
71+
"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",
72+
"execution_mode": "Approval Required",
73+
"conversation_starters": [
74+
"Who owns the oauth service?",
75+
"What is the payments service about?",
76+
"Which services does the platform team own?",
77+
"Show me all services that don't have a README",
78+
"Which services are failing their production readiness scorecard?"
79+
],
80+
"tools": [
81+
"^(list|get|search|track|describe)_.*"
82+
]
83+
}
8684
}
8785
```
8886
</details>
8987

90-
5. Click on `Create` to save the agent.
91-
92-
## Blueprint configuration
93-
94-
### Minimum configuration
95-
96-
The Service Explorer agent requires access to the `service` and `githubRepository` blueprints.
97-
This gives the agent basic visibility into your services and their corresponding code repositories.
98-
99-
From here, you can expand the agent’s capabilities in one of two ways:
100-
- **Classic mode**: Manually add more blueprints to provide richer service context (e.g., incidents, deployments, monitoring).
101-
- **MCP mode**: Enable automatic discovery and management of blueprints, entities, and actions, with built-in transparency.
102-
103-
104-
### Classic mode
105-
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.
106-
107-
Here are some examples of how you can enhance the agent by adding more blueprints:
108-
109-
- **PagerDuty** (`pagerdutyService`, `pagerdutyIncident`): Adds incident history, on-call information, and service health.
110-
- **Kubernetes** (`workload`, `argocdApplication`): Shows deployment status, pod health, and runtime information.
111-
- **Monitoring** (`newRelicService`, `newRelicAlert`): Provides performance metrics and alert status.
112-
- **Feature Flags** (`launchDarklyFeatureFlag`): Shows which features are enabled for each service.
113-
- **Documentation** (`jiraProject`, `jiraIssue`): Links to project documentation and known issues.
114-
115-
<h4> Customizing Blueprint Access </h4>
116-
You can modify the `allowed_blueprints` array at any time to add or remove blueprints.
117-
118-
For example, if you want to give the agent access to Kubernetes information, you would add `"workload"` and `"argocdApplication"` to the array:
119-
```json
120-
"allowed_blueprints": [
121-
"service",
122-
"githubRepository",
123-
// ... other blueprints
124-
"workload",
125-
"argocdApplication"
126-
]
127-
```
128-
129-
### MCP mode
130-
When using [MCP server backend mode](/ai-interfaces/ai-agents/interact-with-ai-agents), no manual additional blueprint configuration is required. MCP auto-discovers and manages access to blueprints, entities, and actions. This simplifies setup and ensures the agent always has the latest catalog context.
88+
:::tip MCP Enhanced Capabilities
89+
The AI agent uses MCP (Model Context Protocol) enhanced capabilities to automatically discover important and relevant blueprint entities via its tools. The `^(list|get|search|track|describe)_.*` pattern allows the agent to access and analyze related entities across your entire software catalog, including services, repositories, teams, users, incidents, deployments, monitoring data, and more. This automatic discovery means you don't need to manually configure which blueprints the agent can access - it intelligently finds and uses relevant data to answer questions about your services.
90+
:::
13191

92+
5. Click on `Create` to save the agent.
13293

13394
## Interact with the Service Explorer
13495

@@ -140,12 +101,16 @@ You can interact with the Service Explorer AI agent in [several ways](/ai-interf
140101
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:
141102

142103
1. Go to the [homepage](https://app.getport.io/organization/home) of your portal.
104+
143105
2. Click on `+ Widget`.
106+
144107
3. Choose `AI agent`.
108+
145109
4. Type **Service Explorer** for `Title`.
110+
146111
5. Select **Service Explorer** from the `Agent` dropdown.
147-
6. **Enable MCP backend mode** (optional): Toggle the "Use MCP" option to enable enhanced capabilities with intelligent catalog access and Claude models.
148-
7. Click on `Save`.
112+
113+
6. Click on `Save`.
149114

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

@@ -191,7 +156,7 @@ Here are some questions you can ask the Service Explorer agent:
191156

192157
You can further enhance the Service Explorer setup by:
193158

194-
- **Classic mode:**: Include additional blueprints like `workload`, `newRelicService`, or `argocdApplication`.
195-
- **MCP mode**: Relying on MCP’s discovery to automatically include new entities and actions.
196-
- **Transparency logs**: Using MCP’s visibility features to monitor how the agent answers questions.
197-
- **Custom metadata**: Add organization-specific properties to the service blueprint for richer answers.
159+
- **Enrich your catalog**: Add more integrations (PagerDuty, Kubernetes, monitoring tools) to your Port catalog. The agent will automatically discover and use this data thanks to the MCP tools pattern.
160+
- **Custom metadata**: Add organization-specific properties to the service blueprint for richer answers that reflect your team's needs.
161+
- **Refine the prompt**: Customize the agent's prompt to emphasize specific aspects of service ownership or documentation standards unique to your organization.
162+
- **Monitor interactions**: Check the [AI interaction details](/ai-interfaces/ai-agents/interact-with-ai-agents#ai-interaction-details) to see how developers are using the agent and improve it based on their questions and feedback.

0 commit comments

Comments
 (0)