Working with Agents
================

Agents are the central concept in Malevich Brain. An agent combines an LLM with a set of tools, allowing it to perform tasks.

Creating an Agent
----------------

To create an agent, you need to provide an LLM instance and a list of tools:

.. code-block:: python

    from brain.agents.agent import Agent
    from brain.agents.llm.openai import OpenAIBaseLLM
    from brain.agents.tool import tool
    
    # Create a tool
    @tool()
    def search_web(query: str) -> str:
        """Search the web for information"""
        # Implementation...
        return "Search results..."
    
    # Initialize the LLM
    llm = OpenAIBaseLLM(api_key="your-api-key")
    
    # Create the agent
    agent = Agent(
        llm=llm,
        tools=[search_web],
        instructions="You are a helpful assistant."
    )

Agent Configuration
------------------

You can customize the agent's behavior using the ``AgentConfig`` class:

.. code-block:: python

    from brain.agents.agent import Agent, AgentConfig
    
    # Create a custom config
    config = AgentConfig(
        expose_tools_to_system_prompt=True,  # Include tool info in system prompt
        max_tool_calls=10,  # Limit the number of tool calls
        tool_info_format="Custom format: {name}\n{description}\n"  # Custom format for tool info
    )
    
    # Create the agent with the custom config
    agent = Agent(
        llm=llm,
        tools=[search_web],
        instructions="You are a helpful assistant.",
        config=config
    )

Running the Agent
---------------

To run the agent, call the ``run`` method with a user intent:

.. code-block:: python

    async def main():
        result = await agent.run("Can you search for information about Python?")
        print(result)

For a complete implementation example, refer to the :ref:`Quickstart <getting_started/quickstart:Quickstart>` guide.

Handling Agent Output
-------------------

The ``run`` method returns the final response from the agent as a string. If you need more control over the agent's execution or want to access intermediate results, you can implement custom callbacks (see the :ref:`Callbacks <user_guide/callbacks:Using Callbacks>` section).

Agent Execution Flow
------------------

When you run an agent, the following steps occur:

1. The system prompt is sent to the LLM (if provided)
2. The user intent is sent to the LLM
3. The LLM generates a response, which might include tool calls
4. If tool calls are present, the agent executes the tools with the provided inputs
5. The tool results are sent back to the LLM
6. Steps 3-5 repeat until the LLM provides a final response without tool calls
7. The final response is returned from the ``run`` method

This execution flow allows the agent to use tools to gather information and perform actions before providing a final response to the user.