Skip to content

Commit 4515a85

Browse files
Amichai-Skaliter-PortAmichai-Skaliter-Port
committed
Merge branch 'main' of https://github.com/port-labs/port-docs into r_uoStC8xH6rKv0Y81-add-multi-cert-support-port-agent-3
2 parents c9ccb8b + 7f465fa commit 4515a85

File tree

4 files changed

+168
-224
lines changed

4 files changed

+168
-224
lines changed

‎docs/guides/all/add-rca-context-to-ai-agents.md‎

Lines changed: 112 additions & 131 deletions
Original file line numberDiff line numberDiff line change
@@ -46,82 +46,83 @@ Follow the steps below to create the blueprint:
4646
4. Copy and paste the JSON schema from below:
4747

4848
<details>
49-
<summary>`Root Cause Analysis` blueprint</summary>
49+
<summary><b>`Root Cause Analysis` blueprint (click to expand)</b></summary>
5050

5151
The entities of this blueprint will represent different RCA documents from past incidents.
5252

53-
```json showLineNumbers
54-
{
55-
"identifier": "rootCauseAnalysis",
56-
"title": "Root Cause Analysis",
57-
"icon": "Bug",
58-
"schema": {
59-
"properties": {
60-
"summary": {
61-
"type": "string",
62-
"title": "Summary",
63-
"description": "Brief summary of the incident"
64-
},
65-
"incidentDate": {
66-
"type": "string",
67-
"format": "date-time",
68-
"title": "Incident Date",
69-
"description": "When the incident occurred"
70-
},
71-
"severity": {
72-
"type": "string",
73-
"title": "Severity",
74-
"enum": ["Critical", "High", "Medium", "Low"],
75-
"enumColors": {
76-
"Critical": "red",
77-
"High": "orange",
78-
"Medium": "yellow",
79-
"Low": "green"
53+
```json showLineNumbers
54+
{
55+
"identifier": "rootCauseAnalysis",
56+
"title": "Root Cause Analysis",
57+
"icon": "Bug",
58+
"description": "Historical Root Cause Analysis documents from past incidents, including resolutions, lessons learned, and preventive measures",
59+
"schema": {
60+
"properties": {
61+
"summary": {
62+
"type": "string",
63+
"title": "Summary",
64+
"description": "Brief summary of the incident"
65+
},
66+
"incidentDate": {
67+
"type": "string",
68+
"format": "date-time",
69+
"title": "Incident Date",
70+
"description": "When the incident occurred"
71+
},
72+
"severity": {
73+
"type": "string",
74+
"title": "Severity",
75+
"enum": ["Critical", "High", "Medium", "Low"],
76+
"enumColors": {
77+
"Critical": "red",
78+
"High": "orange",
79+
"Medium": "yellow",
80+
"Low": "green"
81+
}
82+
},
83+
"affectedServices": {
84+
"type": "array",
85+
"title": "Affected Services",
86+
"description": "Services impacted by this incident"
87+
},
88+
"rootCause": {
89+
"type": "string",
90+
"format": "markdown",
91+
"title": "Root Cause",
92+
"description": "Detailed analysis of what caused the incident"
93+
},
94+
"resolution": {
95+
"type": "string",
96+
"format": "markdown",
97+
"title": "Resolution",
98+
"description": "How the incident was resolved"
99+
},
100+
"preventiveMeasures": {
101+
"type": "string",
102+
"format": "markdown",
103+
"title": "Preventive Measures",
104+
"description": "Actions taken to prevent similar incidents"
105+
},
106+
"lessonsLearned": {
107+
"type": "string",
108+
"format": "markdown",
109+
"title": "Lessons Learned",
110+
"description": "Key takeaways and learnings from this incident"
111+
},
112+
"tags": {
113+
"type": "array",
114+
"title": "Tags",
115+
"description": "Tags for categorizing and searching RCAs"
80116
}
117+
},
118+
"required": ["summary", "incidentDate", "severity", "rootCause", "resolution"]
81119
},
82-
"affectedServices": {
83-
"type": "array",
84-
"title": "Affected Services",
85-
"description": "Services impacted by this incident"
86-
},
87-
"rootCause": {
88-
"type": "string",
89-
"format": "markdown",
90-
"title": "Root Cause",
91-
"description": "Detailed analysis of what caused the incident"
92-
},
93-
"resolution": {
94-
"type": "string",
95-
"format": "markdown",
96-
"title": "Resolution",
97-
"description": "How the incident was resolved"
98-
},
99-
"preventiveMeasures": {
100-
"type": "string",
101-
"format": "markdown",
102-
"title": "Preventive Measures",
103-
"description": "Actions taken to prevent similar incidents"
104-
},
105-
"lessonsLearned": {
106-
"type": "string",
107-
"format": "markdown",
108-
"title": "Lessons Learned",
109-
"description": "Key takeaways and learnings from this incident"
110-
},
111-
"tags": {
112-
"type": "array",
113-
"title": "Tags",
114-
"description": "Tags for categorizing and searching RCAs"
120+
"mirrorProperties": {},
121+
"calculationProperties": {},
122+
"aggregationProperties": {},
123+
"relations": {}
115124
}
116-
},
117-
"required": ["summary", "incidentDate", "severity", "rootCause", "resolution"]
118-
},
119-
"mirrorProperties": {},
120-
"calculationProperties": {},
121-
"aggregationProperties": {},
122-
"relations": {}
123-
}
124-
```
125+
```
125126
</details>
126127

