Conversation
…ng, auth, and usage details
Documentation Review SummaryThank you for this comprehensive expansion of the Custom Actions documentation! The added implementation details about versioning, constraints, and OpenAPI parsing are valuable for both users and developers. Required Changes (4 issues)
Notable Suggestions
I'll post inline comments on the specific lines. Once the required changes are addressed, this will be a significant improvement to the docs. Review powered by Claude Code documentation-pr-reviewer agent |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| If the external API requires authentication, create an Authentication Provider in Team Settings and attach it to the Custom Action. If no auth provider is configured the action will use an anonymous auth service. | ||
|
|
||
| [auth_providers]: team/authentication_providers.md | ||
| See: docs/team/authentication_providers.md |
There was a problem hiding this comment.
Fix broken link format (Required)
This link format won't work in MkDocs. Use proper relative markdown link syntax:
| See: docs/team/authentication_providers.md | |
| See [Authentication Providers](team/authentication_providers.md) for details on creating and configuring authentication. |
| Custom Actions enable bots to communicate with external services via HTTP API calls. This feature allows you to extend the functionality of your bot by integrating it with other services. | ||
|
|
||
| This feature is analogous to the OpenAI's [GPT Actions](https://platform.openai.com/docs/actions/introduction) feature. | ||
| This feature is analogous to the OpenAI's GPT Actions feature. |
There was a problem hiding this comment.
Consider restoring the external link (Suggestion)
The removed hyperlink to OpenAI's GPT Actions documentation provided helpful context. Consider keeping it:
| This feature is analogous to the OpenAI's GPT Actions feature. | |
| This feature is analogous to the OpenAI's [GPT Actions](https://platform.openai.com/docs/actions/introduction) feature. |
External references help users understand the broader context.
| ### API Schema (OpenAPI) | ||
|
|
||
| Provide a JSON or YAML OpenAPI schema that describes the API. The platform parses the schema on save and extracts operations. The schema must be a valid OpenAPI document (FastAPI's /openapi.json works). |
There was a problem hiding this comment.
Add actionable guidance (Required)
Expand this to help users understand what causes validation failures:
| ### API Schema (OpenAPI) | |
| Provide a JSON or YAML OpenAPI schema that describes the API. The platform parses the schema on save and extracts operations. The schema must be a valid OpenAPI document (FastAPI's /openapi.json works). | |
| Provide a JSON or YAML OpenAPI schema that describes the API. The platform parses the schema on save and extracts operations. The schema must be a valid OpenAPI document (FastAPI's /openapi.json works). | |
| If the schema cannot be parsed, the save will fail with a validation error. Common issues include invalid JSON/YAML syntax, missing required OpenAPI fields (e.g., `openapi` version, `paths`, `info`), or non-standard operation definitions. Check the error message displayed in the UI for specific validation failures. |
|
|
||
| ## How Custom Actions work (detailed) | ||
|
|
||
| - The CustomAction model stores the server_url, api_schema, optional auth_provider, and derived operations. When a Custom Action is saved the OpenAPI schema is parsed and the available operations are computed and stored in-memory for the working version. |
There was a problem hiding this comment.
Clarify "working version" terminology (Required)
The versioning documentation uses "unreleased version" consistently. Either define "working version" here or align with existing terminology for consistency.
Suggestion: Replace "working version" with "unreleased version" throughout (here and on line 50).
|
|
||
| - When running, each CustomActionOperation is converted into a "tool" that is passed to the LLM agent. The tool knows how to build and send the HTTP request for that operation (see apps.chat.agent.openapi_tool.FunctionDef.build_tool). | ||
|
|
||
| - API responses are returned to the LLM as text. If the remote response includes a Content-Disposition header indicating a file download, the file is downloaded and handled accordingly. |
There was a problem hiding this comment.
Clarify file handling (Suggestion)
"handled accordingly" is vague. Be specific about what happens to downloaded files:
| - API responses are returned to the LLM as text. If the remote response includes a Content-Disposition header indicating a file download, the file is downloaded and handled accordingly. | |
| - API responses are returned to the LLM as text. If the remote response includes a Content-Disposition header indicating a file download, the file is downloaded and passed to the LLM as an attachment (depending on the LLM's file handling capabilities). |
Or if files aren't fully supported, state that explicitly.
|
|
||
| - API responses are returned to the LLM as text. If the remote response includes a Content-Disposition header indicating a file download, the file is downloaded and handled accordingly. | ||
|
|
||
| ## Permissions, constraints, and usage notes |
There was a problem hiding this comment.
Consider section rename (Suggestion)
This section doesn't actually cover "Permissions" - only constraints and limitations. Consider:
| ## Permissions, constraints, and usage notes | |
| ## Constraints and limitations |
- Remove internal implementation details (models, database constraints) - Focus on user-facing concepts and UI workflow - Keep technical depth but explain from user's point of view - Add troubleshooting and best practices sections
|
@snopoke I will see if anything useful here to add to docs. Then we can close this out. |
2 participants
Summary
This PR expands the custom actions documentation based on a thorough review of the implementation in
apps/custom_actions.Changes
Updated
docs/concepts/custom_actions.mdwith:FunctionDef.build_tool)Background
The existing docs were brief and missing important implementation details that users and developers need to understand how custom actions work, especially around versioning, constraints, and the OpenAPI parsing behavior.
Review Notes
apps/custom_actions(models, schema_utils, forms, views)cc: @skelly (requested via research task)