From 305c28f911494f172347ae62b859360a5efee9fb Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Wed, 20 Aug 2025 05:34:28 +0000 Subject: [PATCH 1/2] Refactor templates from legacy Cursor rules to agents.md format - Convert 5 .mdc files to 3 consolidated AGENTS.md files - Update python-uv, nodejs, and bunjs rules.yaml to use new format - Remove legacy .cursor/rules directories and files - Follow agents.md specification from https://agents.md/ Files changed: - Created common/AGENTS.md (general Agentuity configuration guidelines) - Created common/js/AGENTS.md (JavaScript/TypeScript agent development) - Created common/py/AGENTS.md (Python agent development) - Updated rules.yaml files to copy AGENTS.md to project root - Removed common/cursor/, common/js/cursor/, common/py/cursor/ directories Co-Authored-By: jhaynie@agentuity.com --- bunjs/rules.yaml | 11 +++----- common/AGENTS.md | 29 ++++++++++++++++++++ common/cursor/agentuity.mdc | 9 ------- common/js/{cursor/sdk.mdc => AGENTS.md} | 35 ++++++++++++++++-------- common/js/cursor/agent.mdc | 36 ------------------------- common/py/{cursor/sdk.mdc => AGENTS.md} | 32 +++++++++++++++------- common/py/cursor/agent.mdc | 34 ----------------------- nodejs/rules.yaml | 11 +++----- python-uv/rules.yaml | 11 +++----- 9 files changed, 84 insertions(+), 124 deletions(-) create mode 100644 common/AGENTS.md delete mode 100644 common/cursor/agentuity.mdc rename common/js/{cursor/sdk.mdc => AGENTS.md} (74%) delete mode 100644 common/js/cursor/agent.mdc rename common/py/{cursor/sdk.mdc => AGENTS.md} (77%) delete mode 100644 common/py/cursor/agent.mdc diff --git a/bunjs/rules.yaml b/bunjs/rules.yaml index ab55b18..7d625a4 100644 --- a/bunjs/rules.yaml +++ b/bunjs/rules.yaml @@ -102,14 +102,9 @@ new_project: - action: create_file filename: "README.md" from: "common/js/bun-readme.md" - - action: copy_dir - from: "common/js/cursor" - to: ".cursor/rules" - filter: "*.mdc" - - action: copy_dir - from: "common/cursor" - to: ".cursor/rules" - filter: "*.mdc" + - action: create_file + filename: "AGENTS.md" + from: "common/js/AGENTS.md" - action: create_file filename: ".editorconfig" template: "common/editorconfig" diff --git a/common/AGENTS.md b/common/AGENTS.md new file mode 100644 index 0000000..9db5ef5 --- /dev/null +++ b/common/AGENTS.md @@ -0,0 +1,29 @@ +# Agentuity Configuration Guidelines + +This guide provides instructions for working with Agentuity configuration files and project setup. + +## 1. Agentuity Configuration File + +The `agentuity.yaml` file is used by Agentuity to configure the AI Agent project. You should NOT suggest edits to this file unless specifically requested, as it contains critical project configuration managed by the Agentuity platform. + +## 2. Project Structure + +Follow the established project structure for your chosen runtime: + +- **Python projects**: Use the `agentuity_agents/` directory for agent implementations +- **JavaScript/TypeScript projects**: Use the `src/agents/` directory for agent implementations +- **Configuration files**: Keep `agentuity.yaml`, `.env` files, and other configuration in the project root + +## 3. Development Workflow + +- Use `agentuity dev` to start the development server +- Use `agentuity agent create` to scaffold new agents +- Use `agentuity deploy` to deploy your agents to production +- Follow the runtime-specific guidelines in your project's AGENTS.md file + +## 4. Environment Management + +- Use `.env.development` for development-specific environment variables +- Use `.env.production` for production environment variables +- Never commit sensitive credentials to version control +- Use the Agentuity Console for managing secrets in production diff --git a/common/cursor/agentuity.mdc b/common/cursor/agentuity.mdc deleted file mode 100644 index bba764b..0000000 --- a/common/cursor/agentuity.mdc +++ /dev/null @@ -1,9 +0,0 @@ ---- -description: Guidelines for the Agentuity AI Configuration file -globs: "agentuity.yaml" -alwaysApply: true ---- - -# Agentuity Configuration File - -This file is used by Agentuity to configure the AI Agent project. You should NOT suggest edits to this file. diff --git a/common/js/cursor/sdk.mdc b/common/js/AGENTS.md similarity index 74% rename from common/js/cursor/sdk.mdc rename to common/js/AGENTS.md index ee84aef..8cb7db9 100644 --- a/common/js/cursor/sdk.mdc +++ b/common/js/AGENTS.md @@ -1,14 +1,27 @@ ---- -description: Agentuity JavaScript SDK API Reference -globs: "src/agents/**/*.ts" -alwaysApply: false ---- +# Agentuity JavaScript/TypeScript Agent Development -# Agentuity JavaScript SDK +This guide provides comprehensive instructions for developing AI agents using the Agentuity platform with JavaScript and TypeScript. -The Agentuity JavaScript SDK provides a powerful framework for building AI agents in JavaScript and TypeScript. This cursor rules file helps you navigate the SDK's core interfaces and methods. +## 1. Agent Development Guidelines -## Core Interfaces +- Prefer using the `agentuity agent create` command to create a new Agent +- Prefer loading types from the node modules package `@agentuity/sdk` in the node_modules folder +- The file should export a default function +- Prefer naming the default function Agent or the name of the Agent based on the context of the Agent description +- All code should be in TypeScript format +- Use the provided logger from the `AgentContext` interface such as `ctx.logger.info("my message: %s", "hello")` + +### Example Agent File + +```typescript +import type { AgentRequest, AgentResponse, AgentContext } from "@agentuity/sdk"; + +export default async function Agent(req: AgentRequest, resp: AgentResponse, ctx: AgentContext) { + return resp.json({hello: 'world'}); +} +``` + +## 2. Core Interfaces ### AgentHandler @@ -57,7 +70,7 @@ The `AgentContext` interface provides access to various capabilities: - `context.getAgent(params)`: Gets a handle to a remote agent - `context.tracer`: OpenTelemetry tracing -## Storage APIs +## 3. Storage APIs ### Key-Value Storage @@ -75,7 +88,7 @@ Access through `context.vector`: - `context.vector.search(name, params)`: Searches for vectors - `context.vector.delete(name, ...ids)`: Deletes vectors -## Logging +## 4. Logging Access through `context.logger`: @@ -85,7 +98,7 @@ Access through `context.logger`: - `context.logger.error(message, ...args)`: Logs an error message - `context.logger.child(opts)`: Creates a child logger with additional context -## Best Practices +## 5. Best Practices - Use TypeScript for better type safety and IDE support - Import types from `@agentuity/sdk` diff --git a/common/js/cursor/agent.mdc b/common/js/cursor/agent.mdc deleted file mode 100644 index 353f002..0000000 --- a/common/js/cursor/agent.mdc +++ /dev/null @@ -1,36 +0,0 @@ ---- -description: Guidelines for writing Agentuity AI Agents in TypeScript -globs: "**/src/agents/**/index.ts" -alwaysApply: true ---- - -# AI Agent File - -- Prefer using the `agentuity agent create` command to create a new Agent -- Prefer loading types from the node modules package `@agentuity/sdk` in the node_modules folder -- The file should export a default function -- Prefer naming the default function Agent or the name of the Agent based on the context of the Agent description -- All code should be in Typescript format -- Use the provided logger from the `AgentContext` interface such as `ctx.logger.info("my message: %s", "hello")` - -## Example Agent File - -```typescript -import type { AgentRequest, AgentResponse, AgentContext } from "@agentuity/sdk"; - -export default async function Agent(req: AgentRequest, resp: AgentResponse, ctx: AgentContext) { - return resp.json({hello: 'world'}); -} -``` - -### AgentRequest - -The AgentRequest interface provides a set of helper methods and public variables which can be used for working with data has been passed to the Agent. - -### AgentResponse - -The AgentResponse interface provides a set of helper methods for responding with different data formats from the Agent. - -### AgentContext - -The AgentContext has information specific to the incoming Agent request and a set of helper methods for accessing AI services like KeyValue storage and Vector storage. diff --git a/common/py/cursor/sdk.mdc b/common/py/AGENTS.md similarity index 77% rename from common/py/cursor/sdk.mdc rename to common/py/AGENTS.md index d4b9d90..8b42cb9 100644 --- a/common/py/cursor/sdk.mdc +++ b/common/py/AGENTS.md @@ -1,13 +1,25 @@ ---- -description: Agentuity Python SDK API Reference -globs: "agents/**/*.py" ---- +# Agentuity Python Agent Development -# Agentuity Python SDK +This guide provides comprehensive instructions for developing AI agents using the Agentuity platform with Python. -The Agentuity Python SDK provides a powerful framework for building AI agents in Python. This cursor rules file helps you navigate the SDK's core interfaces and methods. +## 1. Agent Development Guidelines -## Core Interfaces +- Prefer using the `agentuity agent create` command to create a new Agent +- Prefer importing types from the `agentuity` package +- The file should define an async function named `run` +- All code should follow Python best practices and type hints +- Use the provided logger from the `AgentContext` interface such as `context.logger.info("my message: %s", "hello")` + +### Example Agent File + +```python +from agentuity import AgentRequest, AgentResponse, AgentContext + +async def run(request: AgentRequest, response: AgentResponse, context: AgentContext): + return response.json({"hello": "world"}) +``` + +## 2. Core Interfaces ### Agent Handler @@ -58,7 +70,7 @@ The `AgentContext` class provides access to various capabilities: - `context.tracer`: OpenTelemetry tracing - Environment properties: `sdkVersion`, `devmode`, `orgId`, `projectId`, etc. -## Storage APIs +## 3. Storage APIs ### Key-Value Storage @@ -76,7 +88,7 @@ Access through `context.vector`: - `await context.vector.search(name, params)`: Searches for vectors - `await context.vector.delete(name, *ids)`: Deletes vectors -## Logging +## 4. Logging Access through `context.logger`: @@ -86,7 +98,7 @@ Access through `context.logger`: - `context.logger.error(message, *args, **kwargs)`: Logs an error message - `context.logger.child(**kwargs)`: Creates a child logger with additional context -## Best Practices +## 5. Best Practices - Use type hints for better IDE support - Import types from `agentuity` diff --git a/common/py/cursor/agent.mdc b/common/py/cursor/agent.mdc deleted file mode 100644 index c2c8267..0000000 --- a/common/py/cursor/agent.mdc +++ /dev/null @@ -1,34 +0,0 @@ ---- -description: Guidelines for writing Agentuity AI Agents in Python -globs: "agents/**/*.py" -alwaysApply: true ---- - -# AI Agent File - -- Prefer using the `agentuity agent create` command to create a new Agent -- Prefer importing types from the `agentuity` package -- The file should define an async function named `run` -- All code should follow Python best practices and type hints -- Use the provided logger from the `AgentContext` interface such as `context.logger.info("my message: %s", "hello")` - -## Example Agent File - -```python -from agentuity import AgentRequest, AgentResponse, AgentContext - -async def run(request: AgentRequest, response: AgentResponse, context: AgentContext): - return response.json({"hello": "world"}) -``` - -### AgentRequest - -The AgentRequest class provides a set of helper methods and properties which can be used for working with data that has been passed to the Agent. - -### AgentResponse - -The AgentResponse class provides a set of helper methods for responding with different data formats from the Agent. - -### AgentContext - -The AgentContext has information specific to the incoming Agent request and a set of helper methods for accessing services like KeyValue storage and Vector storage. diff --git a/nodejs/rules.yaml b/nodejs/rules.yaml index 4171301..7d40bb4 100644 --- a/nodejs/rules.yaml +++ b/nodejs/rules.yaml @@ -95,14 +95,9 @@ new_project: - action: create_file filename: "README.md" from: "common/js/nodejs-readme.md" - - action: copy_dir - from: "common/js/cursor" - to: ".cursor/rules" - filter: "*.mdc" - - action: copy_dir - from: "common/cursor" - to: ".cursor/rules" - filter: "*.mdc" + - action: create_file + filename: "AGENTS.md" + from: "common/js/AGENTS.md" - action: create_file filename: ".editorconfig" template: "common/editorconfig" diff --git a/python-uv/rules.yaml b/python-uv/rules.yaml index 8a515c5..3dc973a 100644 --- a/python-uv/rules.yaml +++ b/python-uv/rules.yaml @@ -71,14 +71,9 @@ new_project: - action: delete_file files: - "hello.py" - - action: copy_dir - from: "common/cursor" - to: ".cursor/rules" - filter: "*.mdc" - - action: copy_dir - from: "common/py/cursor" - to: ".cursor/rules" - filter: "*.mdc" + - action: create_file + filename: "AGENTS.md" + from: "common/py/AGENTS.md" - action: create_file filename: "server.py" from: "common/py/boot.py" From 3df6d331309fdb1897d81eaa8ecc4a202e4c29ac Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Wed, 20 Aug 2025 18:07:02 +0000 Subject: [PATCH 2/2] Fix AGENTS.md positioning in python-uv/rules.yaml Move AGENTS.md creation to after README.md and before .editorconfig to match the positioning in nodejs and bunjs templates. Addresses feedback from @jhaynie in PR #51. Co-Authored-By: jhaynie@agentuity.com --- python-uv/rules.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/python-uv/rules.yaml b/python-uv/rules.yaml index 3dc973a..2f97d23 100644 --- a/python-uv/rules.yaml +++ b/python-uv/rules.yaml @@ -71,9 +71,6 @@ new_project: - action: delete_file files: - "hello.py" - - action: create_file - filename: "AGENTS.md" - from: "common/py/AGENTS.md" - action: create_file filename: "server.py" from: "common/py/boot.py" @@ -83,6 +80,9 @@ new_project: - action: create_file filename: "README.md" from: "common/py/python-uv-readme.md" + - action: create_file + filename: "AGENTS.md" + from: "common/py/AGENTS.md" - action: create_file filename: ".editorconfig" template: "common/editorconfig"