Server concepts in learn #903
Conversation
felixweinberger
force-pushed
the
docs/develop
branch
2 times, most recently
from
170ad13 to
24ac67f
Compare
docs/docs/learn/server-concepts.mdx
Outdated
|
|
||
| #### Overview | ||
|
|
||
| Resources use URI-based identification, with each resource having a unique URI such as `file:///path/to/document.md`. They declare MIME types for appropriate content handling and support two access patterns: direct resources with fixed URIs, and resource templates with parameterized URIs. |
There was a problem hiding this comment.
The phrase "two access patterns" doesn't seem quite right. resources/read is the sole access pattern, whereas resources/list and resources/templates/list are the two discovery patterns.
Also, MIME types are optional, though it may be fine to gloss over that here.
docs/docs/learn/server-concepts.mdx
Outdated
| - **Name**: Unique identifier for the prompt | ||
| - **Description**: User-facing explanation of purpose | ||
| - **Arguments**: Typed parameters with optional defaults | ||
| - **Instructions**: Template text with parameter placeholders |
There was a problem hiding this comment.
Regarding "Instructions", the server doesn't expose the template text to the client, and the actual prompt content that the server returns is termed "messages" (e.g. messages[i].content). What do we want to highlight here?
Also, similar to previous comments, I think title is currently preferred over name, and these fields may be optional.
There was a problem hiding this comment.
name is unique identifier, where title is preferred for a display. I think I will just remove this section, it's not super useful here
docs/docs/learn/server-concepts.mdx
Outdated
| ```yaml | ||
| name: plan-vacation | ||
| description: Guide through vacation planning process | ||
| arguments: | ||
| - destination: string (required) | ||
| - duration: number (days) | ||
| - budget: number (optional) | ||
| - interests: array of strings | ||
| ``` |
There was a problem hiding this comment.
just for the formatting
docs/docs/learn/server-concepts.mdx
Outdated
| ```yaml | ||
| prompt: plan-vacation | ||
| arguments: | ||
| destination: "Barcelona" | ||
| departure_date: "2024-06-15" | ||
| return_date: "2024-06-22" | ||
| budget: 3000 | ||
| travelers: 2 | ||
| ``` |
There was a problem hiding this comment.
Some comments inline - overall I think this is a really nice overview of the building blocks.
The main thing that hit me was the feeling that the integrated example's use of resource templates is kind of implausible (IMO ofc - tell me if I'm wrong!). But I think that may really be a more fundamental question about the use of resources, rather than an issue with the content here.
docs/docs/learn/server-concepts.mdx
Outdated
|
|
||
| #### Overview | ||
|
|
||
| Tools are characterized by their schema-defined interfaces, which use JSON Schema for parameter validation. Each tool performs a single, atomic operation with clearly defined inputs and outputs. Most importantly, tool execution requires explicit user approval, ensuring users maintain control over actions taken on their behalf. |
There was a problem hiding this comment.
| Tools are characterized by their schema-defined interfaces, which use JSON Schema for parameter validation. Each tool performs a single, atomic operation with clearly defined inputs and outputs. Most importantly, tool execution requires explicit user approval, ensuring users maintain control over actions taken on their behalf. | |
| Tools are characterized by their schema-defined interfaces, which use JSON Schema for validation. Each tool performs a single operation with clearly defined inputs and outputs. Most importantly, tool execution requires explicit user approval, ensuring users maintain control over actions taken on their behalf. |
- removed "parameter" because I wanted to say something about output validation, but "parameter (and optional output) validation" might be too much too soon
- removed "atomic" - I think it implies a constraint that doesn't actually exist
docs/docs/learn/server-concepts.mdx
Outdated
| 3. **Excepteur**: Sint occaecat cupidatat non proident sunt in culpa (qui officia deserunt mollit) | ||
| ### Tools - AI actions | ||
|
|
||
| Tools enable AI models to perform actions through server-implemented functions. Each tool defines a specific operation with typed inputs and outputs. |
There was a problem hiding this comment.
| Tools enable AI models to perform actions through server-implemented functions. Each tool defines a specific operation with typed inputs and outputs. | |
| Tools enable AI models to perform actions through server-implemented functions. Each tool defines a specific operation with typed inputs and outputs. The model requests tool execution based on context. |
Added the last sentence for color - I don't think it overspecifies but ymmv
docs/docs/learn/server-concepts.mdx
Outdated
| - **Travel documents** (`file:///Documents/Travel/passport.pdf`) - For important information | ||
| - **Previous itineraries** (`trips://history/barcelona-2023`) - For reference | ||
|
|
||
| Instead of manually copying this information, resources let the AI access it directly with user permission. During planning, the AI can check calendar availability, look up weather patterns, and reference travel preferences—all through structured resource access. |
There was a problem hiding this comment.
"resources let the AI access it directly" sounds more like model-controlled than app-controlled - a clarifying edit might be "resources let the user add it directly to the context" (which gets unpacked in the more detailed description below).
But zooming out, maybe defining resources as app-controlled might be one of the things that's holding adoption of resources back?
E.g. I'm deciding between weather://forecast/{city}/{date} and get_weather(city, date) and the former requires the user (via an app UI) to add the weather to the context explicitly, rather than letting the model discover and choose get_weather.
Partly I'm thinking this through myself, but I'm also channeling the doc reader who might at this point have the same question. I think a having a brief high-level "Tools vs Resources: how to choose" section on this page might be really useful.
There was a problem hiding this comment.
"Tools vs Resources: how to choose" I'll do it as a separate PR
docs/docs/learn/server-concepts.mdx
Outdated
| - `calendar://my-calendar/June-2024` (from Calendar Server) | ||
| - `travel://preferences/europe` (from Travel Server) | ||
| - `travel://past-trips/Spain-2023` (from Travel Server) | ||
| - `weather://forecast/Barcelona/2024-06` (from Weather Server) |
There was a problem hiding this comment.
Apropos of the resources vs tools comment above (and the bigger question of how resources are really used) - is this realistic? It seems like "I'm thinking of planning a vacation, idk Barcelona? What's the weather like there rn" in a chatbot (+ model-driven tool calls to e.g. get_weather) is the way it would actually be done, rather than picking city out of an app modal and typing in a date.
TBH I can't think of a good use "typical" case for parameterized resources, they all turn into tools in my mind - it's because for examples like weather and calendar, "app-controlled" implies it's the user doing the parameterization via app UI, which seems cumbersome compared to the model translating natural language into parameters. (For direct resources it's easier, e.g. here's my passport.)
There was a problem hiding this comment.
yeah, maybe we can have a simpler example of past travel - as this is something user wants to select
No description provided.