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

Opencode is quickly becoming the second most talked-about AI coding tool after Claude Code. In Korea, its adoption has accelerated thanks to Oh-my-opencode, and developer communities worldwide are paying attention.

But the real value of Opencode goes beyond coding assistance. Because it’s open source, you can inspect exactly how the agent is designed - from tool registration to sub-agent orchestration. Open-source projects benefit from contributions by developers across the community, which means the documentation reflects the most current thinking in agent architecture.

The Configure section of Opencode’s docs reads 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 just a chatbot. An agent with the right tools becomes 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 is already 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 is substantial.

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.

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
• Instead of writing custom adapters for every service, MCP gives agents a unified way to reach outside their sandbox
• Expect a growing ecosystem of service applications built on the MCP layer

MCP solves a real interoperability problem. Before it, every agent framework invented its own way to connect to external tools. MCP makes those connections portable and composable.

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

Language Server Protocol was originally designed for IDEs, but it turns out to be 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, but it significantly improves code navigation accuracy
• Instead of relying purely on text search, agents can use LSP to understand code structure semantically

An agent that can follow a function call to its definition, trace all references, and understand type hierarchies operates at a fundamentally different level than one that only does 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): 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): Built by the BeeAI team and recently merged into the A2A effort

Both are in early stages, but they represent the foundation for multi-agent systems where agents from different vendors and frameworks work together seamlessly. The analogy is HTTP for the web - a shared transport layer that makes everything interoperable.

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 - like code review, TDD workflow, or 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

Skills are to agents what packages are to applications. They modularize expertise and make it distributable.

The Takeaway

Building effective AI agents isn’t about knowing every tool available. It’s 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 one addresses a distinct concern, and together they define what a well-architected agent system looks like.

Because Opencode is open source, its documentation evolves with contributions from the broader developer community. If you’re serious about understanding agent architecture, the Opencode docs are worth reading through.