From ba2536f46daac6c1a3f4b5fe35ff82f3840b52c2 Mon Sep 17 00:00:00 2001 From: Samantha Coyle Date: Tue, 16 Jun 2026 13:10:58 -0500 Subject: [PATCH 1/2] fix(conversation): update api docs + drive more clarity Signed-off-by: Samantha Coyle --- .../en/reference/api/conversation_api.md | 44 +++++++++++-------- 1 file changed, 25 insertions(+), 19 deletions(-) diff --git a/daprdocs/content/en/reference/api/conversation_api.md b/daprdocs/content/en/reference/api/conversation_api.md index c84289b9017..6d8872a563b 100644 --- a/daprdocs/content/en/reference/api/conversation_api.md +++ b/daprdocs/content/en/reference/api/conversation_api.md @@ -34,8 +34,8 @@ POST http://localhost:/v1.0-alpha2/conversation//converse | --------- | ----------- | | `contextId` | The ID of an existing chat (like in ChatGPT). Optional | | `inputs` | Inputs for the conversation. Multiple inputs at one time are supported. Required | -| `parameters` | Parameters for all custom fields. Optional | -| `metadata` | Metadata passed to conversation components. Optional | +| `parameters` | Typed per-request overrides for provider-specific fields (for example `model`, `max_tokens`). Values are wrapped in `google.protobuf.Any`. Optional | +| `metadata` | Up to 16 key-value pairs to attach to the conversation for structured tagging (for example `user_id`, `session_id`). Not a mechanism for overriding component configuration. Optional | | `scrubPii` | A boolean value to enable obfuscation of sensitive information returning from the LLM. Optional | | `temperature` | A float value to control the temperature of the model. Used to optimize for consistency (0) or creativity (1). Optional | | `tools` | Tools register the tools available to be used by the LLM during the conversation. Optional | @@ -78,39 +78,45 @@ Tools can be defined using the `tools` field with function definitions: The `toolChoice` is an optional parameter that controls how the model can use available tools: +- **`none`**: The model will not call any tool and instead generates a message (default when no tools are present) - **`auto`**: The model can pick between generating a message or calling one or more tools (default when tools are present) - **`required`**: Requires one or more functions to be called - **`{tool_name}`**: Forces the model to call a specific tool by name #### Metadata -The `metadata` field serves as a dynamic configuration mechanism that allows you to pass additional configuration and authentication information to conversation components on a per-request basis. This metadata overrides any corresponding fields configured in the component's YAML configuration file, enabling dynamic configuration without modifying static component definitions. +The `metadata` field is a set of up to 16 key-value pairs that can be attached to the conversation. This mirrors [OpenAI's `metadata` field](https://platform.openai.com/docs/api-reference/chat/create#chat-create-metadata) and is intended for storing additional information about the conversation in a structured format, such as user IDs, session IDs, or other application-specific tags. -**Common metadata fields:** +This field is **not** a mechanism for overriding component configuration or passing authentication details such as API keys; provider credentials and connection settings belong in the component's YAML configuration file. -| Field | Description | Example | -| ----- | ----------- | ------- | -| `api_key` | API key for authenticating with the LLM service | `"sk-1234567890abcdef"` | -| `model` | Specific model identifier | `"gpt-4-turbo"`, `"claude-3-sonnet"` | -| `version` | API version or service version | `"1.0"`, `"2023-12-01"` | -| `endpoint` | Custom endpoint URL for the service | `"https://api.custom-llm.com/v1"` | +**Constraints:** -{{% alert title="Note" color="primary" %}} -The exact metadata fields supported depend on the specific conversation component implementation. Refer to the component's documentation for the complete list of supported metadata fields. -{{% /alert %}} +- Maximum of 16 key-value pairs +- Keys are strings up to 64 characters +- Values are strings up to 512 characters + +**Example usage:** + +```json +"metadata": { + "user_id": "user-1234", + "session_id": "session-abcd", + "environment": "production" +} +``` In addition to passing metadata in the request body, you can also pass metadata as URL query parameters without modifying the request payload. Here is the format: - **Prefix**: All metadata parameters must be prefixed with `metadata.` - **Format**: `?metadata.=` -- **Multiple parameters**: Separate with `&` (e.g., `?metadata.api_key=sk-123&metadata.model=gpt-4`) +- **Multiple parameters**: Separate with `&` (e.g., `?metadata.user_id=user-1234&metadata.session_id=session-abcd`) -Example of model override: +Example: ```bash -POST http://localhost:3500/v1.0-alpha2/conversation/openai/converse?metadata.model=sk-gpt-4-turbo +POST http://localhost:3500/v1.0-alpha2/conversation/openai/converse?metadata.user_id=user-1234 ``` -URL metadata parameters are merged with request body metadata, URL parameters take precedence if conflicts exist, and both override component configuration in the YAML file. +URL metadata parameters are merged with request body metadata; URL parameters take precedence if conflicts exist. ### Request content examples @@ -173,8 +179,8 @@ curl -X POST http://localhost:3500/v1.0-alpha2/conversation/openai/converse \ } }, "metadata": { - "api_key": "test-key", - "version": "1.0" + "user_id": "user-1234", + "session_id": "session-abcd" }, "scrubPii": false, "temperature": 0.7, From 33d2d60e2cc1e87fb75908a39fab209283ac5fc9 Mon Sep 17 00:00:00 2001 From: Mark Fussell Date: Tue, 16 Jun 2026 18:03:01 -0700 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Mark Fussell --- .../content/en/reference/api/conversation_api.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/daprdocs/content/en/reference/api/conversation_api.md b/daprdocs/content/en/reference/api/conversation_api.md index 6d8872a563b..5b1e5720121 100644 --- a/daprdocs/content/en/reference/api/conversation_api.md +++ b/daprdocs/content/en/reference/api/conversation_api.md @@ -87,7 +87,7 @@ The `toolChoice` is an optional parameter that controls how the model can use av #### Metadata The `metadata` field is a set of up to 16 key-value pairs that can be attached to the conversation. This mirrors [OpenAI's `metadata` field](https://platform.openai.com/docs/api-reference/chat/create#chat-create-metadata) and is intended for storing additional information about the conversation in a structured format, such as user IDs, session IDs, or other application-specific tags. -This field is **not** a mechanism for overriding component configuration or passing authentication details such as API keys; provider credentials and connection settings belong in the component's YAML configuration file. +This field is **not** a mechanism for overriding component configuration or passing authentication details such as API keys; provider credentials and connection settings belong in the component's YAML configuration file. If you're migrating from older examples that pass `api_key` via `metadata`, move those values into the component configuration (or a referenced secret) instead. **Constraints:** @@ -98,10 +98,12 @@ This field is **not** a mechanism for overriding component configuration or pass **Example usage:** ```json -"metadata": { - "user_id": "user-1234", - "session_id": "session-abcd", - "environment": "production" +{ + "metadata": { + "user_id": "user-1234", + "session_id": "session-abcd", + "environment": "production" + } } ``` @@ -112,7 +114,7 @@ In addition to passing metadata in the request body, you can also pass metadata - **Multiple parameters**: Separate with `&` (e.g., `?metadata.user_id=user-1234&metadata.session_id=session-abcd`) Example: -```bash +```text POST http://localhost:3500/v1.0-alpha2/conversation/openai/converse?metadata.user_id=user-1234 ```