Skip to content

Commit 7f465fa

Browse files
sivanel97sivanel97
authored
Merge pull request #2933 from port-labs/update-add-rca-context-to-ai-agents-guide-description
Enhance RCA context in AI agent documentation with automatic blueprint discovery
2 parents 7d67dd0 + f54b691 commit 7f465fa

File tree

1 file changed

+112
-131
lines changed

1 file changed

+112
-131
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.

0 commit comments

Comments
 (0)