Skip to content

Commit 4a1fd5d

Browse files
OskarStarkOskarStark
committed
feature #497 Add AGENTS.md with optimized guidance for AI agents (OskarStark)
This PR was squashed before being merged into the main branch. Discussion ---------- Add `AGENTS.md` with optimized guidance for AI agents | Q | A | ------------- | --- | Bug fix? | no | New feature? | yes | Docs? | no | Issues | Fix #437 | License | MIT - Streamlined content from `CLAUDE.md` for better AI agent consumption - Organized essential commands, code standards, and workflow rules - Focused on component architecture and development practices - Maintained all critical guidelines in more concise format Commits ------- 42162c8 Add `AGENTS.md` with optimized guidance for AI agents
2 parents 31a4b03 + 42162c8 commit 4a1fd5d

File tree

7 files changed

+536
-0
lines changed

7 files changed

+536
-0
lines changed

‎AGENTS.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# AGENTS.md
2+
3+
This file provides guidance to AI agents when working with code in this repository.
4+
5+
## Project Overview
6+
7+
Symfony AI monorepo with independent packages for AI integration in PHP applications. Each component in `src/` has its own composer.json, tests, and dependencies.
8+
9+
## Architecture
10+
11+
### Core Components
12+
- **Platform** (`src/platform/`): Unified AI platform interface (OpenAI, Anthropic, Azure, Gemini, VertexAI)
13+
- **Agent** (`src/agent/`): AI agent framework for user interaction and task execution
14+
- **Store** (`src/store/`): Data storage abstraction with vector database support
15+
- **MCP SDK** (`src/mcp-sdk/`): Model Context Protocol SDK for agent-tool communication
16+
17+
### Integration Bundles
18+
- **AI Bundle** (`src/ai-bundle/`): Symfony integration for Platform, Store, and Agent
19+
- **MCP Bundle** (`src/mcp-bundle/`): Symfony integration for MCP SDK
20+
21+
### Supporting Directories
22+
- **Examples** (`examples/`): Standalone usage examples
23+
- **Demo** (`demo/`): Full Symfony web application demo
24+
- **Fixtures** (`fixtures/`): Shared multi-modal test fixtures
25+
26+
## Essential Commands
27+
28+
### Testing
29+
```bash
30+
# Component-specific testing
31+
cd src/platform && vendor/bin/phpunit
32+
cd src/agent && vendor/bin/phpunit
33+
cd src/ai-bundle && vendor/bin/phpunit
34+
cd demo && vendor/bin/phpunit
35+
```
36+
37+
### Code Quality
38+
```bash
39+
# Fix code style (always run after changes)
40+
vendor/bin/php-cs-fixer fix
41+
42+
# Static analysis (component-specific)
43+
cd src/platform && vendor/bin/phpstan analyse
44+
```
45+
46+
### Development Tools
47+
```bash
48+
# Link components for development
49+
./link /path/to/project
50+
51+
# Run examples
52+
cd examples && php anthropic/chat.php
53+
54+
# Demo application
55+
cd demo && symfony server:start
56+
```
57+
58+
## Code Standards
59+
60+
### PHP Conventions
61+
- Follow Symfony coding standards with `@Symfony` PHP CS Fixer rules
62+
- Use project-specific exceptions instead of global ones (`\RuntimeException`, `\InvalidArgumentException`)
63+
- Define array shapes for parameters and return types
64+
- Add `@author` tags to new classes
65+
- Always add newlines at end of files
66+
67+
### Testing Guidelines
68+
- Use **PHPUnit 11+** with component-specific configurations
69+
- Prefer `MockHttpClient` over response mocking
70+
- Use `self::assert*` or `$this->assert*` in tests
71+
- No void return types for test methods
72+
- Leverage shared fixtures in `/fixtures` for multi-modal content
73+
- Always fix risky tests
74+
75+
### Git & Commits
76+
- Never mention AI assistance in commits or PR descriptions
77+
- Sign commits with GPG
78+
- Use conventional commit messages
79+
80+
### Variable Naming
81+
- Name MessageBus variables as `$bus` (not `$messageBus`)
82+
83+
## Component Dependencies
84+
85+
- Agent → Platform (AI communication)
86+
- AI Bundle → Platform + Agent + Store (integration)
87+
- MCP Bundle → MCP SDK (integration)
88+
- Store: standalone (often used with Agent for RAG)
89+
90+
## Development Workflow
91+
92+
1. Each `src/` component is independently versioned
93+
2. Use `@dev` versions for internal dependencies during development
94+
3. Run PHP-CS-Fixer after code changes
95+
4. Test component-specific changes in isolation
96+
5. Use monorepo structure for shared development workflow

