chore: import upstream snapshot with attribution

.cursor/rules/agent-development.mdc

@@ -0,0 +1,103 @@
+---
+description:
+globs:
+alwaysApply: false
+---
+# CopilotKit Agent Development Guide
+
+## Agent Types
+
+### Python Agents
+Python agents are typically in folders named `agent-py/` or `agent/` and use the [sdk-python/](mdc:sdk-python/) package.
+
+#### Core Python SDK Components
+- **[copilotkit/agent.py](mdc:sdk-python/copilotkit/agent.py)** - Main agent class
+- **[copilotkit/action.py](mdc:sdk-python/copilotkit/action.py)** - Action definitions
+- **[copilotkit/crewai/](mdc:sdk-python/copilotkit/crewai/)** - CrewAI integration
+- **[copilotkit/integrations/](mdc:sdk-python/copilotkit/integrations/)** - Third-party integrations
+
+#### Python Agent Examples
+- **[coagents-starter/agent-py/](mdc:examples/coagents-starter/agent-py/)** - Basic Python agent setup
+- **[coagents-ai-researcher/agent/](mdc:examples/coagents-ai-researcher/agent/)** - Research agent with web scraping
+- **[coagents-travel/agent/](mdc:examples/coagents-travel/agent/)** - Travel planning agent
+- **[langgraph-tutorial-quickstart/agent-py/](mdc:examples/langgraph-tutorial-quickstart/agent-py/)** - LangGraph integration
+
+### JavaScript Agents
+JavaScript agents are in folders named `agent-js/` and use the [sdk-js/](mdc:packages/sdk-js/) package.
+
+#### JavaScript Agent Examples
+- **[coagents-starter/agent-js/](mdc:examples/coagents-starter/agent-js/)** - Basic JavaScript agent setup
+- **[coagents-qa-native/agent-js/](mdc:examples/coagents-qa-native/agent-js/)** - Native JavaScript QA agent
+- **[coagents-routing/agent-js/](mdc:examples/coagents-routing/agent-js/)** - Routing agent
+
+## Agent Patterns
+
+### Single Agent Pattern
+Simple agents that handle specific tasks:
+- File structure: `agent/main.py` or `agent/index.js`
+- Direct communication with frontend
+- Good for focused use cases
+
+### Multi-Agent (Coagents) Pattern
+Complex systems with multiple cooperating agents:
+- Multiple agent files or classes
+- Shared state management
+- Agent routing and coordination
+- Examples: [coagents-routing/](mdc:examples/coagents-routing/), [coagents-shared-state/](mdc:examples/coagents-shared-state/)
+
+### CrewAI Integration Pattern
+Using CrewAI for agent orchestration:
+- **Flows**: [coagents-starter-crewai-flows/](mdc:examples/coagents-starter-crewai-flows/)
+
+### LangGraph Integration Pattern
+Using LangGraph for agent state management:
+- **[langgraph-tutorial-quickstart/](mdc:examples/langgraph-tutorial-quickstart/)** - Basic LangGraph setup
+- **[langgraph-tutorial-customer-support/](mdc:examples/langgraph-tutorial-customer-support/)** - Customer support bot
+- Uses [langgraph.json](mdc:sdk-python/langgraph.json) for configuration
+
+## Agent Setup
+
+### Python Agent Setup
+1. Use [requirements-template.txt](mdc:examples/shared/requirements-template.txt) as a starting point
+2. Configure [pyproject-template.toml](mdc:examples/shared/pyproject-template.toml)
+3. Import from `copilotkit` package
+4. Define actions and agent logic
+
+### JavaScript Agent Setup
+1. Install `@copilotkit/sdk-js` package
+2. Configure TypeScript with proper types
+3. Define actions and agent endpoints
+4. Set up Express.js server or similar
+
+## Common Agent Features
+
+### Actions
+- Define functions that agents can call
+- Handle user interactions
+- Modify application state
+- Examples in action.py files across examples
+
+### State Management
+- Shared state between agents
+- Persistent state across conversations
+- Example: [coagents-shared-state/](mdc:examples/coagents-shared-state/)
+
+### User Input Handling
+- Wait for user input during agent execution
+- Interactive workflows
+- Example: [coagents-wait-user-input/](mdc:examples/coagents-wait-user-input/)
+
+### Integration Patterns
+- Vector databases (Pinecone, MongoDB Atlas)
+- LLM providers (OpenAI, Anthropic)
+- External APIs and services
+
+## Development Best Practices
+1. Start with a simple agent template
+2. Define clear actions and interfaces
+3. Handle errors gracefully
+4. Test with the corresponding UI example
+5. Use shared utilities from [examples/shared/](mdc:examples/shared/)
+6. Follow the established patterns in existing examples
+
+