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:

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:

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:

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

For a complete implementation example, refer to the 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 Callbacks section).

Agent Execution Flow#

When you run an agent, the following steps occur:

The system prompt is sent to the LLM (if provided)
The user intent is sent to the LLM
The LLM generates a response, which might include tool calls
If tool calls are present, the agent executes the tools with the provided inputs
The tool results are sent back to the LLM
Steps 3-5 repeat until the LLM provides a final response without tool calls
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.