‎demo/AGENTS.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# AGENTS.md
2+
3+
AI agent guidance for the Symfony AI demo application.
4+
5+
## Project Overview
6+
7+
Symfony 7.3 demo showcasing AI integration with RAG, streaming chat, multimodal interactions, and MCP server functionality.
8+
9+
## Architecture
10+
11+
### Core Features
12+
- **Chat Systems**: Blog, YouTube, Wikipedia, Audio, Stream implementations
13+
- **Twig LiveComponents**: Real-time chat interfaces with Symfony UX
14+
- **AI Agents**: Multiple configured agents with different models and tools
15+
- **Vector Store**: ChromaDB integration for similarity search
16+
- **MCP Tools**: Model Context Protocol for extending agent capabilities
17+
18+
### Technologies
19+
- Symfony 7.3 + UX (LiveComponent, Turbo, Typed)
20+
- OpenAI GPT-4o-mini + embeddings
21+
- ChromaDB vector database
22+
- FrankenPHP runtime
23+
24+
## Essential Commands
25+
26+
### Setup
27+
```bash
28+
# Start services
29+
docker compose up -d
30+
composer install
31+
echo "OPENAI_API_KEY='sk-...'" > .env.local
32+
33+
# Initialize vector store
34+
symfony console app:blog:embed -vv
35+
symfony console app:blog:query
36+
37+
# Start server
38+
symfony serve -d
39+
```
40+
41+
### Testing
42+
```bash
43+
vendor/bin/phpunit
44+
vendor/bin/phpunit tests/SmokeTest.php
45+
```
46+
47+
### Code Quality
48+
```bash
49+
vendor/bin/php-cs-fixer fix
50+
vendor/bin/phpstan analyse
51+
```
52+
53+
### MCP Server
54+
```bash
55+
symfony console mcp:server
56+
# Test: {"method":"tools/list","jsonrpc":"2.0","id":1}
57+
```
58+
59+
## Configuration
60+
61+
### AI Setup (`config/packages/ai.yaml`)
62+
- **Agents**: blog, stream, youtube, wikipedia, audio
63+
- **Platform**: OpenAI integration
64+
- **Store**: ChromaDB vector store
65+
- **Indexer**: Text embedding model
66+
67+
### Chat Pattern
68+
- `Chat` class: Message flow and session management
69+
- `TwigComponent` class: LiveComponent UI
70+
- Agent configuration in `ai.yaml`
71+
- Session storage with component keys
72+
73+
## Development Notes
74+
75+
- PHP 8.4+ with strict typing
76+
- OpenAI GPT-4o-mini default model
77+
- ChromaDB on port 8080
78+
- LiveComponents for real-time UI
79+
- Symfony DI and best practices

