Build Real Agentic Apps Using CUGA: Two Dozen Working Examples on a Lightweight Harness

Build Real Agentic Apps Using CUGA: Two Dozen Working Examples on a Lightweight Harness

The rise of agentic AI—systems that can reason, plan, and execute tasks autonomously—has transformed how developers approach automation. Yet building such agents often requires complex frameworks, heavy infrastructure, and extensive boilerplate. Enter CUGA (Compact Unified Generative Agent), a lightweight harness that lets you build and deploy agentic applications with minimal overhead. In this article, we’ll explore how CUGA enables you to create two dozen working examples, from simple chatbots to multi-step reasoning agents, all on a lightweight harness. We’ll cover installation, configuration, and practical usage with real commands, drawing on insights from recent developments in AI agent frameworks highlighted by sources like the Hugging Face Blog, OpenAI News, Microsoft AI Blog, and Anthropic News.

What Is CUGA and Why Agentic Apps Matter

Agentic applications are AI systems that can perceive their environment, make decisions, and take actions to achieve goals. Unlike traditional chatbots that respond to prompts, agentic apps can break down complex tasks, use tools (e.g., search, calculators, APIs), and iterate on their outputs. CUGA provides a minimal abstraction layer over language models (LLMs) like those from OpenAI, Anthropic, or open-source alternatives, making it easy to orchestrate agentic behavior without heavyweight orchestration tools.

The concept of agentic AI has gained traction across the industry. OpenAI’s recent news emphasizes the shift toward autonomous systems capable of real-world interaction. Microsoft’s AI blog showcases how agents integrate with enterprise tools like Azure. Anthropic’s research highlights safety and reliability in agentic workflows. The Hugging Face Blog, meanwhile, has published practical examples of building agents with lightweight frameworks. CUGA aligns with this trend by offering a harness that is both simple and extensible.

Requirements

Before diving into installation and examples, ensure you have the following:

• **Python 3.10 or later**: CUGA is Python-native. Check your version with `python --version`.
• **A supported LLM provider**: OpenAI API key (for GPT-4o or GPT-4-turbo), Anthropic API key (for Claude 3.5 Sonnet), or access to a local model via Hugging Face Transformers.
• **Basic familiarity with the command line and Python**: You’ll run scripts and modify configuration files.
• **At least 4 GB RAM**: For local models or heavy agent loops.
• **Internet connection**: For API-based models and package downloads.

Step-by-Step Installation

CUGA is distributed as a Python package. We’ll install it in a virtual environment to keep dependencies isolated.

1. Create and activate a virtual environment

Start by creating a dedicated environment for your CUGA projects. This prevents conflicts with other Python packages.

python -m venv cuga_env
source cuga_env/bin/activate  # On Windows: cuga_env\Scripts\activate

2. Install CUGA and its core dependencies

Use pip to install the CUGA package along with the LLM provider libraries you plan to use. For this guide, we’ll install support for OpenAI, Anthropic, and open-source models via Hugging Face.

pip install cuga openai anthropic transformers torch

The `cuga` package itself is lightweight—less than 500 KB. The additional libraries add capabilities for different backends.

3. Verify the installation

Run a quick check to ensure CUGA is correctly installed and can import.

python -c "from cuga import Agent; print('CUGA installed successfully')"

If you see the success message, you’re ready to configure your LLM provider.

4. Set up your API keys

CUGA reads API keys from environment variables for security. Set them in your shell or a `.env` file.

export OPENAI_API_KEY="your-openai-key-here"
export ANTHROPIC_API_KEY="your-anthropic-key-here"

For local models, you don’t need API keys—just ensure Hugging Face transformers can access the model (e.g., `meta-llama/Llama-2-7b-chat-hf`).

5. Test with a simple agent

Create a file named `test_agent.py` with the following content to verify everything works:

from cuga import Agent

agent = Agent(model="gpt-4o", provider="openai")
response = agent.run("What is 2 + 2?")
print(response)

Run it:

python test_agent.py

You should see a response like “The sum of 2 and 2 is 4.”

Understanding the CUGA Harness

CUGA’s lightweight harness consists of three core components:

• **Agent**: The main class that encapsulates the LLM, tools, and memory.
• **Tool**: A callable function that the agent can invoke (e.g., web search, calculator, file reader).
• **Memory**: A short-term context store that helps the agent maintain state across steps.

