IBM releases CUGA, an open-source agent harness with two dozen example apps

IBM Research released CUGA, an open-source agent harness intended to reduce the boilerplate required to build agentic applications. The project emphasizes a "harness, not a framework" approach, providing pre-assembled components for planning, execution loops, tool calls, and state management so developers can focus on defining tools and prompts rather than wiring infrastructure.

CUGA includes two dozen working example applications, each packaged as a single FastAPI file wrapping a CugaAgent instance. These examples range from a movie recommender to an IBM Cloud architecture advisor, and are designed to be read, copied, and adapted. The examples are presented in a live gallery for interactive exploration.

The harness supports interchangeable tool bindings, including OpenAPI, MCP, and LangChain functions, allowing developers to mix local and hosted tools without rewriting adapter code. Declarative guardrails, multi-agent delegation over A2A, Docling-powered RAG, and provider switching (e.g., OpenAI, watsonx, Ollama) are provided out of the box.

CUGA introduces configurable reasoning modes—Fast, Balanced, and Accurate—along with configurable code execution sandboxes (local, Docker/Podman, or E2B cloud). These modes allow tuning for cost, latency, and safety without changing the agent definition, enabling the same agent logic to run efficiently across different deployment constraints.

The IBM Cloud architecture advisor example demonstrates the harness's approach: the entire agent is defined in four lines of constructor code, with tools and prompts specified separately. The agent uses a factory pattern to switch providers via environment variables, keeping application code agnostic to the underlying model.

State management is handled by the harness, with intermediate results tracked and reflected upon to catch errors and re-plan as needed. This reduces the risk of cascading failures in long-horizon tasks, a common failure mode for agentic systems.

CUGA's design is motivated by the observation that most agentic apps begin with a week of plumbing before the agent can do useful work. By inverting this workflow, IBM Research aims to shift the focus from infrastructure to application logic, while still supporting governance and scalability for production deployments.