‎examples/AGENTS.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# AGENTS.md
2+
3+
AI agent guidance for Symfony AI examples directory.
4+
5+
## Project Overview
6+
7+
Standalone examples demonstrating Symfony AI component usage across different platforms. Serves as reference implementations and integration tests.
8+
9+
## Essential Commands
10+
11+
### Setup
12+
```bash
13+
composer install
14+
../link # Link local AI components
15+
docker compose up -d # For store examples
16+
```
17+
18+
### Running Examples
19+
```bash
20+
# Single example
21+
php openai/chat.php
22+
php openai/toolcall-stream.php -vvv
23+
24+
# Batch execution
25+
./runner # All examples
26+
./runner openai mistral # Specific platforms
27+
./runner --filter=toolcall # Pattern filter
28+
```
29+
30+
### Environment
31+
Configure API keys in `.env.local` (copy from `.env` template).
32+
33+
## Architecture
34+
35+
### Directory Structure
36+
- Platform directories: `openai/`, `anthropic/`, `gemini/`, etc.
37+
- `misc/`: Cross-platform examples
38+
- `rag/`: Retrieval Augmented Generation examples
39+
- `toolbox/`: Utility tools and integrations
40+
- `bootstrap.php`: Common setup for all examples
41+
42+
### Patterns
43+
- Shared `bootstrap.php` setup
44+
- Consistent structure across platforms
45+
- Verbose output flags (`-vv`, `-vvv`)
46+
- Synchronous and streaming demos
47+
48+
### Dependencies
49+
Uses `@dev` versions:
50+
- `symfony/ai-platform`
51+
- `symfony/ai-agent`
52+
- `symfony/ai-store`
53+
54+
## Development Notes
55+
56+
- Examples serve as integration tests
57+
- Runner executes in parallel for platform verification
58+
- Demonstrates both sync and async patterns
59+
- Platform-specific client configurations

‎src/agent/AGENTS.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# AGENTS.md
2+
3+
AI agent guidance for the Agent component.
4+
5+
## Component Overview
6+
7+
Framework for building AI agents with user interaction and task execution. Built on Platform component with optional Store integration for memory.
8+
9+
## Architecture
10+
11+
### Core Classes
12+
- **Agent** (`src/Agent.php`): Main orchestration class
13+
- **AgentInterface**: Contract for implementations
14+
- **Chat** (`src/Chat.php`): High-level conversation interface
15+
- **Input/Output** (`src/Input.php`, `src/Output.php`): Pipeline data containers
16+
17+
### Processing Pipeline
18+
- **InputProcessorInterface**: Input transformation contract
19+
- **OutputProcessorInterface**: Output transformation contract
20+
- Middleware-like processing chain
21+
22+
### Key Features
23+
- **Memory** (`src/Memory/`): Conversation memory with embeddings
24+
- **Toolbox** (`src/Toolbox/`): Function calling capabilities
25+
- **Structured Output**: Typed response support
26+
- **Message Stores** (`src/Chat/MessageStore/`): Chat persistence
27+
28+
## Essential Commands
29+
30+
### Testing
31+
```bash
32+
vendor/bin/phpunit
33+
vendor/bin/phpunit tests/AgentTest.php
34+
vendor/bin/phpunit --coverage-html coverage/
35+
```
36+
37+
### Code Quality
38+
```bash
39+
vendor/bin/phpstan analyse
40+
cd ../../.. && vendor/bin/php-cs-fixer fix src/agent/
41+
```
42+
43+
## Processing Architecture
44+
45+
### Pipeline Flow
46+
1. Input processors modify requests
47+
2. Platform processes request
48+
3. Output processors modify responses
49+
50+
### Built-in Processors
51+
- **SystemPromptInputProcessor**: Adds system prompts
52+
- **ModelOverrideInputProcessor**: Runtime model switching
53+
- **MemoryInputProcessor**: Conversation context from memory
54+
55+
### Memory Providers
56+
- **StaticMemoryProvider**: In-memory storage
57+
- **EmbeddingProvider**: Vector-based semantic memory (requires Store)
58+
59+
### Tool Integration
60+
- Auto-discovery via attributes
61+
- Fault-tolerant execution
62+
- Event system for lifecycle management
63+
64+
## Dependencies
65+
66+
- **Platform component**: Required for AI communication
67+
- **Store component**: Optional for embedding memory
68+
- **Symfony**: HttpClient, Serializer, PropertyAccess, Clock
69+
70+
## Testing Patterns
71+
72+
- Use `MockHttpClient` over response mocking
73+
- Test processors independently
74+
- Use `/fixtures` for multimodal content
75+
- Prefer `self::assert*` in tests
76+
77+
## Development Notes
78+
79+
- Component is experimental (BC breaks possible)
80+
- Add `@author` tags to new classes
81+
- Use component-specific exceptions from `src/Exception/`
82+
- Follow `@Symfony` PHP CS Fixer rules

0 commit comments

Comments
 (0)