Mastering Agentic Tools

Introduction: From Chatbot to Agent

Welcome to Lesson 4 of the Foundation Course. In the previous lessons, you learned how to configure OpenCode, manage sessions, switch between models, and toggle between Build and Plan agents. Now we explore the most important concept in this entire course: Agentic Behavior . Most people are accustomed to chat-based AI like ChatGPT or standard chatbots. You ask a question, receive text or code snippets, and then must copy, paste, and run everything yourself. If an error occurs, you copy the error message and paste it back into the chat for another round of suggestions. This back-and-forth can be tedious and slow. OpenCode is fundamentally different because it is an Agent, not just a chatbot. An agent does not merely talk — it takes action. It has "hands" in the form of tools that allow it to read files, create scripts, edit code, and run commands directly on your machine. Think of the difference between asking a friend for driving directions versus having them actually drive you to your destination. That is the leap from chatbot to agent. In this lesson, you will learn to shift your mindset from "doing everything yourself" to "managing a capable worker." You describe what you want to happen, and OpenCode figures out how to use its tools to make it happen. We will cover how the agent selects tools automatically, how to point it to specific files using the @ symbol, and how it can even fix its own mistakes when things go wrong.

The Agent's Toolbox

To act autonomously, an agent needs tools. Just as a carpenter has a hammer and saw, OpenCode has a set of digital tools that allow it to interact with your computer. These tools are built into the system, and the agent knows exactly when to use each one based on your request. Here are the core tools available to the agent: Tool Purpose Example Use read Opens and reads file contents Understanding existing code write Creates a new file Starting a new script edit Modifies parts of an existing file Adding a function, fixing a bug glob Finds files matching a pattern Locating all .py files grep Searches for text inside files Finding where a function is called bash Runs terminal commands Executing scripts, installing packages The most important point to remember is that you do not need to tell the agent which tool to use. You never type "please use the write tool." Instead, you simply say "create a file," and the agent intelligently selects the write tool. You say "run the script," and it uses bash . This abstraction lets you focus on your goals rather than the mechanics. You can ask the agent to describe its capabilities directly in a session: text > What tools do you have access to? I have access to several tools that I use automatically based on your requests: File Operations read - Read file contents write - Create new files edit - Modify existing files glob - Find files by pattern grep - Search within files Command Execution bash - Run shell commands I select these tools automatically based on what you're trying to accomplish. You don't need to tell me which tool to use - just describe what you want! By understanding that these tools exist, you can be more confident in asking for complex tasks, knowing the agent has the means to execute them. You are not limited to receiving code snippets — you can request complete workflows.

Tool	Purpose	Example Use
`read`	Opens and reads file contents	Understanding existing code
`write`	Creates a new file	Starting a new script
`edit`	Modifies parts of an existing file	Adding a function, fixing a bug
`glob`	Finds files matching a pattern	Locating all `.py` files
`grep`	Searches for text inside files	Finding where a function is called
`bash`	Runs terminal commands	Executing scripts, installing packages

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Referencing Files with the @ Syntax

When working with an agent, context is everything. If you have a project with dozens of files, the agent does not read all of them at once because doing so would be slow and expensive in terms of tokens. You need a way to tell the agent, "Look at this specific file while answering my question."

OpenCode uses the @ symbol followed by a filename to explicitly reference a file. This is similar to tagging a person on social media, but here you are tagging a document. When you use @filename, the agent prioritizes reading that file before generating its response. This ensures its answer is based on your actual code rather than general knowledge or assumptions.

For example, if you want to understand a script named analyzer.py, you would type:

text

> @analyzer.py What does this file do?

● Reading analyzer.py...

This file provides simple text analysis utilities with three functions:

  count_characters(text)
    Returns the total number of characters in the text.

  count_sentences(text)
    Counts sentences by looking for period, exclamation, and question marks.

  average_word_length(text)
    Calculates the average length of words, stripping punctuation.