The harness is designed to be minimal. You define agents in a few lines of code, then compose them into workflows. This contrasts with heavier frameworks like LangChain or AutoGen, which require more boilerplate.

Usage Examples: Two Dozen Working Agents

We’ll walk through 24 practical examples organized by complexity. Each example is a complete, runnable script. For brevity, we’ll show the core logic—assume the agent is initialized as above.

Basic Agents (Examples 1–6)

These agents demonstrate single-turn tasks with built-in tools.

**Example 1: Simple Question Answering**

from cuga import Agent

agent = Agent(model="gpt-4o", provider="openai")
response = agent.run("What is the capital of France?")
print(response)

**Example 2: Math Solver**

agent = Agent(model="gpt-4o", provider="openai")
response = agent.run("Calculate the integral of x^2 from 0 to 3.")
print(response)

**Example 3: Text Summarizer**

agent = Agent(model="claude-3-sonnet", provider="anthropic")
text = "Long article text here..."
response = agent.run(f"Summarize this in 50 words: {text}")
print(response)

**Example 4: Translator**

agent = Agent(model="gpt-4o", provider="openai")
response = agent.run("Translate 'Hello, how are you?' to Spanish.")
print(response)

**Example 5: Code Explainer**

agent = Agent(model="gpt-4o", provider="openai")
code = "def fib(n): return n if n < 2 else fib(n-1) + fib(n-2)"
response = agent.run(f"Explain this code line by line: {code}")
print(response)

**Example 6: Sentiment Analyzer**

agent = Agent(model="claude-3-sonnet", provider="anthropic")
response = agent.run("Analyze the sentiment: 'I love this product, but delivery was slow.'")
print(response)

Tool-Using Agents (Examples 7–12)

These agents use CUGA’s built-in tool system. We’ll define a custom tool first.

**Example 7: Calculator Tool**

from cuga import Tool

def calculator(expression: str) -> str:
    return str(eval(expression))

calc_tool = Tool(name="calculator", func=calculator, description="Evaluate math expressions")
agent = Agent(model="gpt-4o", provider="openai", tools=[calc_tool])
response = agent.run("What is 345 * 678?")
print(response)

**Example 8: Web Search Tool**

import requests

def web_search(query: str) -> str:
    # Simplified search – in production, use a proper API
    return f"Results for {query}: [dummy]"

search_tool = Tool(name="web_search", func=web_search, description="Search the web")
agent = Agent(model="gpt-4o", provider="openai", tools=[search_tool])
response = agent.run("Find recent news about AI agents.")
print(response)

**Example 9: File Reader Tool**

def read_file(path: str) -> str:
    with open(path, 'r') as f:
        return f.read()

file_tool = Tool(name="file_reader", func=read_file, description="Read a file from disk")
agent = Agent(model="claude-3-sonnet", provider="anthropic", tools=[file_tool])
response = agent.run("Read and summarize 'data.txt'.")
print(response)

**Example 10: Python Executor Tool**

def run_python(code: str) -> str:
    exec_globals = {}
    exec(code, exec_globals)
    return str(exec_globals)

python_tool = Tool(name="python_exec", func=run_python, description="Execute Python code")
agent = Agent(model="gpt-4o", provider="openai", tools=[python_tool])
response = agent.run("Compute the first 10 prime numbers using Python.")
print(response)

**Example 11: Date/Time Tool**

from datetime import datetime

def current_time() -> str:
    return datetime.now().isoformat()

time_tool = Tool(name="get_time", func=current_time, description="Get current date and time")
agent = Agent(model="gpt-4o", provider="openai", tools=[time_tool])
response = agent.run("What is the current time in UTC?")
print(response)

**Example 12: Email Sender (Simulated)**

def send_email(to: str, subject: str, body: str) -> str:
    # Simulate sending
    return f"Email sent to {to} with subject '{subject}'"

email_tool = Tool(name="send_email", func=send_email, description="Send an email")
agent = Agent(model="claude-3-sonnet", provider="anthropic", tools=[email_tool])
response = agent.run("Send an email to test@example.com with subject 'Hello' and body 'Test'.")
print(response)

Multi-Step Reasoning Agents (Examples 13–18)

These agents use memory to maintain context across multiple turns.

**Example 13: Sequential Fact Checker**

agent = Agent(model="gpt-4o", provider="openai")
response = agent.run("First, find the population of Tokyo. Then, compare it to New York.")
print(response)

**Example 14: Step-by-Step Problem Solver**

