Agents

Agent Class

The Agent class is a fundamental component of the Cultura framework, designed to execute tasks autonomously. It fuses LLMs, tools, and long-term memory capabilities to create a full-stack agent. The Agent class is highly customizable, allowing for fine-grained control over its behavior and interactions.

run Method

The run method is the primary entry point for executing tasks with an Agent instance. It accepts a task string as the main input task and processes it according to the agent's configuration. Additionally, it can accept an img parameter such as img="image_filepath.png" to process images if you have a VLM attached such as DeepseekVL.

Simple Example

pythonCopyfrom cultura import Agent

agent = Agent(
    agent_name="Stock-Analysis-Agent",
    model_name="deepseek-r1",
    max_loops="auto",
    interactive=True,
    streaming_on=True,
)

agent.run("What is the current market trend for tech stocks?")

Settings and Customization

The Agent class offers a range of settings to tailor its behavior to specific needs. Some key settings include:

pythonCopyimport os
from cultura import Agent

from cultura.prompts.finance_agent_sys_prompt import (
    FINANCIAL_AGENT_SYS_PROMPT,
)

# Initialize the agent
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    system_prompt=FINANCIAL_AGENT_SYS_PROMPT,
    model_name="deepseek-r1",
    max_loops=1,
    autosave=True,
    dashboard=False,
    verbose=True,
    dynamic_temperature_enabled=True,
    saved_state_path="finance_agent.json",
    user_name="cultluraagent",
    retry_attempts=1,
    context_length=200000,
    return_step_meta=False,
    output_type="string",
    streaming_on=False,
)

agent.run(
    "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria"
)

Integrating RAG with Cultura for Enhanced Long-Term Memory

Agent equipped with quasi-infinite long-term memory using RAG (Relational Agent Graph) for advanced document understanding, analysis, and retrieval capabilities.

Mermaid Diagram for RAG Integration

pythonCopyfrom cultura import Agent
from cultura.prompts.finance_agent_sys_prompt import (
    FINANCIAL_AGENT_SYS_PROMPT,
)
import os

from cultura_memory import ChromaDB

# Initialize the ChromaDB client for long-term memory management
chromadb = ChromaDB(
    metric="cosine",  # Metric for similarity measurement
    output_dir="finance_agent_rag",  # Directory for storing RAG data
    # docs_folder="artifacts",  # Uncomment and specify the folder containing your documents
)

# Initialize the agent with RAG capabilities
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    system_prompt=FINANCIAL_AGENT_SYS_PROMPT,
    agent_description="Agent creates a comprehensive financial analysis",
    model_name="deepseek-r1",
    max_loops="auto",  # Auto-adjusts loops based on task complexity
    autosave=True,  # Automatically saves agent state
    dashboard=False,  # Disables dashboard for this example
    verbose=True,  # Enables verbose mode for detailed output
    streaming_on=True,  # Enables streaming for real-time processing
    dynamic_temperature_enabled=True,  # Dynamically adjusts temperature for optimal performance
    saved_state_path="finance_agent.json",  # Path to save agent state
    user_name="culturaagent",  # User name for the agent
    retry_attempts=3,  # Number of retry attempts for failed tasks
    context_length=200000,  # Maximum length of the context to consider
    long_term_memory=chromadb,  # Integrates ChromaDB for long-term memory management
    return_step_meta=False,
    output_type="string",
)

# Run the agent with a sample task
agent.run(
    "What are the components of a startups stock incentive equity plan"
)

Misc Agent Settings

We provide a vast array of features to save agent states using JSON, YAML, TOML, upload PDFs, batched jobs, and much more!

Method Table

pythonCopy# Convert the agent object to a dictionary
print(agent.to_dict())
print(agent.to_toml())
print(agent.model_dump_json())
print(agent.model_dump_yaml())

# Ingest documents into the agent's knowledge base
agent.ingest_docs("your_pdf_path.pdf")

# Receive a message from a user and process it
agent.receive_message(name="agent_name", message="message")

# Send a message from the agent to a user
agent.send_agent_message(agent_name="agent_name", message="message")

# Ingest multiple documents into the agent's knowledge base
agent.ingest_docs("your_pdf_path.pdf", "your_csv_path.csv")

# Run the agent with a filtered system prompt
agent.filtered_run(
    "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria?"
)

# Run the agent with multiple system prompts
agent.bulk_run(
    [
        "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria?",
        "Another system prompt",
    ]
)

# Add a memory to the agent
agent.add_memory("Add a memory to the agent")

# Check the number of available tokens for the agent
agent.check_available_tokens()

# Perform token checks for the agent
agent.tokens_checks()

# Print the dashboard of the agent
agent.print_dashboard()

# Fetch all the documents from the doc folders
agent.get_docs_from_doc_folders()

# Activate agent ops
agent.activate_agentops()
agent.check_end_session_agentops()

# Dump the model to a JSON file
agent.model_dump_json()
print(agent.to_toml())

