Working with Agents

Developers now write code with agents. Instead of manually typing every line, they delegate a large amount of work to agents.

In the fundamentals course, we learned the core behavior behind agents: give them powerful tools and let them work in a loop toward a larger goal. Here, we will learn how to work effectively with those agents.

Agent harness

OpenCode is a coding agent that runs inside a "harness": the infrastructure that determines how the agent operates.

• Instructions: system prompts and rules that guide behavior.
• Tools: file access, terminal commands, search, and other actions.
• Model: the agent model you choose for the task.
• Context: files, conversation history, command output, and repository knowledge.

A coding agent helps you complete tasks from the goal you provide. OpenCode invests heavily in choosing leading models, optimizing the harness, and giving the agent the right tools for coding.

Writing effective prompts

The first entry point when working with an agent is the prompt you give it. Compare two approaches:

Vague prompt:

Build a settings page.

The agent has to guess everything: the layout you want, the components, the styling approach, and more. The result may need many iterations.

Constrained prompt:

Build a settings page for user notification preferences.
Look at the existing profile page in `src/app/profile/page.tsx` for our layout patterns.
Use the same form components from `src/components/ui/Form.tsx`.
The settings should include:
- Email notifications
- SMS notifications
- Weekly digest

Save settings using the existing useUserPreferences hook.
Follow the same API route pattern in `src/app/api/user/profile/route.ts`.

The second prompt is much better because it gives specific instructions grounded in your codebase.

Managing your context

As you work with agents, the conversation builds context: messages, tool calls, file contents, and more. This context grows with each turn.

Watch how much context the agent is using. Start a new conversation when you switch tasks, because context from the previous task will only fill the window without adding value.

Recent models have become very good at finding context for you. When given tools such as semantic search, they can find relevant files, symbols, and even previous conversations on their own.

Avoiding scope creep

One of the most common mistakes is asking for a change that is too large without planning. You give one ambitious request, and the agent ends up modifying dozens of files in unexpected ways.

If you see this happen, stop and consider whether the task can be broken into smaller steps. We will cover this more in the feature-building section.

What you learned

You learned how an agent harness works, how to think about effective prompts, and how to manage context. In the next lesson, you will learn how to navigate and understand a large codebase.