feat(agent-toolkit): agents subgraph tools expansion

packages/agent-toolkit/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 5.11.0
+
+### Add agent management tools
+
+Six new tools enabling agents to create and manage monday.com platform agents end-to-end:
+
+- `manage_agent_state` — activate, deactivate, or manually trigger a run
+- `manage_agent_knowledge` — grant, update, or revoke a board/doc access for an agent
+- `manage_agent_skills` — create account-wide skills and attach/detach them to agents
+- `manage_agent_triggers` — list, add, or remove triggers; catalog lookup workflow built in
+- `get_agent_catalog` — fetch available trigger types and skills from the account catalog
+- Extended `update_agent` with `agent_id` naming alignment, enum-safe `agent_model`, empty-input guard, and consistent return shape
+
 ## 5.7.1
 
 ### form_questions_editor — fix ConditionOperator and remove existing_column_id

packages/agent-toolkit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/agent-toolkit",
-  "version": "5.10.3",
+  "version": "5.11.0",
 
 
   "description": "monday.com agent toolkit",

packages/agent-toolkit/src/core/tools/platform-api-tools/agents-tools/create-agent-skill/create-agent-skill-tool.test.ts

@@ -0,0 +1,79 @@
+import { MondayAgentToolkit } from 'src/mcp/toolkit';
+import { callToolByNameRawAsync, createMockApiClient, parseToolResult } from '../../test-utils/mock-api-client';
+import { CreateAgentSkillMutation } from 'src/monday-graphql/generated/graphql.dev/graphql';
+
+const mockSkill = { id: 'skill-123', name: 'Send Slack Message', description: 'Posts to Slack' };
+
+describe('CreateAgentSkillTool', () => {
+  let mocks: ReturnType<typeof createMockApiClient>;
+
+  beforeEach(() => {
+    mocks = createMockApiClient();
+    jest.spyOn(MondayAgentToolkit.prototype as any, 'createApiClient').mockReturnValue(mocks.mockApiClient);
+  });
+
+  it('should create a skill and return it', async () => {
+    mocks.setResponseOnce({ create_agent_skill: mockSkill } as CreateAgentSkillMutation);
+
+    const result = await callToolByNameRawAsync('create_agent_skill', {
+      name: 'Send Slack Message',
+      content: '## Instructions\nPost a message.',
+    });
+    const parsed = parseToolResult(result);
+
+    expect(parsed.skill.id).toBe('skill-123');
+  });
+
+  it('should pass name, content, and description to the mutation', async () => {
+    mocks.setResponseOnce({ create_agent_skill: mockSkill } as CreateAgentSkillMutation);
+
+    await callToolByNameRawAsync('create_agent_skill', {
+      name: 'Send Slack Message',
+      content: '## Instructions\nPost a message.',
+      description: 'Posts to Slack',
+    });
+
+    expect(mocks.getMockRequest()).toHaveBeenCalledWith(
+      expect.stringContaining('createAgentSkill'),
+      { name: 'Send Slack Message', content: '## Instructions\nPost a message.', description: 'Posts to Slack' },
+      expect.objectContaining({ versionOverride: 'dev' }),
+    );
+  });
+
+  it('should pass versionOverride dev', async () => {
+    mocks.setResponseOnce({ create_agent_skill: mockSkill } as CreateAgentSkillMutation);
+
+    await callToolByNameRawAsync('create_agent_skill', {
+      name: 'Send Slack Message',
+      content: '## Instructions',
+    });
+
+    expect(mocks.getMockRequest()).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.anything(),
+      expect.objectContaining({ versionOverride: 'dev' }),
+    );
+  });
+
+  it('should throw when create_agent_skill returns null', async () => {
+    mocks.setResponseOnce({ create_agent_skill: null } as CreateAgentSkillMutation);
+
+    const result = await callToolByNameRawAsync('create_agent_skill', {
+      name: 'Send Slack Message',
+      content: '## Instructions',
+    });
+
+    expect(result.content[0].text).toContain('create_agent_skill returned no data');
+  });
+
+  it('should propagate API errors with context', async () => {
+    mocks.setError('API error');
+
+    const result = await callToolByNameRawAsync('create_agent_skill', {
+      name: 'Send Slack Message',
+      content: '## Instructions',
+    });
+
+    expect(result.content[0].text).toContain('Failed to create monday platform agent skill');
+  });
+});

