> ## Documentation Index
> Fetch the complete documentation index at: https://docs.camel-ai.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Learn about CAMEL's agent types, with a focus on ChatAgent and advanced agent architectures for AI-powered automation.

## Concept

Agents in CAMEL are autonomous entities capable of performing specific tasks through interaction with language models and other components.
Each agent is designed with a particular role and capability, allowing them to work independently or collaboratively to achieve complex goals.

<Note type="info" title="What is an Agent?">
  <strong>Think of an agent as an AI-powered teammate</strong> one that brings a defined role, memory, and tool-using abilities to every workflow. CAMEL’s agents are composable, robust, and can be extended with custom logic.
</Note>

## Base Agent Architecture

All CAMEL agents inherit from the <code>BaseAgent</code> abstract class, which defines two essential methods:

| Method               | Purpose          | Description                                     |
| -------------------- | ---------------- | ----------------------------------------------- |
| <code>reset()</code> | State Management | Resets the agent to its initial state           |
| <code>step()</code>  | Task Execution   | Performs a single step of the agent's operation |

## Types

### ChatAgent

The `ChatAgent` is the primary implementation that handles conversations with language models. It supports:

* System message configuration for role definition
* Memory management for conversation history
* Tool/function calling capabilities
* Response formatting and structured outputs
* Multiple model backend support with scheduling strategies
* Async operation support

<AccordionGroup>
  <Accordion title="Other Agent Types (When to Use)">
    **`CriticAgent`**
    Specialized agent for evaluating and critiquing responses or solutions. Used in scenarios requiring quality assessment or validation.

    **`DeductiveReasonerAgent`**
    Focused on logical reasoning and deduction. Breaks down complex problems into smaller, manageable steps.

    **`EmbodiedAgent`**
    Designed for embodied AI scenarios, capable of understanding and responding to physical world contexts.

    **`KnowledgeGraphAgent`**
    Specialized in building and utilizing knowledge graphs for enhanced reasoning and information management.

    **`MultiHopGeneratorAgent`**
    Handles multi-hop reasoning tasks, generating intermediate steps to reach conclusions.

    **`SearchAgent`**
    Focused on information retrieval and search tasks across various data sources.

    **`TaskAgent`**
    Handles task decomposition and management, breaking down complex tasks into manageable subtasks.
  </Accordion>
</AccordionGroup>

## Usage

### Basic ChatAgent Usage

```python theme={"system"}
from camel.agents import ChatAgent

# Create a chat agent with a system message
agent = ChatAgent(system_message="You are a helpful assistant.")

# Step through a conversation
response = agent.step("Hello, can you help me?")
```

### Simplified Agent Creation

The `ChatAgent` supports multiple ways to specify the model:

```python theme={"system"}
from camel.agents import ChatAgent
from camel.models import ModelFactory
from camel.types import ModelPlatformType, ModelType

# Method 1: Using just a string for the model name (default model platform is used)
agent_1 = ChatAgent("You are a helpful assistant.", model="gpt-4o-mini")

# Method 2: Using a ModelType enum (default model platform is used)
agent_2 = ChatAgent("You are a helpful assistant.", model=ModelType.GPT_4O_MINI)

# Method 3: Using a tuple of strings (platform, model)
agent_3 = ChatAgent("You are a helpful assistant.", model=("openai", "gpt-4o-mini"))

# Method 4: Using a tuple of enums
agent_4 = ChatAgent(
    "You are a helpful assistant.",
    model=(ModelPlatformType.ANTHROPIC, ModelType.CLAUDE_HAIKU_4_5),
)

# Method 5: Using default model platform and default model type when none is specified
agent_5 = ChatAgent("You are a helpful assistant.")

# Method 6: Using a pre-created model with ModelFactory (original approach)
model = ModelFactory.create(
    model_platform=ModelPlatformType.OPENAI,  # Using enum
    model_type=ModelType.GPT_4O_MINI,         # Using enum
)
agent_6 = ChatAgent("You are a helpful assistant.", model=model)

# Method 7: Using ModelFactory with string parameters
model = ModelFactory.create(
    model_platform="openai",     # Using string
    model_type="gpt-4o-mini",    # Using string
)
agent_7 = ChatAgent("You are a helpful assistant.", model=model)
```

### Using Tools with Chat Agent

