Use Cases for AI Agents Basics

python -m venv .venv && source .venv/bin/activate
# optional only if you extend examples with a live model later
# pip install openai

def goal_card(goal: str, done_when: str, tools: list[str]) -> dict:
    return {"goal": goal, "done_when": done_when, "tools": tools}
 
print(goal_card(
    goal="Draft a weekly competitor brief",
    done_when="3 sources cited + 1-page summary saved",
    tools=["web_search", "doc_write"],
))

CATEGORIES = ("coding", "knowledge", "personal", "industry")
 
TASKS = {
    "fix flaky test and open PR": "coding",
    "synthesize 5 papers into a memo": "knowledge",
    "triage inbox and draft replies": "personal",
    "flag suspicious payments for review": "industry",
}
 
for task, expected in TASKS.items():
    assert expected in CATEGORIES
    print(f"{task!r:40} -> {expected}")

def shape_scores(description: str) -> dict[str, int]:
    d = description.lower()
    return {
        "research": sum(w in d for w in ("find", "compare", "cite", "survey")),
        "execution": sum(w in d for w in ("fix", "deploy", "send", "update", "create")),
        "monitoring": sum(w in d for w in ("watch", "alert", "monitor", "track")),
    }
 
print(shape_scores("Compare three vendors and cite sources"))
print(shape_scores("Watch error rates and open a ticket"))

def pick_pattern(path_known: bool, needs_tools: bool, human_judges: bool) -> str:
    if path_known and not needs_tools:
        return "script_or_workflow"
    if human_judges:
        return "copilot_draft_approve"
    if needs_tools:
        return "agent_loop"
    return "single_completion"
 
print(pick_pattern(True, False, False))   # script_or_workflow
print(pick_pattern(False, True, True))    # copilot_draft_approve
print(pick_pattern(False, True, False))   # agent_loop

CHECKS = [
    ("verifiable_goal", True),
    ("branching_on_results", True),
    ("tools_exist_or_cheap", True),
    ("stop_conditions_planned", True),
    ("human_gate_for_writes", True),
    ("eval_tasks_listed", False),  # gap
]
 
def go_nogo(checks: list[tuple[str, bool]]) -> str:
    missing = [name for name, ok in checks if not ok]
    return "GO with caveats" if missing else "GO"
    # treat any missing critical item as NO in real reviews
 
print(go_nogo(CHECKS), "missing:", [n for n, ok in CHECKS if not ok])

candidates = [
    {"name": "repo test fixer", "verify": 5, "tools": 5, "risk": 2},
    {"name": "auto-refund payments", "verify": 3, "tools": 4, "risk": 5},
    {"name": "meeting notes to CRM", "verify": 4, "tools": 3, "risk": 2},
]
 
def score(c: dict) -> float:
    return c["verify"] + c["tools"] - c["risk"]
 
ranked = sorted(candidates, key=score, reverse=True)
for c in ranked:
    print(f"{score(c):4.0f}  {c['name']}")

RED_FLAGS = {
    "irreversible_without_undo": 3,
    "no_tool_api": 3,
    "success_needs_senior_every_time": 2,
    "latency_must_be_one_cheap_call": 2,
    "no_trace_budget": 2,
}
 
def premature(flags: list[str]) -> bool:
    return sum(RED_FLAGS[f] for f in flags) >= 4
 
print(premature(["irreversible_without_undo", "no_trace_budget"]))
print(premature(["latency_must_be_one_cheap_call"]))

from dataclasses import dataclass, asdict
import json
 
@dataclass
class UseCaseBrief:
    name: str
    category: str
    shape: str
    goal: str
    tools: list[str]
    human_gate: str
    stop: str
    eval_n: int
 
brief = UseCaseBrief(
    name="PR review assistant",
    category="coding",
    shape="execution+review",
    goal="Comment on diff risks before human merge",
    tools=["git_diff", "linter_read", "pr_comment"],
    human_gate="human merges; agent cannot approve",
    stop="max 8 turns or review posted",
    eval_n=25,
)
print(json.dumps(asdict(brief), indent=2))