packages/agent-toolkit/src/core/tools/platform-api-tools/agents-tools/create-agent-skill/create-agent-skill-tool.ts

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+import {
+  CreateAgentSkillMutation,
+  CreateAgentSkillMutationVariables,
+} from '../../../../../monday-graphql/generated/graphql.dev/graphql';
+import { createAgentSkillMutation } from './create-agent-skill.graphql.dev';
+import { ToolInputType, ToolOutputType, ToolType } from '../../../../tool';
+import { BaseMondayApiTool, createMondayApiAnnotations } from '../../base-monday-api-tool';
+import { rethrowWithContext } from '../../../../../utils';
+
+export const createAgentSkillToolSchema = {
+  name: z.string().trim().min(1).describe('Display name of the new skill.'),
+  content: z
+    .string()
+    .trim()
+    .min(1)
+    .describe('Markdown instructions defining what the skill does and how to execute it.'),
+  description: z
+    .string()
+    .trim()
+    .min(1)
+    .optional()
+    .describe('Short description of the skill shown in the catalog.'),
+};
+
+export class CreateAgentSkillTool extends BaseMondayApiTool<typeof createAgentSkillToolSchema> {
+  name = 'create_agent_skill';
+  type = ToolType.WRITE;
+  annotations = createMondayApiAnnotations({
+    title: 'Create monday Platform Agent Skill',
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+  });
+
+  getDescription(): string {
+    return `Create a new custom skill in the account-wide skill catalog.
+
+Skills extend what an agent can do — for example, sending emails, searching the web, or querying databases. A skill created here is available to all agents in the account.
+
+After creating a skill, use manage_agent_skills with action:"add" and the returned id to attach it to a specific agent.
+
+USAGE EXAMPLE:
+- { "name": "Send Slack Message", "content": "## Instructions\\nPost a message to a Slack channel.", "description": "Sends a message to Slack" }`;
+  }
+
+  getInputSchema() {
+    return createAgentSkillToolSchema;
+  }
+
+  protected async executeInternal(
+    input: ToolInputType<typeof createAgentSkillToolSchema>,
+  ): Promise<ToolOutputType<never>> {
+    try {
+      const variables: CreateAgentSkillMutationVariables = {
+        name: input.name,
+        content: input.content,
+        description: input.description,
+      };
+      const res = await this.mondayApi.request<CreateAgentSkillMutation>(createAgentSkillMutation, variables, {
+        versionOverride: 'dev',
+      });
+      if (!res.create_agent_skill) {
+        throw new Error('create_agent_skill returned no data');
+      }
+      return {
+        content: {
+          message: 'Skill created. Use the returned id with manage_agent_skills action:add to attach it to an agent.',
+          skill: res.create_agent_skill,
+        },
+      };
+    } catch (error) {
+      rethrowWithContext(error, 'create monday platform agent skill');
+    }
+  }
+}

packages/agent-toolkit/src/core/tools/platform-api-tools/agents-tools/create-agent-skill/create-agent-skill.graphql.dev.ts

@@ -0,0 +1,11 @@
+import { gql } from 'graphql-request';
+
+export const createAgentSkillMutation = gql`
+  mutation createAgentSkill($name: String!, $content: String!, $description: String) {
+    create_agent_skill(name: $name, content: $content, description: $description) {
+      id
+      name
+      description
+    }
+  }
+`;

packages/agent-toolkit/src/core/tools/platform-api-tools/agents-tools/create-agent/create-agent-tool.ts

@@ -80,7 +80,7 @@ Two modes:
 
 Do not mix prompt with manual profile fields in one request.
 
-Created agents start in state INACTIVE and must be activated before they can be triggered. Instruct the user to activate from the monday.com agent settings UI.
+Created agents start in state INACTIVE and must be activated before they can be triggered. After creation, call manage_agent_state with action:activate and the returned agent id.
 
 created_at and updated_at are null in the response — call get_agent with the returned id afterward to fetch them.
 
@@ -137,7 +137,7 @@ USAGE EXAMPLES:
 
         return {
           content: {
-            message: `monday platform agent ${res.create_blank_agent.id} created in state INACTIVE — user must activate it from the monday.com UI before it can be triggered`,
+            message: `monday platform agent ${res.create_blank_agent.id} created in state INACTIVE — call manage_agent_state with action:activate and agent_id:${res.create_blank_agent.id} to activate it`,
             agent: res.create_blank_agent,
           },
         };
@@ -165,7 +165,7 @@ USAGE EXAMPLES:
 
       return {
         content: {
-          message: `monday platform agent ${res.create_agent.id} created in state INACTIVE — user must activate it from the monday.com UI before it can be triggered`,
+          message: `monday platform agent ${res.create_agent.id} created in state INACTIVE — call manage_agent_state with action:activate and agent_id:${res.create_agent.id} to activate it`,
           agent: res.create_agent,
         },
       };

packages/agent-toolkit/src/core/tools/platform-api-tools/agents-tools/get-agent-catalog/get-agent-catalog-tool.test.ts