Agent with Pydantic BaseModel as Output Type

The following is an example of an agent that intakes a Pydantic BaseModel and outputs it at the same time:

pythonCopyfrom pydantic import BaseModel, Field
from cultura import Agent

# Initialize the schema for the person's information
class Schema(BaseModel):
    name: str = Field(..., title="Name of the person")
    agent: int = Field(..., title="Age of the person")
    is_student: bool = Field(..., title="Whether the person is a student")
    courses: list[str] = Field(
        ..., title="List of courses the person is taking"
    )

# Convert the schema to a JSON string
tool_schema = Schema(
    name="Tool Name",
    agent=1,
    is_student=True,
    courses=["Course1", "Course2"],
)

# Define the task to generate a person's information
task = "Generate a person's information based on the following schema:"

# Initialize the agent
agent = Agent(
    agent_name="Person Information Generator",
    system_prompt=(
        "Generate a person's information based on the following schema:"
    ),
    # Set the tool schema to the JSON string -- this is the key difference
    tool_schema=tool_schema,
    model_name="deepseek-r1",
    max_loops=3,
    autosave=True,
    dashboard=False,
    streaming_on=True,
    verbose=True,
    interactive=True,
    # Set the output type to the tool schema which is a BaseModel
    output_type=tool_schema,  # or dict, or str
    metadata_output_type="json",
    # List of schemas that the agent can handle
    list_base_models=[tool_schema],
    function_calling_format_type="Deepseek",
    function_calling_type="json",  # or soon yaml
)

# Run the agent to generate the person's information
generated_data = agent.run(task)

# Print the generated data
print(f"Generated data: {generated_data}")

Multi-Modal Autonomous Agent

Run the agent with multiple modalities useful for various real-world tasks in manufacturing, logistics, and health.

pythonCopyimport os
from dotenv import load_dotenv
from cultura import Agent

from cultura_models import DeepseekVL

# Load the environment variables
load_dotenv()

# Initialize the language model
llm = DeepseekVL(
    deepseek_api_key=os.environ.get("DEEPSEEK_API_KEY"),
    max_tokens=500,
)

# Initialize the task
task = (
    "Analyze this image of an assembly line and identify any issues such as"
    " misaligned parts, defects, or deviations from the standard assembly"
    " process. IF there is anything unsafe in the image, explain why it is"
    " unsafe and how it could be improved."
)
img = "assembly_line.jpg"

## Initialize the workflow
agent = Agent(
    agent_name = "Multi-ModalAgent",
    llm=llm, 
    max_loops="auto", 
    autosave=True, 
    dashboard=True, 
    multi_modal=True
)

# Run the workflow on a task
agent.run(task, img)

Local Agent ToolAgent

ToolAgent is a fully local agent that can use tools through JSON function calling. It intakes any open-source model from Hugging Face and is extremely modular and plug-and-play. We need help adding general support to all models soon.

pythonCopyfrom pydantic import BaseModel, Field
from transformers import AutoModelForCausalLM, AutoTokenizer

from cultura import ToolAgent
from cultura.tools.json_utils import base_model_to_json

# Load the pre-trained model and tokenizer
model = AutoModelForCausalLM.from_pretrained(
    "databricks/dolly-v2-12b",
    load_in_4bit=True,
    device_map="auto",
)
tokenizer = AutoTokenizer.from_pretrained("databricks/dolly-v2-12b")

# Initialize the schema for the person's information
class Schema(BaseModel):
    name: str = Field(..., title="Name of the person")
    agent: int = Field(..., title="Age of the person")
    is_student: bool = Field(
        ..., title="Whether the person is a student"
    )
    courses: list[str] = Field(
        ..., title="List of courses the person is taking"
    )

# Convert the schema to a JSON string
tool_schema = base_model_to_json(Schema)

# Define the task to generate a person's information
task = (
    "Generate a person's information based on the following schema:"
)

# Create an instance of the ToolAgent class
agent = ToolAgent(
    name="dolly-function-agent",
    description="An agent to create a child's data",
    model=model,
    tokenizer=tokenizer,
    json_schema=tool_schema,
)

# Run the agent to generate the person's information
generated_data = agent.run(task)

# Print the generated data
print(f"Generated data: {generated_data}")

---

Additional Notes

• Environment Variables: Ensure that all necessary environment variables (e.g., DEEPSEEK_API_KEY) are properly set in your .env file when running multi-modal agents or any other agents requiring API access.

• Dependencies: Make sure to install all required dependencies for the Cultura framework, including but not limited to pydantic, transformers, and any other libraries referenced in the examples.

• Long-Term Memory Management: When integrating long-term memory with RAG, ensure that the ChromaDB is correctly configured and that the docs_folder is specified if needed.

• Schema Definitions: When using Pydantic BaseModel for schemas, ensure that your schemas are well-defined and validated to prevent runtime errors.

If you encounter any issues or need further customization, feel free to consult the Cultura framework documentation or reach out to the support community.