127128
5. Click `Create` to save the blueprint.
@@ -150,7 +151,7 @@ Let's create our first RCA entity using the Port UI:
150151

151152
3. Toggle JSON mode and copy and paste the following JSON:
152153
<details>
153-
<summary>Database Connection Pool Exhaustion incident</summary>
154+
<summary><b>Database Connection Pool Exhaustion incident (click to expand)</b></summary>
154155

155156
```json showLineNumbers
156157
{
@@ -190,7 +191,7 @@ Let us add another RCA entity:
190191
2. Toggle JSON mode and copy and paste the following JSON:
191192

192193
<details>
193-
<summary>Memory Leak incident</summary>
194+
<summary><b>Memory Leak incident (click to expand)</b></summary>
194195

195196
```json showLineNumbers
196197
{
@@ -340,7 +341,7 @@ else:
340341
**Example integration scenarios:**
341342

342343
<details>
343-
<summary>GitHub Actions workflow</summary>
344+
<summary><b>GitHub Actions workflow (click to expand)</b></summary>
344345

345346
```yaml title=".github/workflows/create-rca.yml"
346347
name: Create RCA from Issue
@@ -389,11 +390,10 @@ jobs:
389390
print(f'RCA created: {response.status_code}')
390391
"
391392
```
392-
393393
</details>
394394
395395
<details>
396-
<summary>Standalone Python script for bulk import</summary>
396+
<summary><b>Standalone Python script for bulk import (click to expand)</b></summary>
397397
398398
```python title="bulk_import_rcas.py"
399399
#!/usr/bin/env python3
@@ -465,7 +465,6 @@ def main():
465465
if __name__ == '__main__':
466466
main()
467467
```
468-
469468
</details>
470469
471470
</TabItem>
@@ -598,87 +597,69 @@ For a more comprehensive knowledge base, consider adding 5-10 RCA documents cove
598597

599598
## Update AI agent configuration
600599

601-
Now we'll modify the Incident Manager AI agent to include access to our RCA documents.
600+
The Incident Manager AI agent uses the MCP tools pattern (`^(list|get|search|track|describe)_.*`), which automatically provides access to all blueprints in your catalog - including the RCA blueprint you just created. This means the agent can already search and reference RCA documents without any configuration changes.
602601

603-
<h3> Add RCA blueprint to allowed blueprints</h3>
604-
605-
1. Go to the [AI Agents](https://app.getport.io/_ai_agents) page.
606-
607-
2. Find the **Incident Manager** agent and click on the `...` on the far right of the row.
608-
609-
3. Click on `Edit`.
602+
:::tip Automatic blueprint discovery
603+
With the MCP tools pattern, AI agents automatically discover new blueprints you create. You don't need to manually add `"rootCauseAnalysis"` to any configuration - the agent already has access to query and reference these documents.
604+
:::
610605

611-
4. In the `allowed_blueprints` array, add `"rootCauseAnalysis"`:
612606

613-
```json showLineNumbers
614-
"allowed_blueprints": [
615-
"pagerdutyService",
616-
"pagerdutyIncident",
617-
"pagerdutyEscalationPolicy",
618-
"pagerdutySchedule",
619-
"pagerdutyOncall",
620-
"pagerdutyUser",
621-
"_user",
622-
"_team",
623-
"service",
624-
"rootCauseAnalysis" //highlight
625-
]
626-
```
607+
<h3> Update the agent prompt (Optional)</h3>
627608

628-
5. Click `Save` to save the changes.
609+
While the agent can automatically access RCA documents, updating the prompt helps guide it on when and how to use this information effectively.
629610

611+
1. Go to the [AI Agents](https://app.getport.io/_ai_agents) page.
630612

631-
<h3> Update the agent prompt</h3>
613+
2. Find the **Incident Manager** agent and click on the `...` on the far right of the row.
632614

633-
Enhance the prompt to include instructions about using RCA context:
615+
3. Click on `Edit`.
634616

635-
1. Click on `Edit property` on the `Prompt` field.
617+
4. Click on `Edit property` on the `Prompt` field.
636618

637-
2. Replace the existing content with the following:
619+
5. Replace the existing content with the following:
638620

639621
<details>
640-
<summary>Enhanced agent prompt</summary>
622+
<summary><b>Enhanced agent prompt (click to expand)</b></summary>
641623

642-
```markdown showLineNumbers"
643-
You are an agent responsible for answering questions about PagerDuty incidents, services, escalation policies, schedules, and on-call rotations.
644-
You also have access to historical Root Cause Analysis (RCA) documents from past incidents.
645-
646-
## Guidelines
647-
- Provide clear information about incidents
648-
- Identify who is on-call for services (both primary and secondary on-call)
649-
- Report on incident statistics and resolution times
650-
- When relevant, reference past RCA documents to provide context and suggest solutions
651-
- Use RCA lessons learned to help prevent similar incidents
652-
- Suggest preventive measures based on historical incident patterns
624+
```markdown showLineNumbers"
625+
You are an agent responsible for answering questions about PagerDuty incidents, services, escalation policies, schedules, and on-call rotations.
626+
You also have access to historical Root Cause Analysis (RCA) documents from past incidents.
627+
628+
### Guidelines
629+
- Provide clear information about incidents
630+
- Identify who is on-call for services (both primary and secondary on-call)
631+
- Report on incident statistics and resolution times
632+
- When relevant, reference past RCA documents to provide context and suggest solutions
633+
- Use RCA lessons learned to help prevent similar incidents
634+
- Suggest preventive measures based on historical incident patterns
653635
```
654-
</details>
636+
</details>
655637

656-
3. Click `Save` to save the changes.
638+
6. Click `Save` to save the changes.
657639

658-
<h3> Add RCA-focused conversation starters</h3>
640+
<h3> Add RCA-focused conversation starters (Optional)</h3>
659641

660642
1. Click on `Edit property` on the `Conversation starters` field.
661643

662644
2. Replace the existing content with the following:
663645

664646
<details>
665-
<summary>Conversation starters</summary>
647+
<summary><b>Conversation starters (click to expand)</b></summary>
666648

667-
```json showLineNumbers
649+
```json showLineNumbers
668650
[
669-
"Who is on call for the payment service?",
670-
"What are the active incidents right now?",
671-
"What is our average incident resolution time?",
672-
"Have we seen database connection issues before?",
673-
"What can we learn from past payment service incidents?",
674-
"Show me RCAs for incidents similar to the current one"
651+
"Who is on call for the payment service?",
652+
"What are the active incidents right now?",
653+
"What is our average incident resolution time?",
654+
"Have we seen database connection issues before?",
655+
"What can we learn from past payment service incidents?",
656+
"Show me RCAs for incidents similar to the current one"
675657
]
676-
```
658+
```
677659
</details>
678660

679-
3. Click `Save property` to save the changes.
680661

681-
4. Click on `Update` to save the changes to the agent.
662+
3. Click on `Update` to save the changes to the agent.
682663

683664
:::info Using RCA Context
684665
You can now use these RCA context in your agent's responses:
@@ -787,4 +768,4 @@ Here are some ways to expand and improve your setup:
787768
- **Cross-reference data**: Link RCAs to services, teams, and other relevant entities using relations.
788769
- **Monitor agent usage**: Review AI invocation logs to see how effectively the agent uses RCA context.
789770
- **Add more context types**: Create additional blueprints for different types of organizational knowledge.
790-
- **Regular maintenance**: Periodically review and update RCA documents as processes evolve.
771+
- **Regular maintenance**: Periodically review and update RCA documents as processes evolve.

‎docs/guides/all/heal-unhealthy-k8s-pods.md‎

Lines changed: 12 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1107,20 +1107,6 @@ Next, we will create an AI agent that analyzes pod health issues and creates com
11071107
"properties": {
11081108
"description": "AI agent specialized in diagnosing and automatically fixing unhealthy Kubernetes workloads. Monitors pod health, identifies root causes, and applies appropriate fixes.",
11091109
"status": "active",
1110-
"allowed_blueprints": [
1111-
"k8s_workload",
1112-
"k8s_pod",
1113-
"k8s_replicaSet",
1114-
"k8s_namespace",
1115-
"k8s_cluster"
1116-
],
1117-
"allowed_actions": [
1118-
"get_k8s_pod_logs",
1119-
"restart_k8s_workload",
1120-
"scale_k8s_workload",
1121-
"update_k8s_workload_config",
1122-
"create_k8s_fix_pr"
1123-
],
11241110
"prompt": "You are a Kubernetes healing AI agent with access to comprehensive SDLC data and pod logs.\n\n**Your healing process:**\n1. **FIRST - Get Logs**: Always start by retrieving pod logs using the get_k8s_pod_logs action to understand what's actually happening\n2. **Analyze with Context**: Combine log data with SDLC information (recent deployments, code changes, configuration updates) to build a complete picture\n3. **Intelligent Diagnosis**: Based on logs and context, determine the root cause (crashes, resource constraints, configuration issues, etc.)\n4. **Targeted Fix**: Execute only the specific action that will resolve the issue:\n - Restart for crashes and transient issues\n - Scale for resource constraints (CPU/memory)\n - Update config for resource limit issues\n - Create PR for complex fixes requiring code changes\n5. **Explain Your Actions**: Always explain what you found in the logs and why you chose the specific fix in your response",
11251111
"execution_mode": "Automatic",
11261112
"conversation_starters": [
@@ -1130,13 +1116,25 @@ Next, we will create an AI agent that analyzes pod health issues and creates com
11301116
"Scale up resources for this memory-constrained workload",
11311117
"What's causing this ImagePullBackOff error?",
11321118
"Why are my pods stuck in Pending state?"
1119+
],
1120+
"tools": [
1121+
"^(list|get|search|track|describe)_.*",
1122+
"run_get_k8s_pod_logs",
1123+
"run_restart_k8s_workload",
1124+
"run_scale_k8s_workload",
1125+
"run_update_k8s_workload_config",
1126+
"run_create_k8s_fix_pr"
11331127
]
11341128
},
11351129
"relations": {}
11361130
}
11371131
```
11381132
</details>
11391133

1134+
:::tip MCP Enhanced Capabilities
1135+
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 Kubernetes resources, recent deployments, code changes, runbooks, and history logs. This gives the agent rich SDLC context to make intelligent healing decisions. Additionally, we explicitly add the remediation action tools (`run_get_k8s_pod_logs`, `run_restart_k8s_workload`, etc.), which the agent calls sequentially to diagnose and fix unhealthy workloads.
1136+
:::
1137+
11401138
5. Click `Create` to save the agent.
11411139

11421140
## Set up automation

0 commit comments

Comments
 (0)