@@ -0,0 +1,108 @@
+import { MondayAgentToolkit } from 'src/mcp/toolkit';
+import { callToolByNameRawAsync, createMockApiClient, parseToolResult } from '../../test-utils/mock-api-client';
+import { GetAgentTriggersCatalogQuery, GetAgentSkillsCatalogQuery } from 'src/monday-graphql/generated/graphql.dev/graphql';
+
+describe('GetAgentCatalogTool', () => {
+  let mocks: ReturnType<typeof createMockApiClient>;
+
+  beforeEach(() => {
+    mocks = createMockApiClient();
+    jest.spyOn(MondayAgentToolkit.prototype as any, 'createApiClient').mockReturnValue(mocks.mockApiClient);
+  });
+
+  const mockTrigger = {
+    block_reference_id: 'status-change-ref',
+    name: 'Status Change',
+    description: 'Fires when a status column changes',
+    field_schemas: [{ field_key: 'board_id', value_schema: 'The ID of the board to watch' }],
+    required_fields: [{ field_key: 'board_id', depends_on: [], optional: false }],
+  };
+
+  const mockSkill = {
+    id: 'skill-1',
+    name: 'Board Manager',
+    description: 'Manages boards and items',
+  };
+
+  it('should return triggers catalog when type is triggers', async () => {
+    mocks.setResponseOnce({ agent_triggers_catalog: [mockTrigger] } as GetAgentTriggersCatalogQuery);
+
+    const result = await callToolByNameRawAsync('get_agent_catalog', { type: 'triggers' });
+    const parsed = parseToolResult(result);
+
+    expect(parsed.count).toBe(1);
+    expect(parsed.triggers[0].block_reference_id).toBe('status-change-ref');
+  });
+
+  it('should pass versionOverride dev when fetching triggers', async () => {
+    mocks.setResponseOnce({ agent_triggers_catalog: [] } as GetAgentTriggersCatalogQuery);
+
+    await callToolByNameRawAsync('get_agent_catalog', { type: 'triggers' });
+
+    expect(mocks.getMockRequest()).toHaveBeenCalledWith(
+      expect.stringContaining('getAgentTriggersCatalog'),
+      expect.objectContaining({ block_reference_ids: undefined }),
+      expect.objectContaining({ versionOverride: 'dev' }),
+    );
+  });
+
+  it('should pass block_reference_ids when provided', async () => {
+    mocks.setResponseOnce({ agent_triggers_catalog: [mockTrigger] } as GetAgentTriggersCatalogQuery);
+
+    await callToolByNameRawAsync('get_agent_catalog', { type: 'triggers', block_reference_ids: ['status-change-ref'] });
+
+    expect(mocks.getMockRequest()).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ block_reference_ids: ['status-change-ref'] }),
+      expect.anything(),
+    );
+  });
+
+  it('should return skills catalog when type is skills', async () => {
+    mocks.setResponseOnce({ agent_skills_catalog: [mockSkill] } as GetAgentSkillsCatalogQuery);
+
+    const result = await callToolByNameRawAsync('get_agent_catalog', { type: 'skills' });
+    const parsed = parseToolResult(result);
+
+    expect(parsed.count).toBe(1);
+    expect(parsed.skills[0].id).toBe('skill-1');
+  });
+
+  it('should pass versionOverride dev when fetching skills', async () => {
+    mocks.setResponseOnce({ agent_skills_catalog: [] } as GetAgentSkillsCatalogQuery);
+
+    await callToolByNameRawAsync('get_agent_catalog', { type: 'skills' });
+
+    expect(mocks.getMockRequest()).toHaveBeenCalledWith(
+      expect.stringContaining('getAgentSkillsCatalog'),
+      expect.anything(),
+      expect.objectContaining({ versionOverride: 'dev' }),
+    );
+  });
+
+  it('should return empty list with count 0 when no triggers exist', async () => {
+    mocks.setResponseOnce({ agent_triggers_catalog: [] } as GetAgentTriggersCatalogQuery);
+
+    const result = await callToolByNameRawAsync('get_agent_catalog', { type: 'triggers' });
+    const parsed = parseToolResult(result);
+
+    expect(parsed.count).toBe(0);
+    expect(parsed.triggers).toEqual([]);
+  });
+
+  it('should propagate errors when fetching triggers catalog', async () => {
+    mocks.setError('Unauthorized');
+
+    const result = await callToolByNameRawAsync('get_agent_catalog', { type: 'triggers' });
+
+    expect(result.content[0].text).toContain('Failed to fetch monday platform agent triggers catalog');
+  });
+
+  it('should propagate errors when fetching skills catalog', async () => {
+    mocks.setError('Unauthorized');
+
+    const result = await callToolByNameRawAsync('get_agent_catalog', { type: 'skills' });
+
+    expect(result.content[0].text).toContain('Failed to fetch monday platform agent skills catalog');
+  });
+});