|
1 | | -# Model Context Protocols (MCP) and adding AI tools |
| 1 | +# Best Practices |
2 | 2 |
|
3 | | -> [!NOTE] |
4 | | -> |
5 | | -> This functionality is in beta and is evolving rapidly. |
6 | | -> |
7 | | -> When using any AI tool for development, exercise a level of caution appropriate to your use case and environment. |
8 | | -> Always review AI-generated content before using it in critical systems. |
9 | | -> |
10 | | -> Join our [Discord channel](https://discord.gg/coder) or |
11 | | -> [contact us](https://coder.com/contact) to get help or share feedback. |
| 3 | +This document includes a mix of cultural and technical best practices and guidelines for introducing AI agents into your organization. |
12 | 4 |
|
13 | | -## Overview |
| 5 | +## Identify Use Cases |
14 | 6 |
|
15 | | -Coder templates should be pre-equipped with the tools and dependencies needed |
16 | | -for development. With AI Agents, this is no exception. |
| 7 | +To successfully implement AI coding agents, identify 3-5 practical use cases where AI tools can deliver real value. Additionally, find a target group of developers and projects that are the best candidates for each specific use case. |
17 | 8 |
|
18 | | -## Prerequisites |
| 9 | +Below are common scenarios where AI coding agents provide the most impact, along with the right tools for each use case: |
19 | 10 |
|
20 | | -- A Coder deployment with v2.21 or later |
21 | | -- A [template configured for AI agents](./create-template.md) |
| 11 | +| Scenario | Description | Examples | Tools | |
| 12 | +|------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------| |
| 13 | +| **Automating actions in the IDE** | Supplement tedious development with agents | Small refactors, generating unit tests, writing inline documentation, code search and navigation | [IDE Agents](./ide-agents.md) in Workspaces | |
| 14 | +| **Developer-led investigation and setup** | Developers delegate research and initial implementation to AI, then take over in their preferred IDE to complete the work | Bug triage and analysis, exploring technical approaches, understanding legacy code, creating starter implementations | [Tasks](./tasks.md), to a full IDE with [Workspaces](../user-guides/workspace-access/index.md) | |
| 15 | +| **Prototyping & Business Applications** | User-friendly interface for engineers and non-technical users to build and prototype within new or existing codebases | Creating dashboards, building simple web apps, data analysis workflows, proof-of-concept development | [Tasks](./tasks.md) | |
| 16 | +| **Full background jobs & long-running agents** | Agents that run independently without user interaction for extended periods of time | Automated code reviews, scheduled data processing, continuous integration tasks, monitoring and alerting | [Tasks](./tasks.md) API *(in development)* | |
| 17 | +| **External agents and chat clients** | External AI agents and chat clients that need access to Coder workspaces for development environments and code sandboxing | ChatGPT, Claude Desktop, custom enterprise agents running tests, performing development tasks, code analysis | [MCP Server](./mcp-server.md) | |
22 | 18 |
|
23 | | -## Best Practices |
| 19 | +## Provide Agents with Proper Context |
24 | 20 |
|
25 | | -- Use the most capable ML models you have access to in order to evaluate Agent |
26 | | - performance. |
27 | | -- Set a system prompt with the `AI_SYSTEM_PROMPT` environment in your template |
28 | | -- Within your repositories, write a `.cursorrules`, `CLAUDE.md` or similar file |
29 | | - to guide the agent's behavior. |
30 | | -- To read issue descriptions or pull request comments, install the proper CLI |
31 | | - (e.g. `gh`) in your image/template. |
32 | | -- Ensure your [template](./create-template.md) is truly pre-configured for |
33 | | - development without manual intervention (e.g. repos are cloned, dependencies |
34 | | - are built, secrets are added/mocked, etc.). |
| 21 | +While LLMs are trained on general knowledge, it's important to provide additional context to help agents understand your codebase and organization. |
35 | 22 |
|
36 | | - > Note: [External authentication](../admin/external-auth/index.md) can be helpful |
37 | | - > to authenticate with third-party services such as GitHub or JFrog. |
| 23 | +### Memory |
38 | 24 |
|
39 | | -- Give your agent the proper tools via MCP to interact with your codebase and |
40 | | - related services. |
41 | | -- Read our recommendations on [securing agents](./securing.md) to avoid |
42 | | - surprises. |
| 25 | +Coding Agents like Claude Code often refer to a [memory file](https://docs.anthropic.com/en/docs/claude-code/memory) in order to gain context about your repository or organization. |
43 | 26 |
|
44 | | -## Adding Tools via MCP |
| 27 | +Look up the docs for the specific agent you're using to learn more about how to provide context to your agents. |
45 | 28 |
|
46 | | -Model Context Protocol (MCP) is an emerging standard for adding tools to your |
47 | | -agents. |
| 29 | +### Tools (Model Context Protocol) |
48 | 30 |
|
49 | | -Follow the documentation for your [agent](./agents.md) to learn how to configure |
50 | | -MCP servers. See |
51 | | -[modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) |
52 | | -to browse open source MCP servers. |
| 31 | +Agents can also use tools, often via [Model Context Protocol](https://modelcontextprotocol.io/introduction) to look up information or perform actions. A common example would be fetching style guidelines from an internal wiki, or looking up the documentation for a service within your catalog. |
53 | 32 |
|
54 | | -### Our Favorite MCP Servers |
| 33 | +Look up the docs for the specific agent you're using to learn more about how to provide tools to your agents. |
55 | 34 |
|
56 | | -In internal testing, we have seen significant improvements in agent performance |
57 | | -when these tools are added via MCP. |
| 35 | +#### Our Favorite MCP Servers |
| 36 | + |
| 37 | +In internal testing, we have seen significant improvements in agent performance when these tools are added via MCP. |
58 | 38 |
|
59 | 39 | - [Playwright](https://github.com/microsoft/playwright-mcp): Instruct your agent |
60 | 40 | to open a browser, and check its work by viewing output and taking |
61 | 41 | screenshots. |
62 | 42 | - [desktop-commander](https://github.com/wonderwhy-er/DesktopCommanderMCP): |
63 | | - Instruct your agent to run long-running tasks (e.g. `npm run dev`) in the |
64 | | - background instead of blocking the main thread. |
| 43 | + Instruct your agent to run long-running tasks (e.g. `npm run dev`) in the background instead of blocking the main thread. |
| 44 | + |
| 45 | +## Security & Permissions |
| 46 | + |
| 47 | +LLMs and agents can be dangerous if not run with proper boundaries. Be sure not to give agents full permissions on behalf of a user, and instead use separate identities with limited scope whenever interacting autonomously. |
| 48 | + |
| 49 | +[Learn more about securing agents with Coder Tasks](./security.md) |
65 | 50 |
|
66 | | -## Next Steps |
| 51 | +## Keep it Simple |
67 | 52 |
|
68 | | -- [Supervise Agents in the UI](./coder-dashboard.md) |
69 | | -- [Supervise Agents in the IDE](./ide-integration.md) |
70 | | -- [Supervise Agents Programmatically](./headless.md) |
71 | | -- [Securing Agents](./securing.md) |
| 53 | +Today's LLMs and AI agents are not going to refactor entire codebases with production-grade code on their own! Using coding agents can be extremely fun and productive, but it is important to keep the scope of your use cases small and simple, and grow them over time. |
0 commit comments