Project Definition and Agent Loop

Define an individual agent project and implement its first bounded agent loop.

Course overview · Next

Assignment

Turn the minimal starter into the first working version of your own agent. Choose one narrow task that requires the system to inspect information, observe a result, and decide what to do next. Avoid ideas that can be completed by one model response.

Create a repository from the course template with Use this template, clone it, and verify the setup:

uv sync --locked
cp .env.example .env
uv run pytest

OpenRouter Access

Add the individual course key supplied by the instructor to .env:

MODEL_NAME=google/gemma-4-26b-a4b-it
OPENROUTER_API_KEY=replace-with-your-individual-course-key

Verify the connection from the repository root:

uv run python -c 'from agent_project.llm import OpenRouterClient; print(OpenRouterClient().complete([{"role": "user", "content": "Reply with exactly COURSE_READY"}])["text"])'

The expected output is COURSE_READY. This is a live request and uses a small amount of credit. Your key works only with the course model and has a USD 2 limit for the whole course. Use the mock client in automated tests. Never commit .env, print the key, include it in a trace, or share it.

Then:

  1. Complete the project brief in the root README.md.
  2. Add a small sample of local, public, or synthetic domain data that the agent can inspect.
  3. Implement one or two read-only domain tools.
  4. Implement the agent loop under src/agent_project/.
  5. Provide a command that accepts a natural-language goal and runs the agent.

During a run, the model receives the goal, current state, and available tools. It either requests a tool, asks for clarification, or finishes. Application code validates and executes a requested tool, returns its result to the model, and repeats until the goal, a clear failure, or the step limit is reached. Keep the goal, step count, observations, and final status in explicit state, and record every transition with the supplied JSONL trace helper.

At least one demonstrated goal must require a new decision after observing a tool result. A single model call or a fixed retrieve -> generate pipeline is not an agent for this assignment.

Example

Example agent run for choosing a camera

Follow the same decision pattern in a different domain. You do not need to use cameras or document search.

Deliverables

  • Completed project brief in README.md.
  • A runnable, bounded agent loop with at least one domain tool.
  • Application-side tool validation and structured JSONL traces.
  • Deterministic tests using the mock client.
  • One successful and one unsuccessful recorded run.
  • Setup and execution instructions.

Useful Materials