```python theme={"system"}
from camel.agents import ChatAgent
from camel.toolkits import FunctionTool

# Define a tool
def calculator(a: int, b: int) -> int:
    return a + b

# Create agent with tool
agent = ChatAgent(tools=[calculator])

# The agent can now use the calculator tool in conversations
response = agent.step("What is 5 + 3?")
```

### Structured Output

CAMEL's `ChatAgent` can produce structured output by leveraging Pydantic models. This feature is especially useful when you need the agent to return data in a specific format, such as JSON. By defining a Pydantic model, you can ensure that the agent's output is predictable and easy to parse.

<Tabs>
  <Tab title="Simple Object">
    Here's how you can get a structured response from a `ChatAgent`. First, define a `BaseModel` that specifies the desired output fields. You can add descriptions to each field to guide the model.

    ```python theme={"system"}
    from pydantic import BaseModel, Field
    from typing import List

    class JokeResponse(BaseModel):
        joke: str = Field(description="A joke")
        funny_level: int = Field(description="Funny level, from 1 to 10")

    # Create agent with structured output
    agent = ChatAgent(model="gpt-4o-mini")
    response = agent.step("Tell me a joke.", response_format=JokeResponse)

    # The response content is a JSON string
    print(response.msgs[0].content)
    # '{"joke": "Why don't scientists trust atoms? Because they make up everything!", "funny_level": 8}'

    # Access the parsed Pydantic object
    parsed_response = response.msgs[0].parsed
    print(parsed_response.joke)
    # "Why don't scientists trust atoms? Because they make up everything!"
    print(parsed_response.funny_level)
    # 8
    ```
  </Tab>

  <Tab title="Nested Objects and Lists">
    You can also use nested Pydantic models and lists to define more complex structures. In this example, we define a `StudentList` that contains a list of `Student` objects.

    ```python theme={"system"}
    from pydantic import BaseModel
    from typing import List

    class Student(BaseModel):
        name: str
        age: str
        email: str

    class StudentList(BaseModel):
        students: List[Student]

    # Create agent with structured output
    agent = ChatAgent(model="gpt-4o-mini")
    response = agent.step(
        "Create a list of two students with their names, ages, and email addresses.",
        response_format=StudentList,
    )

    # Access the parsed Pydantic object
    parsed_response = response.msgs[0].parsed
    for student in parsed_response.students:
        print(f"Name: {student.name}, Age: {student.age}, Email: {student.email}")
    # Name: Alex, Age: 22, Email: alex@example.com
    # Name: Beth, Age: 25, Email: beth@example.com
    ```
  </Tab>
</Tabs>

## Best Practices

<AccordionGroup>
  <Accordion title="Memory Management">
    <ul>
      <li>Use appropriate window sizes to manage conversation history</li>
      <li>Consider token limits when dealing with long conversations</li>
      <li>Utilize the memory system for maintaining context</li>
    </ul>
  </Accordion>

  <Accordion title="Tool Integration">
    <ul>
      <li>Keep tool functions focused and well-documented</li>
      <li>Handle tool errors gracefully</li>
      <li>Use external tools for operations that should be handled by the user</li>
    </ul>
  </Accordion>

  <Accordion title="Response Handling">
    <ul>
      <li>Implement appropriate response terminators for conversation control</li>
      <li>Use structured outputs when specific response formats are needed</li>
      <li>Handle async operations properly when dealing with long-running tasks</li>
    </ul>
  </Accordion>

  <Accordion title="Model Specification">
    <ul>
      <li>Use the simplified model specification methods for cleaner code</li>
      <li>For default platform models, just specify the model name as a string</li>
      <li>For specific platforms, use the tuple format (platform, model)</li>
      <li>Use enums for better type safety and IDE support</li>
    </ul>
  </Accordion>
</AccordionGroup>

## Advanced Features

<Tabs>
  <Tab title="Model Scheduling">
    <Note type="info" title="Custom Model Selection">
      You can dynamically select which model an agent uses for each step by adding your own scheduling strategy.
    </Note>

    <CodeGroup>
      ```python title="Custom Model Scheduling" theme={"system"}
      def custom_strategy(models):
          # Custom model selection logic
          return models[0]

      agent.add_model_scheduling_strategy("custom", custom_strategy)
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Output Language Control">
    <Note type="tip" title="Multilingual Output">
      Agents can respond in any language. Set the output language on-the-fly during conversations.
    </Note>

    <CodeGroup>
      ```python title="Set Output Language" theme={"system"}
      agent.set_output_language("Spanish")
      ```
    </CodeGroup>
  </Tab>
</Tabs>