uc-llm-agent-tools 0.2.0

Lightweight LLM agent library — memory layers, skills, context engineering

uc-llm-agent-tools

Lightweight LLM agent library — memory layers, skills, context engineering.

Works with any LLM: Anthropic, OpenAI, Google, Ollama. Built on uc-llm-provider.

---

Why

Most agent frameworks are complex, opinionated, and hard to embed. uc-llm-agent-tools is a small, composable library:

• No mandatory vector DB — SQLite by default
• No framework lock-in — works with any provider via uc-llm-provider
• Context Engineering first — token budget, anti-fail guards built in
• Readable memory — Identity and memories are Markdown files

Install

pip install uc-llm-agent-tools

Quick Start

import asyncio
from llm_agent_tools import Agent, Identity, MemoryStore, MemoryLayer, skill, SkillResult
from llm_agent_tools.memory.backends.sqlite import SQLiteBackend
from uc_llm_provider import get_provider

# Define a skill
@skill(name="fetch_page", description="Fetch and analyze a web page", tags=["browser"])
async def fetch_page(url: str) -> SkillResult:
    # your implementation here
    return SkillResult(success=True, content=f"Page at {url} analyzed", data={})

# Create agent
agent = Agent(
    identity = Identity.from_file("my-identity.md"),
    memory   = MemoryStore(
        backend = SQLiteBackend("agent.sqlite3"),
        layers  = [
            MemoryLayer("project", level=2, persist=True),
            MemoryLayer("run",     level=3, persist=False),
        ]
    ),
    skills   = [fetch_page],
    provider = get_provider({"name": "anthropic", "provider_type": "anthropic"}),
)

async def main():
    result = await agent.run("Analyze https://example.com for accessibility issues")
    print(result.response)

asyncio.run(main())

Identity File

---
name: My Agent
version: 1.0
---

# Persönlichkeit

I am a QA specialist. I test systematically and precisely.

# Direktiven

- Never test production systems without explicit confirmation.
- Always report errors — never swallow them silently.

Directives are immutable at runtime. Personality grows via agent.identity.add_fact(...).

Memory Hierarchy

Level 0: Directives   — always loaded, never overridden
Level 1: Personality  — always loaded, grows over time
Level N: custom named — filtered by budget and relevance

High beats low. Low complements high.

Context Engineering

ContextBuilder prevents the four context failure modes automatically:

Guard	Problem prevented
Poisoning Guard	LLM-sourced memories are marked [LLM]
Distraction Guard	Run-memory capped when context grows too large
Confusion Guard	Max 8 skills loaded at once
Clash Guard	Hierarchy enforces priority

ThinkingLight

Provider-independent Chain-of-Thought — works on Ollama, GPT, Claude alike. No expensive Extended Thinking required.

from llm_agent_tools import wrap_prompt, extract_thinking

prompt   = wrap_prompt("Analyze this page")
thinking, answer = extract_thinking(llm_response)

Human-in-the-Loop

from llm_agent_tools import HumanInTheLoop

hitl = HumanInTheLoop(on_pause=my_approval_handler)
decision = await hitl.pause(
    message  = "I found 47 test ideas. Generate all as Gherkin?",
    options  = ["All", "High priority only", "Cancel"],
    timeout  = 300,
    fallback = "High priority only",
)

Structured Output

from llm_agent_tools import structured_ai
from pydantic import BaseModel

class TestReport(BaseModel):
    summary: str
    issues:  list[str]

report = await structured_ai(provider, "Analyze this page", TestReport)
# report is a validated TestReport instance

Interactive Session

session = agent.interactive_session()
response = await session.chat("Why did you choose that selector?")
response = await session.chat("Now test the login form specifically")

License

MIT — uc-it