# CAMEL Agents

<p align="center">
  <strong>Communicative Agents for "Mind" Exploration</strong>
</p>

<p align="center">
  <a href="README_CN.md">中文文档</a> | <a href="README.md">English</a>
</p>

<p align="center">
  <a href="#architecture">Architecture</a> •
  <a href="#installation">Installation</a> •
  <a href="#quick-start">Quick Start</a> •
  <a href="#api-reference">API Reference</a>
</p>

---

A Python implementation of **CAMEL**, a framework for building communicative agents that collaborate through role-playing.

## Architecture

```
CAMEL Architecture
│
├── CAMELSociety (Orchestrator)
│   ├── Manages multi-agent collaboration
│   ├── Handles turn-taking between agents
│   └── Tracks conversation progress
│
├── RolePlayingAgent (Agents)
│   ├── Role-based behavior
│   ├── Contextual responses
│   └── Goal-oriented communication
│
├── Conversation (Dialogue Manager)
│   ├── Message history
│   ├── Context formatting
│   └── OpenAI format export
│
└── Types (Data Structures)
    ├── Role - Agent role definition
    ├── Task - Collaborative task
    ├── Message - Single utterance
    └── TaskSpec - Task specification
```

## Core Workflow

```
┌─────────────────────────────────────────────────────────────────┐
│                    CAMEL Collaboration Flow                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   Task ──▶ Agent 1 (Role A) ◀──▶ Conversation ◀──▶ Agent 2     │
│              │                    │                    │         │
│              │                    │                    │         │
│              ▼                    ▼                    ▼         │
│           Respond              Update              Respond       │
│              │                    │                    │         │
│              └────────────────────┴────────────────────┘         │
│                         (Iterate until done)                     │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

## Installation

```bash
pip install camel-agents
```

## Quick Start

```python
from camel import CAMELSociety, Role, AgentType

# Create society
society = CAMELSociety(verbose=True, max_turns=10)

# Define roles
programmer = Role(
    name="Python Programmer",
    description="Expert Python developer who writes clean code",
    agent_type=AgentType.ASSISTANT
)

reviewer = Role(
    name="Code Reviewer",
    description="Meticulous reviewer ensuring quality",
    agent_type=AgentType.USER
)

# Run collaboration
result = society.collaborate(
    task="Write a function to sort a list",
    agents=[programmer, reviewer]
)

print(f"Success: {result.success}")
print(f"Output: {result.final_output}")
print(result.to_transcript())
```

## Predefined Roles

| Role | Description |
|------|-------------|
| `programmer` | Expert Python programmer |
| `reviewer` | Code quality reviewer |
| `teacher` | Educational instructor |
| `student` | Eager learner |
| `writer` | Content creator |
| `editor` | Text quality editor |

## CLI Usage

```bash
# Quick collaboration with predefined roles
camel run "Write a sorting algorithm" --role1 programmer --role2 reviewer

# Interactive mode
camel interactive --role1 teacher --role2 student

# List available roles
camel roles

# Export result
camel run "Task" --export result.json
```

## API Reference

### CAMELSociety

| Method | Description |
|--------|-------------|
| `add_agent(role)` | Add an agent to the society |
| `collaborate(task, agents)` | Run collaborative task |
| `quick_collaborate(task, role1, role2)` | Use predefined roles |
| `get_conversation()` | Get current conversation |
| `get_agents()` | Get all agents |

### RolePlayingAgent

| Method | Description |
|--------|-------------|
| `respond(message)` | Generate response as role |
| `introduce()` | Self-introduction |
| `get_conversation()` | Get agent's conversation |

## Academic Reference

Implementation of the **CAMEL** paper:

> **CAMEL: Communicative Agents for "Mind" Exploration of Large Language Models**
>
> Guohao Li, Hasan Hammoud, Hani Itani, Dmitrii Khizbullin, Bernard Ghanem
>
> *NeurIPS 2023*
>
> Paper: https://arxiv.org/abs/2303.17760

```bibtex
@inproceedings{li2023camel,
  title={CAMEL: Communicative Agents for "Mind" Exploration of Large Language Models},
  author={Li, Guohao and Hammoud, Hasan and Itani, Hani and Khizbullin, Dmitrii and Ghanem, Bernard},
  booktitle={Advances in Neural Information Processing Systems (NeurIPS)},
  year={2023}
}
```

## License

MIT License

---

<p align="center">
  Made with ❤️ by AI Agent Research Team
</p>