feat(sdk): add runAgent() to run app agents from logic functions (#21157)

<img width="948" height="593" alt="image"
src="https://github.com/user-attachments/assets/d990fa98-3cfd-469d-ab7f-0b2d4ccf3afc"
/>

<img width="1361" height="802" alt="image"
src="https://github.com/user-attachments/assets/1091f598-49f3-4c16-92ea-1e1c200181e2"
/>


## Add `runAgent()` to the Logic Function SDK

Lets an app's logic function run one of its own AI agents server-side
and get the result back synchronously — reusing the existing agent
executor instead of a new bespoke transport.

  ### Backend
- New **`runAgent` GraphQL mutation** (metadata schema) in
`ai-agent-execution`, wrapping the existing
`AgentAsyncExecutorService.executeAgent`. Scopes the agent lookup to the
calling
  application and runs it under an application auth context.
- New `@AuthApplication()` param decorator (mirrors `@AuthWorkspace()`)
— first GraphQL resolver authenticated by an **application access
token**.
- Guarded by `WorkspaceAuthGuard` +
`SettingsPermissionGuard(PermissionFlagType.AI)`: the app's role must
grant the `AI` permission flag.

  ### SDK
- `runAgent({ agentUniversalIdentifier, prompt })` posts the mutation to
`/metadata` with the app token via a new runtime GraphQL transport.
Returns `{ result, hasNoMoreAvailableCredits
  }`.
- Refactored the connections helpers onto a shared `postAppEndpoint`
util (removes duplicated transport logic).

  ### Frontend
- App install permission modal now shows an explicit consent line —
_"Run AI agents and bill AI credits to your workspace"_ — when the app's
role requests the `AI` flag.

  ### Docs
- Documented `runAgent` and its `AI` permission-flag requirement in
_Skills & Agents_.
- Fixed outdated role-permission examples in _Roles & Permissions_
(`permissionFlags` → `permissionFlagUniversalIdentifiers`,
`PermissionFlag` → `SystemPermissionFlag`).

  ### Test plan
- [x] SDK unit tests (`run-agent.spec.ts`) — request shape, GraphQL/HTTP
error handling, missing env vars
- [x] `twenty-server`, `twenty-front`, `twenty-shared` typecheck + lint
- [ ] Manual: install an app granting the `AI` flag, call `runAgent()`
from a logic function, confirm the agent runs and credits are billed

---------

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>

packages/twenty-shared/src/ai/index.ts

@@ -15,6 +15,12 @@ export { DATA_RESIDENCY_KEYS } from './constants/data-residency.const';
 export type { NativeAiSdkProviderId } from './constants/native-ai-sdk-provider-ids.const';
 export { NATIVE_AI_SDK_PROVIDER_IDS } from './constants/native-ai-sdk-provider-ids.const';
 export { ToolCategory } from './constants/tool-category.const';
+export type {
+  AgentResponseFormatType,
+  AgentTextResponseFormat,
+  AgentJsonResponseFormat,
+  AgentResponseFormat,
+} from './types/agent-response-format.type';
 export type {
   AgentResponseFieldType,
   AgentResponseSchema,

packages/twenty-shared/src/ai/types/agent-response-format.type.ts

@@ -0,0 +1,12 @@
+import { type AgentResponseSchema } from '@/ai/types/agent-response-schema.type';
+
+export type AgentResponseFormatType = AgentResponseFormat['type'];
+
+export type AgentTextResponseFormat = { type: 'text' };
+export type AgentJsonResponseFormat = {
+  type: 'json';
+  schema: AgentResponseSchema;
+};
+export type AgentResponseFormat =
+  | AgentTextResponseFormat
+  | AgentJsonResponseFormat;

packages/twenty-shared/src/application/agentManifestType.ts

@@ -1,3 +1,4 @@
+import { type AgentResponseFormat } from '@/ai/types/agent-response-format.type';
 import { type SyncableEntityOptions } from '@/application/syncableEntityOptionsType';
 
 export type AgentManifest = SyncableEntityOptions & {
@@ -7,4 +8,5 @@ export type AgentManifest = SyncableEntityOptions & {
   description?: string;
   prompt: string;
   modelId?: string;
+  responseFormat?: AgentResponseFormat;
 };

packages/twenty-shared/src/application/index.ts

@@ -66,6 +66,7 @@ export type {
   FieldPermissionManifest,
   RoleManifest,
 } from './roleManifestType';
+export type { RunAgentInput, RunAgentResult } from './runAgentType';
 export type { ServerVariables } from './server-variables.type';
 export type { SkillManifest } from './skillManifestType';
 export type { StoredOAuthConnectionProviderConfig } from './storedOAuthConnectionProviderConfigType';

packages/twenty-shared/src/application/runAgentType.ts

@@ -0,0 +1,10 @@
+export type RunAgentInput = {
+  agentUniversalIdentifier: string;
+  prompt: string;
+};
+
+export type RunAgentResult = {
+  result: object | null;
+  error: string | null;
+  success: boolean;
+};