refactor(agents): split tool resolution into native and action rails#20331
refactor(agents): split tool resolution into native and action rails#20331
Conversation
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
📊 API Changes ReportGraphQL Schema ChangesGraphQL Schema Changes[error] Error: Unable to read JSON file: /home/runner/work/twenty/twenty/main-schema-introspection.json: Not valid JSON content GraphQL Metadata Schema ChangesGraphQL Metadata Schema Changes[error] Error: Unable to read JSON file: /home/runner/work/twenty/twenty/main-metadata-schema-introspection.json: Not valid JSON content REST API Analysis ErrorError OutputREST Metadata API Analysis ErrorError Output |
1 participant
Summary
Splits AI agent tool resolution into two independent rails:
web_search, xAIweb/xprovider options). Bound byNativeToolBinderService, controlled by per-agentmodelConfigurationtoggles. Opaque to Twenty — executed on the model provider's servers.ToolRegistryService(Exa web search, code interpreter, send email, etc.). Permission-gated via roles, including the newWEB_SEARCH_TOOLflag. Executed on Twenty's server.Both rails merge into a single
ToolSetat call time. When both surfaces have a search tool, the model picks at runtime — coexistence is intentional.Notable changes worth calling out
Contract change:
AgentAsyncExecutorService.executeAgentno longer acceptsrolePermissionConfig. Workflow agents now scope exclusively by the agent's own permission-tab role (unionOf: [agentRoleId]). The previous role-merging path (caller role intersected with agent role) is removed. No agent role → no registry tools (fail-closed by design).NativeToolBinderServicerelocated fromcore-modules/tool-provider/native/→metadata-modules/ai/ai-models/services/. The binder needs SDK-package knowledge, which lives inai-models. Old location created a backwards module dependency.NATIVE_MODEL_TOOLS_BY_SDK_PACKAGEis exhaustive overAiSdkPackage(Record<>, notPartial<Record<>>). Adding a new SDK without thinking about native tools now fails the build. SDKs without native tools (Bedrock, Google, Mistral, Azure, OpenAI-compatible) get explicit{}entries.Discriminated union
kind: 'sdk-tool' | 'provider-option'lets one registry describe both function tools (Anthropic/OpenAI) and runtime sources (xAI). Follows the localtool-providerconvention from #19321.Conscious non-decisions
nativeis reserved for model/provider SDK features; everything Twenty-owned is just a tool/action.