These are utility functions you could import into other scripts for basic
text analysis tasks.

> @analyzer.py What does this file do?

● Reading analyzer.py...

This file provides simple text analysis utilities with three functions:

  count_characters(text)
    Returns the total number of characters in the text.

  count_sentences(text)
    Counts sentences by looking for period, exclamation, and question marks.

  average_word_length(text)
    Calculates the average length of words, stripping punctuation.

These are utility functions you could import into other scripts for basic
text analysis tasks.

Notice how the agent explicitly shows ● Reading analyzer.py... before providing its explanation. This transparency confirms that the response is grounded in the actual file contents.

Best practice: Use the @ syntax whenever your request involves specific code. It reduces hallucinations (where the AI guesses incorrectly about code it hasn't seen) and ensures the agent has the exact data it needs to assist you accurately.

You can also reference multiple files in a single request:

text

> @app.py @utils.py How do these two files work together?

> @app.py @utils.py How do these two files work together?

The agent will read both files and provide an explanation of their relationship, imports, and data flow.

One of the most powerful features of an agent is Task Decomposition — the ability to break a complex request into smaller, manageable steps. Previously, you might have done this manually: first ask for code, then copy it, save it to a file, run it in terminal, read the output, and repeat. With OpenCode, you can chain these steps together in a single request.

Imagine you want to create a Python script that counts words in a text file and then immediately run it to see the results. Instead of multiple back-and-forth messages, you can ask for everything at once:

text

> Create a Python script called word_counter.py that reads sample.txt, counts the words, and prints the total. Then run it to show me the result.

> Create a Python script called word_counter.py that reads sample.txt, counts the words, and prints the total. Then run it to show me the result.

The agent automatically decomposes this into three distinct steps:

Read sample.txt to understand its structure
Write the word_counter.py script with appropriate logic
Execute the script using bash and display the output

You will see this happen in real-time:

text

● Reading sample.txt...
● Creating word_counter.py...

✓ Created word_counter.py

● Running: python word_counter.py

Total words: 78

Done! The script reads sample.txt and counts 78 words.

● Reading sample.txt...
● Creating word_counter.py...

✓ Created word_counter.py

● Running: python word_counter.py

Total words: 78

Done! The script reads sample.txt and counts 78 words.

Notice how the agent performed a read, a write, and a bash execution — all from one prompt. This allows you to work at a higher level of abstraction, focusing on the outcome while the agent handles the implementation details. You become a director rather than a typist.

Iterative Development Through Conversation

Software development is rarely a straight line; it is a cycle of continuous improvement. You write a basic version, test it, add a feature, test again, refine, and repeat. OpenCode excels at this iterative development style because the agent remembers the conversation history and the changes it has made. You do not need to restate the entire problem with each request.

After the agent creates the initial word_counter.py, you might decide you want more detailed statistics. You can simply say:

text

> Update word_counter.py to also count the number of lines and unique words.

● Editing word_counter.py...

✓ Modified word_counter.py

● Running: python word_counter.py

Total lines: 8
Total words: 78
Unique words: 61

Updated! Now shows lines, total words, and unique words.

> Update word_counter.py to also count the number of lines and unique words.

● Editing word_counter.py...

✓ Modified word_counter.py

● Running: python word_counter.py

Total lines: 8
Total words: 78
Unique words: 61

Updated! Now shows lines, total words, and unique words.

The agent understands that "Update" means it should use its edit tool rather than rewriting the entire file. It remembers what word_counter.py contains, so it only modifies the necessary parts while preserving the existing structure.

This conversational style mirrors natural development workflows. You start with a simple implementation and add complexity step-by-step:

text

> Now add a function to show the five most common words

> Also make it ignore common words like "the", "a", "an"

> Can you add a command-line argument so I can specify any input file?

> Now add a function to show the five most common words

> Also make it ignore common words like "the", "a", "an"

> Can you add a command-line argument so I can specify any input file?

Each request builds on the previous work. The agent maintains context across the entire conversation, making development feel like a collaborative dialogue rather than isolated commands.

Self-Correction and Error Recovery

Perhaps the most impressive aspect of agentic AI is the ability to fix its own mistakes. In traditional coding, encountering an error means everything stops until you manually identify and fix the problem. With OpenCode, error messages are automatically fed back to the agent, allowing it to diagnose and resolve issues without your intervention.

Let's say you ask the agent to add a feature that requires the Counter class from Python's collections module:

text

> Update the script to also show the most common word using the Counter class, then run it.

● Editing word_counter.py...

✓ Modified word_counter.py

● Running: python word_counter.py

Traceback (most recent call last):
  File "word_counter.py", line 1, in <module>
    from collections import Counter
ModuleNotFoundError: No module named 'collections'

The script encountered an error.

> Update the script to also show the most common word using the Counter class, then run it.

● Editing word_counter.py...

✓ Modified word_counter.py

● Running: python word_counter.py

Traceback (most recent call last):
  File "word_counter.py", line 1, in <module>
    from collections import Counter
ModuleNotFoundError: No module named 'collections'

The script encountered an error.

In a traditional workflow, you would read this traceback, diagnose that the import statement has an issue (perhaps a typo or environment problem), and manually correct it. With OpenCode, you can simply ask:

text

> There's an error, can you fix it?

● Reading error output...

I see the issue. The collections module is built into Python, so this error
suggests something else is wrong. Let me check the script and fix it.

● Reading word_counter.py...
● Editing word_counter.py...

✓ Fixed word_counter.py

● Running: python word_counter.py

Total lines: 8
Total words: 78
Unique words: 61
Most common word: 'the' (5 times)

Fixed! The script now shows all statistics including the most common word.

> There's an error, can you fix it?

● Reading error output...

I see the issue. The collections module is built into Python, so this error
suggests something else is wrong. Let me check the script and fix it.

● Reading word_counter.py...
● Editing word_counter.py...

✓ Fixed word_counter.py

● Running: python word_counter.py

Total lines: 8
Total words: 78
Unique words: 61
Most common word: 'the' (5 times)

Fixed! The script now shows all statistics including the most common word.

This self-correction loop drastically reduces debugging frustration. The agent reads the error output, hypothesizes what went wrong, applies a fix, and verifies the solution by running the code again. It acts as a partner that not only writes code but also cleans up after itself.

The self-correction capability extends to more complex scenarios as well:

Error Type	Agent Response
Missing import	Adds the required import statement
Missing dependency	Runs `pip install` to install the package
Syntax error	Identifies and fixes the malformed code
Runtime exception	Analyzes the traceback and modifies logic
File not found	Creates the missing file or corrects the path

You do not need to be an expert debugger — you can simply report "it's not working" and let the agent investigate.

In this lesson, you explored the power of Agentic AI and how it differs from traditional chatbots. You learned that:

Concept	What It Means
Tools	OpenCode autonomously selects tools like `read`, `write`, `edit`, and `bash` to fulfill your requests
@ Syntax	Using `@filename` ensures the agent reads the correct file before responding
Task Decomposition	A single prompt can trigger a sequence of reading, writing, and executing
Iterative Development	The agent remembers context, so you can refine code through conversation
Self-Correction	The agent can read error messages, diagnose problems, and fix them automatically

You have now moved from simple configuration commands to complex, multi-step workflows. The key mindset shift is this: describe your goals, not your steps. Tell the agent what you want to achieve, and trust it to figure out how to get there.

In the next practice session, you will put these concepts into action by working with an existing codebase, using the @ syntax to explore files, chaining multiple operations together, and watching the agent handle errors autonomously.

Introduction: From Chatbot to Agent

The Agent's Toolbox

Join the 1M+ learners on CodeSignal

Referencing Files with the @ Syntax

Automatic Task Decomposition

Iterative Development Through Conversation

Self-Correction and Error Recovery

Summary and Next Steps