Build real agentic apps using CUGA: two dozen working examples on a lightweight harness

Open original

The article introduces CUGA, IBM’s open-source agent harness that handles planning, execution loops, tool calls and state management so you only define tools and prompts. It walks through a FastAPI “cloud advisor” example and shows how two dozen single-file apps share the same skeleton for quick setup, governance and scaling.

  • IBM's CUGA harness lets you build agentic apps by defining only tools and prompts—planning, execution, error handling, and state management are all handled by the harness.
  • The cuga-apps repo has two dozen working single-file FastAPI demos, each under 100 lines of code, covering things like a movie recommender and an IBM Cloud architecture advisor.
  • Tools follow a strict success/failure envelope ({"ok": true/false, ...}) so the planner can distinguish recoverable errors from undeclared failures.
  • Built-in Fast/Balanced/Accurate modes tune cost vs. latency without code changes, and the reflection step keeps multi-step runs reliable even with smaller open-weight models like gpt-oss-120b.

CUGA, short for Configurable Generalist Agent, is an open-source harness from IBM that handles the plumbing most agentic apps require—planning loops, tool adapters, state tracking, guardrails and scaling—so developers only supply a tool list and a prompt. The team shipped cuga-apps: two dozen single-file FastAPI demos, from a movie recommender to an IBM Cloud architecture advisor, all under 100 lines of code. You install with pip install cuga, wire up your LLM provider via environment variables (OpenAI, Anthropic, watsonx, LiteLLM, Ollama), list your tools, set special instructions, then call await agent.invoke(...). Everything else—execution, reflection, error handling, variable management—lives inside the harness. One demo, the IBM Cloud advisor, shows the pattern: define a search_ibm_catalog Python function with a docstring, load generic web tools via load_tools(["web"]), and assemble them in a CugaAgent factory. The prompt enforces a catalog lookup before any recommendation and bans made-up service names. State lives in a per-session dict under the hood, driving a live FastAPI UI without a database. Tools must follow a simple envelope convention—{"ok": true, "data": …} or {"ok": false, "code": …, "error": …}—so the planner can recover from expected failures and catch undeclared ones. CUGA’s built-in modes—Fast, Balanced, Accurate—let you tune cost versus latency without code changes, and its reflection step keeps multi-step runs on course, even with smaller open-weight models like gpt-oss-120b.

Ask about this article