A lightweight, transparent, and highly customizable Python library for building AI assistants using OpenAI's Chat Completions API. With a core implementation under 200 lines, it balances simplicity with power, enabling developers to build assistants that manage long conversations, execute multiple tasks, and maintain context across sessions—all while offering full control over data and behavior.
- Assistant Creation: Define assistants with models, system messages, tools, templates, and guardrails.
- Session Management: Persistent, locally stored sessions with SQLite for seamless conversation continuity.
- Memory System: Integration with
Mem4aifor storing and retrieving contextual data. - Message Processing: Handle user inputs, tool execution loops, and structured outputs with ease.
- Transparency: Inspect and modify conversation history, memory, and session data directly.
- Flexibility: Supports vision, token tracking, and dynamic templates for tailored interactions.
First, clone the repository:
git clone https://github.com/MojitoFilms/agentloop.git
cd agentloopThen install the dependencies:
# Install from requirements.txt
pip install -r requirements.txt
# Or install directly
pip install openai tiktoken
pip install git+https://github.com/unclecode/mem4ai.gitSet your OpenAI API key:
export OPENAI_API_KEY="your-api-key-here"Create a simple assistant and start a conversation:
from agentloop import agentloop
# Define a tool
def get_weather(city: str) -> str:
"""Return the weather for a given city."""
return f"Weather in {city}: Sunny, 20°C"
# Create assistant
assistant = agentloop.create_assistant(
model_id="gpt-4o",
template="Hello, {{name}}! I'm your {{role}} assistant.",
template_params={"name": "Alice", "role": "travel"},
tools=[get_weather],
guardrail="Don't discuss politics.",
synthesizer_model_id="gpt-3.5-turbo" # Optional: use a different model for tool calls
)
# Start session
session = agentloop.start_session(assistant, "user123")
# Process a message
response = agentloop.process_message(
session,
"What's the weather in Paris?"
)
print(response["response"]) # Weather in Paris: Sunny, 20°Cassistant = agentloop.create_assistant(
model_id="gpt-4o",
system_message="You are a helpful assistant.",
tools=[get_weather, book_flight],
params={"temperature": 0.7},
template="Hello {{name}}! I am your {{role}} assistant.",
template_params={"name": "User", "role": "travel"},
guardrail="Always be polite and helpful.",
synthesizer_model_id="gpt-3.5-turbo" # Optional: different model for tool call processing
)# Start a new session or load existing one
session = agentloop.start_session(assistant, "user123")
# Get or set conversation history
history = agentloop.get_history(session)
agentloop.set_history(session, new_history)
agentloop.add_messages(session, [{"role": "user", "content": "Hello"}])# Simple text message
response = agentloop.process_message(
session,
"What's the weather in Paris?"
)
# With template
response = agentloop.process_message(
session,
"What's the weather?",
user_template="Query from {{name}}: {{message}}",
template_params={"name": "Alice"}
)
# With structured output
schema = {
"name": "weather_response",
"schema": {
"type": "object",
"properties": {
"city": {"type": "string"},
"temperature": {"type": "string"},
"conditions": {"type": "string"}
},
"required": ["city", "temperature", "conditions"],
"additionalProperties": False
},
"strict": True
}
response = agentloop.process_message(
session,
"What's the weather in Paris?",
schema=schema
)Agentloop uses Mem4ai for memory management:
# Add a memory
agentloop.update_memory(
session,
"User prefers metric units",
{"type": "preference", "value": "metric"}
)
# Get memory instance
memtor = agentloop.get_memory(session)Try the included example:
# Make sure you're in the agentloop directory
python example.py- Travel Planners: Search flights, recommend destinations, and remember user preferences.
- Customer Support: Handle inquiries, search knowledge bases, and maintain conversation context.
- Research Assistants: Extract information from documents, organize findings, and generate summaries.
- Creative Writing Aids: Brainstorm ideas, suggest improvements, and provide feedback on drafts.
All session data is stored locally in SQLite at ~/.agentloop/agentloop.db, giving you full control over your data.
MIT License