Machine Core

A flexible agent framework for building AI agents with MCP integration

Get Started View on GitHub

Features

Clean Architecture

Separation of infrastructure (AgentCore) and execution patterns (BaseAgent)

Flexible Configuration

Environment variables, direct parameters, or runtime overrides

MCP Integration

Easy integration with MCP servers and tools

Multiple Agent Types

Chat, CLI, Receipt Processor, Twitter Bot, Memory Master, RAG Chat

Reusable Package

Install once, use in multiple projects

Streaming Support

Real-time streaming responses for interactive applications

Provided Example Agents

ChatAgent

Streaming chat agent

Use Case: Streamlit UI, web chat

View Live Demo →

CLIAgent

Non-streaming agent

Use Case: Terminal, cron jobs

ReceiptProcessorAgent

Vision + queue processing

Use Case: Document analysis

View Live Demo →

TwitterBotAgent

Scheduled posting agent

Use Case: Social media automation

RAGChatAgent

Knowledge graph integration

Use Case: Q&A, support

MemoryMasterAgent

Knowledge extraction

Use Case: Graph maintenance

Quick Start

Installation

uv add git+https://github.com/samletnorge/machine-core.git

Basic Usage

from machine_core.agents import ChatAgent

# Loads config from environment variables
agent = ChatAgent()

# Run streaming query
async for event in agent.run("What is quantum computing?"):
    if event['type'] == 'text_delta':
        print(event['content'], end='', flush=True)

Custom Configuration

from machine_core import AgentConfig
from machine_core.agents import CLIAgent

# Create custom config
config = AgentConfig(
    max_iterations=20,
40303F    timeout=3600.0,
    max_tool_retries=10
)

# Pass to agent
agent = CLIAgent(
    model_name="llama3.2:latest",
    agent_config=config
)

result = await agent.run("Analyze this data")

Website API Information

The Machine Core API provides the following endpoints:

  • GET /health - Health check endpoint
  • GET /api/info - Get service information
  • GET /metrics - Prometheus metrics

Example: Get Service Info

curl https://machine-core.valiantlynx.com/api/info

Architecture

AgentCore (infrastructure)
  ├─ MCP toolset loading/validation
  ├─ Model/provider configuration
  ├─ Embedding backend setup
  └─ Agent instance creation

BaseAgent (execution patterns)
  ├─ run() [abstract - implement per agent]
  ├─ run_query() [sync execution]
  ├─ run_query_stream() [streaming execution]
  └─ Helper methods

ConcreteAgent (implementations)
  └─ Implements run() using base patterns

Chat