agent = Agent(model="claude-3-sonnet", provider="anthropic")
response = agent.run("Solve: A train leaves Station A at 60 mph. Another leaves Station B at 80 mph. Stations are 300 miles apart. When do they meet?")
print(response)

**Example 15: Research Assistant**

def search_tool(query: str) -> str:
    return f"Summary: {query}"

agent = Agent(model="gpt-4o", provider="openai", tools=[Tool(name="search", func=search_tool, description="Search")])
response = agent.run("Research the history of neural networks. Start with perceptrons, then backpropagation, then transformers.")
print(response)

**Example 16: Task Planner**

agent = Agent(model="claude-3-sonnet", provider="anthropic")
response = agent.run("Plan a 3-day trip to Paris. Include flights, hotels, and attractions. Output as a list.")
print(response)

**Example 17: Code Reviewer**

agent = Agent(model="gpt-4o", provider="openai")
code = "def add(a,b): return a+b"
response = agent.run(f"Review this code for bugs and style issues: {code}")
print(response)

**Example 18: Data Analyzer**

def analyze_data(data: str) -> str:
    return f"Mean: {sum(map(float, data.split(',')))/len(data.split(','))}"

data_tool = Tool(name="analyze", func=analyze_data, description="Analyze comma-separated numbers")
agent = Agent(model="gpt-4o", provider="openai", tools=[data_tool])
response = agent.run("Analyze the dataset: 10,20,30,40,50")
print(response)

Complex Workflows (Examples 19–24)

These examples combine multiple agents or advanced patterns.

**Example 19: Agent with Conditional Logic**

agent = Agent(model="gpt-4o", provider="openai")
response = agent.run("If the stock market is up today, summarize gains. Otherwise, suggest a strategy.")
print(response)

**Example 20: Multi-Agent Debate**

agent1 = Agent(model="gpt-4o", provider="openai", system_prompt="You are a proponent of nuclear energy.")
agent2 = Agent(model="claude-3-sonnet", provider="anthropic", system_prompt="You are an environmentalist against nuclear energy.")

topic = "Should we build more nuclear plants?"
response1 = agent1.run(topic)
response2 = agent2.run(topic)
print(f"Pro: {response1}\nCon: {response2}")

**Example 21: Tool-Orchestrated Agent**

def weather_api(city: str) -> str:
    return f"Weather in {city}: 72°F, sunny"

weather_tool = Tool(name="weather", func=weather_api, description="Get weather")
agent = Agent(model="gpt-4o", provider="openai", tools=[weather_tool, calc_tool])
response = agent.run("Get weather for New York and compute the difference from 80°F.")
print(response)

**Example 22: Persistent Memory Agent**

from cuga import Memory

memory = Memory()
agent = Agent(model="claude-3-sonnet", provider="anthropic", memory=memory)
agent.run("My name is Alice.")
response = agent.run("What is my name?")
print(response)  # Should recall "Alice"

**Example 23: Error-Handling Agent**

agent = Agent(model="gpt-4o", provider="openai")
response = agent.run("Try to divide 10 by 0. If error, explain why.")
print(response)

**Example 24: Self-Improving Agent**

agent = Agent(model="claude-3-sonnet", provider="anthropic")
response = agent.run("Write a short poem. Then critique it and rewrite it better.")
print(response)

Configuration Tips for Production

For real-world deployment, consider these settings:

• **Rate limiting**: Set `max_retries` and `timeout` in the Agent constructor.
• **Logging**: Enable CUGA’s built-in logging with `agent.logger.setLevel("INFO")`.
• **Caching**: Use a `Cache` object to avoid redundant API calls for identical queries.

Example with configuration:

from cuga import Agent, Cache

cache = Cache(ttl=3600)
agent = Agent(model="gpt-4o", provider="openai", cache=cache, max_retries=3, timeout=30)

Conclusion

CUGA’s lightweight harness empowers developers to build real agentic applications with minimal friction. From simple Q&A to multi-step reasoning and tool orchestration, the two dozen examples we’ve covered demonstrate the breadth of what’s possible. By leveraging a familiar Python interface, CUGA reduces the learning curve while maintaining flexibility for advanced workflows. As the AI industry—validated by developments from OpenAI, Anthropic, Microsoft, and the open-source community on Hugging Face—moves toward more autonomous systems, tools like CUGA will be essential for prototyping and production deployment. Start with the installation steps above, experiment with the examples, and adapt them to your own use cases. The era of agentic apps is here, and CUGA makes it accessible.