1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
You are a {{skill}} specialist agent in a multi-agent cognitive workflow.

## Your Role
{{description}}

## Constraints
- Your output MUST conform to the provided JSON schema
- You have a maximum of {{maxOutputTokens}} tokens
- Only use the tools you are authorized for: {{tools}}

## Output Schema
{{outputSchema}}

## Current Context
{{contextSnapshot}}

## Your Task
Analyze the provided context and produce a structured output matching your schema.

Key Principles

1. Be Specific About Output Format

1
2
3
4
5
❌ Don't: "Analyze the document and share your findings."

✅ Do: "Analyze the document and return a JSON object with:
- findings: array of strings (max 10)
- confidence: number between 0 and 1"

2. Reference the Schema

1
2
3
4
5
Your output MUST match this schema:
{
  "findings": ["string"],
  "confidence": 0.95
}

3. Bound the Response

1
2
3
- Maximum 5 findings
- Each finding should be one sentence
- Confidence must be between 0 and 1

Prompt Components

Role Definition

1
2
3
4
You are a **Semantic Mapper** agent responsible for:
- Binding natural language terms to ConceptIDs
- Using the Knowledge Graph for lookups
- Providing confidence scores for each mapping

Context Injection

1
2
3
4
## Current Context Snapshot
Query: "{{query}}"
Existing Bindings: {{bindings}}
Round: {{round}} of {{maxRounds}}

Output Instructions

1
2
3
4
5
6
7
8
9
## Required Output Format
Return a JSON object with this exact structure:
{
  "mappings": [
    { "term": "customer", "conceptId": "sea:customer:001", "confidence": 0.95 }
  ]
}

DO NOT include any text before or after the JSON.

Tool Usage Prompts

Authorizing Tools

1
2
3
4
5
6
7
8
9
You have access to these tools:
- read-kgs: Query the Knowledge Graph
- query-sbvr: Evaluate business rules

To use a tool, output:
{
  "tool": "read-kgs",
  "input": { "sparql": "SELECT * WHERE { ?s ?p ?o }" }
}

Tool Response Handling

1
2
3
4
5
6
Tool results will be provided as:
[TOOL_RESULT: read-kgs]
{ "nodes": [...] }
[/TOOL_RESULT]

Use these results to inform your final output.

Validation Prompts

Schema Reminder

1
2
3
IMPORTANT: Your output MUST be valid JSON matching the schema.
If you cannot provide a valid output, return:
{ "error": "reason", "partial": {...} }

Confidence Calibration

1
2
3
4
5
Score your confidence as:
- 0.9-1.0: High confidence, clear evidence
- 0.7-0.9: Moderate confidence, some ambiguity
- 0.5-0.7: Low confidence, significant uncertainty
- Below 0.5: Insufficient evidence, consider abstaining

Anti-Patterns

❌ Avoid

1
2
3
4
5
6
7
8
# Too vague
"Analyze this document."

# No structure
"Give me your thoughts."

# No bounds
"List all relevant findings."

✅ Prefer

1
2
3
4
5
6
7
8
# Specific
"Extract the top 5 key financial metrics from this quarterly report."

# Structured
"Return a JSON object with 'metrics' array and 'summary' string."

# Bounded
"Maximum 5 metrics, each with name and value."

Testing Prompts

1
2
3
4
5
6
7
8
9
10
# Test prompt with specific input
just cognitive-test-prompt \
  --agent semantic-mapper \
  --input "Map these terms: customer, order, payment"

# Compare outputs across prompt versions
just cognitive-compare-prompts \
  --v1 prompts/v1.md \
  --v2 prompts/v2.md \
  --test-cases tests/mapper-cases.json

📝 Prompt Engineering

Prompt Structure

System Prompt Template