123 lines
3 KiB
Markdown
123 lines
3 KiB
Markdown
# @vercel/detect-agent
|
|
|
|
A lightweight utility for detecting if code is being executed by an AI agent or automated development environment.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install @vercel/detect-agent
|
|
```
|
|
|
|
## Usage
|
|
|
|
```typescript
|
|
import { determineAgent } from '@vercel/detect-agent';
|
|
|
|
const { isAgent, agent } = await determineAgent();
|
|
|
|
if (isAgent) {
|
|
console.log(`Running in ${agent.name} environment`);
|
|
// Adapt behavior for AI agent context
|
|
}
|
|
```
|
|
|
|
## Supported Agents
|
|
|
|
This package can detect the following AI agents and development environments:
|
|
|
|
- **Custom agents** via `AI_AGENT` environment variable
|
|
- **Cursor** (cursor editor and cursor-cli)
|
|
- **Claude Code** (Anthropic's Claude)
|
|
- **Devin** (Cognition Labs)
|
|
- **Gemini CLI** (Google)
|
|
- **Codex** (OpenAI)
|
|
- **Replit** (online IDE)
|
|
|
|
## The AI_AGENT Standard
|
|
|
|
We're promoting `AI_AGENT` as a universal environment variable standard for AI development tools. This allows any tool or library to easily detect when it's running in an AI-driven environment.
|
|
|
|
### For AI Tool Developers
|
|
|
|
Set the `AI_AGENT` environment variable to identify your tool:
|
|
|
|
```bash
|
|
export AI_AGENT="your-tool-name"
|
|
# or
|
|
AI_AGENT="your-tool-name" your-command
|
|
```
|
|
|
|
### Recommended Naming Convention
|
|
|
|
- Use lowercase with hyphens for multi-word names
|
|
- Include version information if needed, separated by an `@` symbol
|
|
- Examples: `claude-code`, `cursor-cli`, `devin@1`, `custom-agent@2.0`
|
|
|
|
## Use Cases
|
|
|
|
### Adaptive Behavior
|
|
|
|
```typescript
|
|
import { determineAgent } from '@vercel/detect-agent';
|
|
|
|
async function setupEnvironment() {
|
|
const { isAgent, agent } = await determineAgent();
|
|
|
|
if (isAgent) {
|
|
// Running in AI environment - adjust behavior
|
|
process.env.LOG_LEVEL = 'verbose';
|
|
console.log(`🤖 Detected AI agent: ${agent.name}`);
|
|
}
|
|
}
|
|
```
|
|
|
|
### Telemetry and Analytics
|
|
|
|
```typescript
|
|
import { determineAgent } from '@vercel/detect-agent';
|
|
|
|
async function trackUsage(event: string) {
|
|
const result = await determineAgent();
|
|
|
|
analytics.track(event, {
|
|
agent: result.isAgent ? result.agent.name : 'human',
|
|
timestamp: Date.now(),
|
|
});
|
|
}
|
|
```
|
|
|
|
### Feature Toggles
|
|
|
|
```typescript
|
|
import { determineAgent } from '@vercel/detect-agent';
|
|
|
|
async function shouldEnableFeature(feature: string) {
|
|
const result = await determineAgent();
|
|
|
|
// Enable experimental features for AI agents
|
|
if (result.isAgent && feature === 'experimental-ai-mode') {
|
|
return true;
|
|
}
|
|
|
|
return false;
|
|
}
|
|
```
|
|
|
|
## Contributing
|
|
|
|
We welcome contributions! Please see our [contributing guidelines](../../CONTRIBUTING.md).
|
|
|
|
### Adding New Agent Support
|
|
|
|
To add support for a new AI agent:
|
|
|
|
1. Add detection logic to `src/index.ts`
|
|
2. Add comprehensive test cases in `test/unit/determine-agent.test.ts`
|
|
3. Update this README with the new agent information
|
|
4. Follow the existing priority order pattern
|
|
|
|
## Links
|
|
|
|
- [GitHub Repository](https://github.com/vercel/vercel/tree/main/packages/detect-agent)
|
|
- [npm Package](https://www.npmjs.com/package/@vercel/detect-agent)
|
|
- [Vercel Documentation](https://vercel.com/docs)
|