Goal Engineering

Turn vague objectives into structured, measurable goals — then verify agent output against them

Goal Engineering turns a vague objective into a structured, measurable goal, then verifies agent output against it.

Quick Start

1. Engineer and verify a goal

   Engineer a goal, run your agent against it, then verify the output:

   Python

   from praisonaiagents import Agent, GoalEngineer
   
   agent = Agent(name="Summariser", instructions="Summarise the input")
   engineer = GoalEngineer()
   goal = engineer.engineer("Summarise the report in under 100 words")
   
   output = agent.start(goal.to_prompt())
   result = engineer.verify(goal, output)
   print(result.score, result.achieved)

   TypeScript

   import { Agent, GoalEngineer } from 'praisonai';
   
   const agent = new Agent({ name: 'Summariser', instructions: 'Summarise the input' });
   const engineer = new GoalEngineer();
   const goal = await engineer.engineer('Summarise the report in under 100 words');
   
   const output = await agent.start(goal.toPrompt());
   const result = await engineer.verify(goal, output);
   console.log(result.score, result.achieved);

2. Explicit criteria + constraints

   Provide your own criteria and constraints to skip LLM decomposition:

   from praisonaiagents import GoalEngineer
   
   engineer = GoalEngineer(auto_decompose=False)
   goal = engineer.engineer(
       "Summarise the report",
       criteria=["Under 100 words", "Preserves key findings"],
       constraints=["No hallucinations"],
   )

3. Full control with GoalConfig

   Tune the model, criteria count, and pass threshold:

   from praisonaiagents import GoalEngineer, GoalConfig
   
   engineer = GoalEngineer(config=GoalConfig(
       model="gpt-4o",
       max_criteria=3,
       threshold=7.5,
   ))

How It Works

A statement is decomposed into criteria, the agent runs, and the output is scored by the same Judge used across evaluation.

A judge failure is inconclusive — criteria stay pending and achieved=False, never a real unmet. The result carries an independent snapshot of criteria, so mutating it never corrupts the goal.

Configuration Options

GoalConfig follows the PraisonAI convention: False = disabled, True = defaults, GoalConfig(...) = custom.

Data Model

GoalEngineer works with three dataclasses, all importable from praisonaiagents.

SuccessCriterion

A single measurable condition that contributes to achieving a goal.

Methods: to_dict(), from_dict(data) (classmethod).

Goal

A goal exposes two computed properties in addition to its fields.

GoalVerificationResult

The result returned by verify().

Method: to_dict().

Common Patterns

Weight criteria by importance and track weighted progress:

from praisonaiagents import GoalEngineer

engineer = GoalEngineer(auto_decompose=False)
goal = engineer.engineer("Ship the release notes")
goal.add_criterion("Covers every merged PR", weight=3.0)
goal.add_criterion("Reads clearly", weight=1.0)

print(goal.progress)  # fraction of weighted criteria met, clamped to [0.0, 1.0]

progress is the fraction of weighted criteria currently met, clamped to [0.0, 1.0]. Non-positive weights count as 0; when total weight is 0, criteria count equally.

Reuse one engineered goal across multiple agents via to_prompt():

from praisonaiagents import Agent, GoalEngineer

engineer = GoalEngineer()
goal = engineer.engineer("Draft a launch email under 150 words")

drafter = Agent(name="Drafter", instructions="Write marketing copy")
editor = Agent(name="Editor", instructions="Tighten and proofread")

draft = drafter.start(goal.to_prompt())
final = editor.start(goal.to_prompt() + f"\n\nDraft:\n{draft}")

Persist a goal with to_dict() and restore it with from_dict():

import json
from praisonaiagents import Goal, GoalEngineer

goal = GoalEngineer().engineer("Summarise the report")
saved = json.dumps(goal.to_dict())

restored = Goal.from_dict(json.loads(saved))

Best Practices

Related