7 Building Blocks of AI Agent Design, Learned from Opencode Docs

Opencode is one of the more talked-about AI coding tools right now. In Korea, its adoption has accelerated thanks to Oh-my-opencode, and developer communities elsewhere are paying attention.

What I find more interesting than the tool itself is how its open-source design exposes the underlying architecture decisions. Because you can inspect exactly how the agent is built, from tool registration to sub-agent orchestration, the Configure section of Opencode’s docs reads almost like an introductory textbook for agent design. Here are the seven building blocks it surfaces, and why each one matters.

Tools: How Agents Interact with the World

Tools define what an agent can do. Each tool is a discrete capability: reading a file, writing to a file, running a terminal command, searching the web, registered as a callable function.

The set of tools you provide determines the agent’s ability boundary. Tools are the interface between the language model and the external environment. From my experience, giving an agent too many tools backfires: it spends more time deciding which tool to use than actually executing. The design principle is straightforward. An agent without tools is a chatbot. An agent with the right tools, and only those tools, is an autonomous worker.

Rules (AGENTS.md): Behavioral Guidelines for Agents

AGENTS.md is a file format that provides project-specific context and constraints to an agent. Think of it as a README written for AI instead of humans.

It contains directives like “never modify code without tests” or “follow this folder structure.” The AGENTS.md standard has already been adopted by over 60,000 open-source projects. Rules shape the agent’s decision-making without changing its underlying model.

Without rules, an agent applies its general training to your specific project. With rules, it applies your project’s conventions, constraints, and preferences. The difference in output quality is substantial, and the rules file itself is cheap to maintain.

Agents (Sub-agents): Divide and Conquer

Complex tasks benefit from being split across multiple specialized agents rather than handled by a single generalist.

You can define role-specific agents: Build, Plan, Review, Debug, and so on. A main agent creates the plan; sub-agents execute individual steps. Each sub-agent operates with a focused context, which reduces the noise and drift that plague long single-agent sessions.

This is the same principle behind microservices applied to AI workflows. Specialization improves quality, and isolation prevents context pollution. That said, coordination overhead is real. Adding sub-agents introduces failure modes that a single agent avoids, so the split is only worth it when the task genuinely requires separate concerns.

MCP (Model Context Protocol): A Standard for External Connections

Model Context Protocol is an open protocol created by Anthropic that standardizes how agents connect to external data sources and services.

It provides a consistent interface for databases, file systems, APIs, and other integrations. Before MCP, every agent framework invented its own way to connect to external tools. MCP makes those connections portable and composable. The ecosystem of MCP-compatible services is growing, though adoption is still early and the spec continues to evolve.

LSP (Language Server Protocol): The Foundation for Code Understanding

Language Server Protocol was originally designed for IDEs, but it is equally valuable for AI agents that need to navigate codebases.

LSP provides go-to-definition, find-references, auto-completion, and diagnostics. In Opencode, LSP integration is still experimental and has known gaps in accuracy. But even partial LSP support improves code navigation meaningfully compared to pure text search. An agent that can follow a function call to its definition, trace all references, and understand type hierarchies operates at a different level than one doing only pattern matching on strings.

A2A and ACP: Standards for Agent-to-Agent Communication

When agents are built with different frameworks, they need a shared protocol to collaborate. Two standards are emerging to fill this gap.

A2A (Agent-to-Agent) was created by Google and donated to the Linux Foundation. It defines how agents discover each other, negotiate capabilities, and exchange messages. ACP (Agent Communication Protocol) was built by the BeeAI team and recently merged into the A2A effort.

Both are in early stages, and it is not yet clear which approach will win adoption. The analogy to HTTP is appealing, a shared transport layer making agents interoperable across vendors and frameworks, but that analogy has been used for many protocols that never reached critical mass.

Skills: Reusable Capability Packages

Agent Skills bundle tools, rules, and prompts into a single installable unit. First introduced by Anthropic, this format is now standardized.

An agent loads a skill when it needs a specific capability: code review, TDD workflow, security analysis. Skills are shareable across projects and teams, creating an ecosystem of reusable agent behaviors. This signals a shift from consuming documentation to consuming skills: instead of reading how to do something, you install the ability to do it. The quality of available skills varies widely right now, and vetting them for a production project requires the same diligence you would apply to any third-party dependency.

The Architecture Behind Effective Agents

Building effective AI agents is not about knowing every tool available. It is about understanding the architecture: how agents think, how they connect to the outside world, and how they collaborate with each other.

These seven building blocks, Tools, Rules, Sub-agents, MCP, LSP, A2A/ACP, and Skills, form the structural vocabulary of agent design. Each addresses a distinct concern. Knowing where each one fits lets you make deliberate choices rather than assembling a system by trial and error.

Because Opencode is open source, its documentation evolves with contributions from the broader developer community. The Opencode docs are a practical starting point for anyone who wants to move from using agents to understanding how they are built.