Agents

The Agent class is the main entry point for using Malevich Brain. It coordinates interactions between the LLM and tools.

Agent

class brain.agents.agent.Agent(llm: BaseLLM, tools: list[Tool] | None = None, instructions: str | None = None, callbacks: list[Callback] = [], config: AgentConfig = AgentConfig(tool_info_format='\nTool {name}:\n{description}\nInput:\n{input_schema}\n', expose_tools_to_system_prompt=True, tool_info_header='Available tools:', max_tool_calls=25, context_format='\n<CONTEXT_REFERENCE_INSTRUCTIONS>\n\nYou have access to contextual objects you may explicitly reference inside your answer.\n\nREFERENCE TOKEN SYNTAX:\n- Full form: @@REF|Custom label@@\n- Short form: @@REF@@  (renderer will insert the canonical label)\n\nRules:\n1. Use only REF identifiers exactly as listed below; never invent or modify them.\n2. Do not alter the REF casing or its punctuation.\n3. If you supply a custom label, keep it faithful and concise (e.g., exact filename, person\'s full name, brief title). Do NOT fabricate facts.\n4. Do not include nested brackets, newlines, or the "|" character inside labels.\n5. Use references inline, at the point of first mention; prefer the full form on first mention for clarity.\n6. If you are unsure which REF corresponds to a mention, ask for clarification instead of guessing.\n7. Do not emit other markup attempting to "link" the object—only the specified token format.\n\nExamples:\n- Correct: I reviewed @@2fce|theFile.txt@@ and compared it with @@u483|Alice Smith@@.\n- Correct (auto label on subsequent use): The issue persists in @@b7aa@@.\n- Incorrect: I reviewed [theFile.txt](2fce)  (wrong format)\n- Incorrect: I reviewed @@2fce@@ if that\'s the right file. (uncertain reference)\n- Incorrect: I reviewed @@2fce|theFile.txt|extra@@ (extra delimiter)\n\nIf a REF must appear multiple times:\n- First mention: prefer full form (with label).\n- Subsequent mentions: short form @@REF@@ is acceptable.\n\nIf no listed REF matches something you need to reference, ask instead of fabricating.\n\nGETTING DETAILS:\nUse the "brain__get_context_details" tool with a REF to get detailed information about any context object.\n\nContext Objects (REF: summary):\n{% for ref, summary in exposed_objects %}\n{{ref}}: {{summary}}\n{% endfor %}\n\n</CONTEXT_REFERENCE_INSTRUCTIONS>\n    '), context: AgentContext = AgentContext(objects=[], context_refs={}), mcp_servers: list[MCP] | None = None, repl: Any | None = None)

The base class for an agent

Show-inheritance:

get_context_ref_mapping() → dict[str, str]

Returns a dictionary mapping context references to their original URNs

async run(intent: str | None = None, previous_messages: list[Message] | None = None, schema: type[BaseModel] | None = None, return_conversation: Literal[True] = True, *args: Any, **kwargs: Any) → list[Message]

async run(intent: str | None = None, previous_messages: list[Message] | None = None, schema: type[BaseModel] | None = None, return_conversation: Literal[False] = False, *args: Any, **kwargs: Any) → Message

Runs the agent on a given intent

The agent will run until it has no more tool calls to fulfill. It no tools are provided, the agent will only use the LLM to respond to the intent.

Parameters:

• intent (str) – The intent to run the agent on.

• previous_messages (list[Message] | None) – The previous messages to use for the agent. If not provided, the agent will start from scratch.

Returns:

The response from the agent.

Return type:

str

Agent Config

class brain.agents.agent.AgentConfig(*, tool_info_format: str = '\nTool {name}:\n{description}\nInput:\n{input_schema}\n', expose_tools_to_system_prompt: bool = True, tool_info_header: str = 'Available tools:', max_tool_calls: int = 25, context_format: str = '\n<CONTEXT_REFERENCE_INSTRUCTIONS>\n\nYou have access to contextual objects you may explicitly reference inside your answer.\n\nREFERENCE TOKEN SYNTAX:\n- Full form: @@REF|Custom label@@\n- Short form: @@REF@@  (renderer will insert the canonical label)\n\nRules:\n1. Use only REF identifiers exactly as listed below; never invent or modify them.\n2. Do not alter the REF casing or its punctuation.\n3. If you supply a custom label, keep it faithful and concise (e.g., exact filename, person\'s full name, brief title). Do NOT fabricate facts.\n4. Do not include nested brackets, newlines, or the "|" character inside labels.\n5. Use references inline, at the point of first mention; prefer the full form on first mention for clarity.\n6. If you are unsure which REF corresponds to a mention, ask for clarification instead of guessing.\n7. Do not emit other markup attempting to "link" the object—only the specified token format.\n\nExamples:\n- Correct: I reviewed @@2fce|theFile.txt@@ and compared it with @@u483|Alice Smith@@.\n- Correct (auto label on subsequent use): The issue persists in @@b7aa@@.\n- Incorrect: I reviewed [theFile.txt](2fce)  (wrong format)\n- Incorrect: I reviewed @@2fce@@ if that\'s the right file. (uncertain reference)\n- Incorrect: I reviewed @@2fce|theFile.txt|extra@@ (extra delimiter)\n\nIf a REF must appear multiple times:\n- First mention: prefer full form (with label).\n- Subsequent mentions: short form @@REF@@ is acceptable.\n\nIf no listed REF matches something you need to reference, ask instead of fabricating.\n\nGETTING DETAILS:\nUse the "brain__get_context_details" tool with a REF to get detailed information about any context object.\n\nContext Objects (REF: summary):\n{% for ref, summary in exposed_objects %}\n{{ref}}: {{summary}}\n{% endfor %}\n\n</CONTEXT_REFERENCE_INSTRUCTIONS>\n    ')

The configuration for an agent

Show-inheritance:

tool_info_format: str

The format to use when exposing tool information to the system prompt. Supports {name}, {description}, {input_schema}, {output_schema}

expose_tools_to_system_prompt: bool

Whether to add tool information to the system prompt

tool_info_header: str

The header to use when exposing tool information to the system prompt

max_tool_calls: int

The maximum number of tool calls to make

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].