agentic-loops

Agentic Loops: Agents, Tools, Workflows

Structured patterns for building multi-turn agents that reason, act, and observe.

An agentic loop is:

1. Think: Agent reasons about task → decides action
2. Act: Call tools / take action
3. Observe: Get result, update state
4. Repeat: Loop until task complete

Minimal Loop — use the tested implementation, don't hand-roll this

Don't write a bespoke think/act/observe loop from scratch — it's easy to get the tool-result protocol wrong (feeding a tool's result back as a plain "user" message loses the call binding and looks like human input to the model, instead of {"role": "tool", "tool_call_id": ..., ...}), easy to leave out a budget (infinite loop if the model never stops calling tools), and easy to skip argument validation (a malformed tool call reaches your tool function instead of being rejected).

agent_loop.py, bundled alongside this file (a symlink back to patterns/agentic-loops/agent_loop.py, so it resolves whether you installed the whole harness or only this one skill), is a minimal, tested (100% coverage), provider-neutral implementation that gets these right: JSON-Schema-validated arguments, provider-correct tool-result messages, an iteration + wall-clock budget, an optional approval hook, and an auditable trace that never logs raw tool output. See patterns/agentic-loops/README.md in the full harness checkout for the complete usage example and what it does not cover (sandboxing, prompt-injection handling, real cost accounting, cancellation, retries/idempotency, persistence, evals) — that guide isn't bundled with this skill since it's documentation, not something the skill needs to function.

# Run from this skill's own directory, or add it to sys.path — see
# test_agent_loop.py (also bundled here) for a runnable example.
from agent_loop import Budget, ToolSpec, run_agent_loop

tool = ToolSpec(name="add", fn=add, parameters_schema={...})  # JSON Schema
result = run_agent_loop(
    model_fn=my_provider_adapter,  # translates to/from your provider's native shape
    tools={"add": tool},
    messages=[{"role": "user", "content": "What is 2 + 3?"}],
    budget=Budget(max_iterations=5, max_seconds=30),
)