Skip to content

Commit f1ea7c8

Browse files
yasmewadyasmewad
committed
Add docs for AI Traits
1 parent cd2a88d commit f1ea7c8

File tree

2 files changed

+240
-0
lines changed

2 files changed

+240
-0
lines changed

‎docs/source-2.0/additional-specs/ai-traits.rst

Lines changed: 239 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
.. _ai-traits:
2+
3+
================
4+
Smithy AI Traits
5+
================
6+
7+
Smithy AI traits provide metadata and a way for service authors embed contextual information to guide Large Language Models (LLMs) and other AI systems in understanding and interacting with services.
8+
9+
10+
.. smithy-trait:: smithy.ai#prompts
11+
.. _smithy.ai#prompts-trait:
12+
13+
----------------------------
14+
``smithy.ai#prompts`` trait
15+
----------------------------
16+
17+
Summary
18+
Defines prompt templates that provide contextual guidance to LLMs for understanding when and how to use operations or services. This trait can be used to generate prompts for a Model Context Protocol (MCP) server.
19+
Trait selector
20+
``:is(service, operation)``
21+
Value type
22+
``map`` where keys are prompt names and values are prompt template definitions.
23+
24+
The ``smithy.ai#prompts`` trait allows service authors to provide structured guidance to AI systems, including contextual descriptions, parameter templates with placeholder syntax, usage conditions, and workflow guidance for complex processes.
25+
26+
Each prompt template definition consists of the following components:
27+
28+
.. list-table::
29+
:header-rows: 1
30+
:widths: 15 15 70
31+
32+
* - Property
33+
- Type
34+
- Description
35+
* - description
36+
- ``string``
37+
- **Required** A concise description of the prompt's purpose and functionality.
38+
* - template
39+
- ``string``
40+
- **Required** The prompt template text.
41+
* - arguments
42+
- ``string``
43+
- Optional reference to a structure shape that defines the parameters used in the template placeholders. Valid value MUST be a structure shapeId.
44+
* - preferWhen
45+
- ``string``
46+
- Optional condition to provide preference for tool selection.May be used for routing to other tools or prompts.
47+
48+
49+
Template Placeholder Syntax
50+
============================
51+
52+
Prompt templates use ``{{parameterName}}`` syntax to reference parameters from the associated ``arguments`` structure. This can be useful to reference and interpolate members of arguments when accepting user input for prompts in Model Context Protocol (MCP) servers.
53+
54+
.. code-block:: smithy
55+
56+
@prompts({
57+
detailed_weather_report: {
58+
description: "Generate a comprehensive weather report"
59+
template: "Create a detailed weather report for {{location}} showing {{temperature}}°F with {{conditions}}. Include humidity at {{humidity}}% and provide recommendations for outdoor activities."
60+
arguments: DetailedWeatherInput
61+
}
62+
})
63+
64+
structure DetailedWeatherInput {
65+
location: String
66+
temperature: Float
67+
conditions: String
68+
humidity: Float
69+
}
70+
71+
72+
Service-level vs operation-level prompts
73+
========================================
74+
75+
**Service-level prompts** SHOULD be used to define workflows that compose multiple operations, provide guidance about the service and offer prompts that make complex interactions with the service simple:
76+
77+
.. code-block:: smithy
78+
79+
@prompts({
80+
service_overview: {
81+
description: "Overview of weather service capabilities"
82+
template: "This weather service provides current conditions and forecasts. Use GetCurrentWeather for immediate conditions, and leverage creative prompts like emoji_weather for enhanced user experience."
83+
preferWhen: "User needs to understand available weather service features"
84+
},
85+
vacation_weather_planner: {
86+
description: "Plan weather for vacation destinations"
87+
template: "Help plan a vacation by comparing weather between {{homeLocation}} and {{destinationLocation}}.
88+
Call GetCurrentWeather for both locations, then provide a recommendation on the best time to travel, what to pack, and activities to consider based on weather differences."
89+
arguments: VacationPlannerInput
90+
}
91+
})
92+
service WeatherService {
93+
operations: [GetCurrentWeather]
94+
}
95+
96+
**Operation-level prompts** SHOULD provide specific guidance for individual operations and their usage:
97+
98+
.. code-block:: smithy
99+
100+
@prompts({
101+
emergency_weather_check: {
102+
description: "Quick weather check for emergency situations"
103+
template: "Immediately check weather conditions at {{location}} focusing on safety concerns. Prioritize severe weather alerts, visibility, and hazardous conditions."
104+
arguments: GetCurrentWeatherInput
105+
preferWhen: "Emergency situations requiring immediate weather assessment"
106+
}
107+
})
108+
operation GetCurrentWeather {
109+
input: GetCurrentWeatherInput
110+
output: GetCurrentWeatherOutput
111+
}
112+
113+
structure GetCurrentWeatherInput {
114+
/// Location for getting weather
115+
@required
116+
location: String
117+
}
118+
119+
120+
Use cases for prompts
121+
=======================
122+
123+
Service authors can define sophisticated workflows by defining prompts to orchestrate multiple API calls and format results.
124+
125+
**Output formatting**
126+
127+
Service teams can control how LLMs present API results:
128+
129+
.. code-block:: smithy
130+
131+
@prompts({
132+
weather_dashboard: {
133+
description: "Create a weather dashboard with multiple data points"
134+
template: "Get weather for {{location}} and create a dashboard view. Format as: 🌡️ Temperature: [temp]°F | 💧 Humidity: [humidity]% | 🌤️ Conditions: [conditions]. Add appropriate weather emoji and brief activity recommendations."
135+
arguments: GetCurrentWeatherInput
136+
}
137+
})
138+
139+
**Multi-operation workflows**
140+
141+
Prompts can guide LLMs to perform complex workflows using existing operations:
142+
143+
.. code-block:: smithy
144+
145+
@prompts({
146+
vacation_weather_planner: {
147+
description: "Plan weather for vacation destinations"
148+
template: "Help plan a vacation by comparing weather between {{homeLocation}} and {{destinationLocation}}. Call GetCurrentWeather for both locations, then provide a recommendation on the best time to travel, what to pack, and activities to consider based on weather differences."
149+
arguments: VacationPlannerInput
150+
}
151+
})
152+
153+
structure VacationPlannerInput {
154+
@required
155+
homeLocation: String
156+
@required
157+
destinationLocation: String
158+
}
159+
160+
161+
A complete example
162+
=====================
163+
164+
The following example demonstrates creative prompt templates that enhance user experience with a weather service:
165+
166+
.. code-block:: smithy
167+
168+
$version: "2"
169+
170+
namespace example.weather
171+
172+
use smithy.ai#prompts
173+
174+
@prompts({
175+
emoji_weather: {
176+
description: "Get weather with emoji visualization"
177+
template: "Get current weather for {{location}} and display it with appropriate weather emojis (☀️ sunny, ⛅ partly cloudy, ☁️ cloudy, 🌧️ rainy, ⛈️ stormy, ❄️ snowy)."
178+
arguments: GetCurrentWeatherInput
179+
preferWhen: "User wants a fun, visual weather display"
180+
}
181+
travel_weather_advisor: {
182+
description: "Provides complete travel guidance according to the weather"
183+
template: "Get weather for {{location}} and provide travel advice. Include clothing recommendations based on temperature and conditions, suggest appropriate activities, and highlight any weather concerns."
184+
arguments: GetCurrentWeatherInput
185+
preferWhen: "User is planning travel or outdoor activities"
186+
}
187+
weather_comparison: {
188+
description: "Compare weather between multiple locations"
189+
template: "Compare current weather between {{location1}} and {{location2}}. Call GetCurrentWeather for each location, then present results in a table format showing temperature, conditions, and humidity. Highlight which location has better weather conditions."
190+
arguments: WeatherComparisonInput
191+
preferWhen: "User wants to compare weather across different cities"
192+
}
193+
})
194+
service WeatherService {
195+
version: "2024-01-01"
196+
operations: [GetCurrentWeather]
197+
}
198+
199+
operation GetCurrentWeather {
200+
input: GetCurrentWeatherInput
201+
output: GetCurrentWeatherOutput
202+
}
203+
204+
structure GetCurrentWeatherInput {
205+
/// Location to get weather for (city, coordinates, or address)
206+
@required
207+
location: String
208+
}
209+
210+
structure GetCurrentWeatherOutput {
211+
temperature: Float
212+
humidity: Float
213+
conditions: String
214+
}
215+
216+
structure WeatherComparisonInput {
217+
/// First location to compare
218+
@required
219+
location1: String
220+
221+
/// Second location to compare
222+
@required
223+
location2: String
224+
}
225+
226+
227+
Integration with Model Context Protocol
228+
=======================================
229+
230+
The ``smithy.ai#prompts`` trait is designed to work with Model Context Protocol (MCP) servers. MCP servers can use the metadata defined in the trait to generate _prompts:https://modelcontextprotocol.io/specification/2025-06-18/server/prompts as defined in the Model Context Protocol (MCP) specification.
231+
232+
See also
233+
- `MCP Server Example`_ for a complete implementation of an MCP server using Smithy
234+
- `MCP Traits Example`_ for additional examples of AI traits in practice
235+
- `MCP Server Model`_ for the Smithy model definition used in the MCP server example
236+
237+
.. _MCP Server Example: https://github.com/smithy-lang/smithy-java/tree/main/examples/mcp-server
238+
.. _MCP Traits Example: https://github.com/smithy-lang/smithy-java/tree/main/examples/mcp-traits-example
239+
.. _MCP Server Model: https://github.com/smithy-lang/smithy-java/blob/main/examples/mcp-server/src/main/resources/software/amazon/smithy/java/example/server/mcp/main.smithy

‎docs/source-2.0/additional-specs/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ start with ``smithy.*`` where "*" is anything other than ``api``.
1010
:maxdepth: 1
1111
:caption: smithy.* specifications
1212

13+
ai-traits
1314
http-protocol-compliance-tests
1415
smoke-tests
1516
waiters

0 commit comments

Comments
 (0)