omninoun.05 / THE AI AGENTS HANDBOOK
Understand agents, their tools, orchestration and limitations. A handbook to explore at your own pace.
THE COMMON THREAD
A model generates. A tool acts within a defined scope. An agent combines instructions and tools to pursue a mission. The system defines contracts, supervises actions and retains evidence.
Useful autonomy includes boundaries, the ability to abstain and stopping criteria. Explore the ten OEP principles.
Artificial intelligence is no longer just a chatbot answering questions like ChatGPT or Claude. We are entering the age of execution.
AI becomes operational.
It no longer just advises, it acts. We develop systems capable of making decisions, executing complex tasks, and learning from their errors.
The goal is to free humans from repetitive tasks to focus on strategy and creation.
Most companies use AI in isolation: an employee copies-pastes text into an LLM, retrieves the result, and processes it manually. This is a waste of time and efficiency.
The true ROI of AI lies in global orchestration and automation of processes via connected workflows.
Our approach is based on the interconnection of four major technological pillars:
Strategic thinking and decision-making engines.
Workflow orchestration and data flow.
Long-term memory and targeted business context.
Connection to business tools (CRM, ERP, Slack).
We deploy concrete solutions to accompany this transformation:
Help managers and teams develop the skills to integrate AI into their daily operations.
An internal tool to structure perfect instructions and obtain optimal results without hallucination, ensuring output reliability.
Our philosophy: technical rigor, rejection of superficial jargon, and implementation of robust architectures (Docker, Controlled Cloud, Sovereignty).
Moving from a reactive approach to an AI-augmented company.
Before choosing a model, understand there is no universal best model. There are profiles adapted to specific use cases. Here's the taxonomy structuring this guide.
These models excel at generating interfaces: React components, Tailwind, animations, landing pages and clean HTML/CSS. They have a good sense of visual rhythm and quickly produce usable frontend code.
These models think before acting. They break down problems, identify edge cases and propose solid structures. Excellent for complex debugging, refactoring and architecture decisions.
These models are optimised for agentic workflows: tool calling, execution loops and task chains. They can use tools, correct themselves and progress through multiple steps without constant supervision.
These models have been extensively trained on code. They understand framework nuances, produce correct and consistent code and handle multi-file projects well.
These models offer strong value for money. Suitable for repetitive tasks, high-volume pipelines, secondary agents and data preprocessing.
These models handle contexts of hundreds of thousands of tokens. Useful for analysing large codebases, long documents or maintaining consistency over extended sessions.
For each model or use case, evaluate it on these 5 axes:
| Axis | What it measures | Questions to ask |
|---|---|---|
| Speed | Generation speed | Do I need immediate results? |
| Depth | Reasoning quality | Is the problem complex or simple? |
| Cost | Price per token/request | What is the usage frequency |
| Autonomy | Agentic capability | Should it act alone or just respond |
| Creativity | Originality of outputs | Is this creative or technical work |
Using the same model for everything because it is simple or familiar is the most common trap. It can also become costly and inefficient over time.
Using GPT-5 to generate simple CSS is like taking a taxi to fetch bread.
Benchmarks measure performance under controlled conditions. They do not measure what matters most: quality on your specific task, in your context, with your constraints. The best model is the one that finishes your work quickly and cleanly, with few retries.
False. Modern low-cost models (Gemini Flash, DeepSeek, Haiku) can perform 80% of a premium model’s work for 10% of the price. The real skill is knowing when to pay for capability and when to save.
A structured technical overview of tools, environments and protocols used in software engineering and automation with autonomous agents.
Autonomous execution systems interacting directly with the code lifecycle: IDEs, CLIs, sandbox environments and Git.
| Agent | Technical description | Official link |
|---|---|---|
| Claude Code | Anthropic’s native CLI agent, running locally in the terminal. It can read codebases, run tests, manage Git and use MCP servers. | Visit website |
| OpenAI Codex CLI | A command-line interface using Codex/GPT models to translate natural-language instructions into executable scripts. | Visit website |
| Gemini CLI | A command-line tool for interacting directly with the Gemini API for refactoring and large-context code analysis. | Visit website |
| Cursor Agent | An advanced agent mode integrated into the Cursor IDE, capable of planning and applying multi-file changes autonomously. | Visit website |
| Windsurf | An agent-native IDE coordinating real-time collaborative workflows between the developer and the agent (Cascade). | Visit website |
| Aider | A Git-focused command-line coding assistant for editing existing repositories with commit tracking. | Visit website |
| Goose | A model-agnostic open-source agent (Block/Agentic AI Foundation). Runs directly on the machine through CLI or desktop to automate build and refactoring recipes without requiring Docker. | Visit website |
| OpenHands | Successor to OpenDevin. An open-source platform allowing autonomous software agents to modify code and execute commands in a secured Docker sandbox. | Visit website |
| Amp | A coding agent developed by Sourcegraph, using its code intelligence engine and semantic repository indexing. | Visit website |
| Freebuff | An open-source community alternative focused on modifying local codebases. | Visit website |
| Codebuff | An assistant specialising in navigating, refactoring and rewriting large software projects. | Visit website |
| Pi Coding Agent | A recent autonomous agent designed to resolve complex architecture tickets and generate unit tests. | Visit website |
Workspaces and cloud IDEs where agents collaborate with users synchronously or asynchronously.
High-level frameworks managing task distribution, memory and multi-agent collaboration.
Agents specialising in DOM interaction, browsing and automating web processes on behalf of a person.
Integration platforms connecting LLMs and agents to databases and third-party APIs through pipeline architectures.
Core libraries and SDKs for developing custom cognitive architectures.
The standardised layer for structured communication between agents, servers and clients.
| Protocol | Technical role | Importance / maturity |
|---|---|---|
| MCP (Model Context Protocol) | An open standard developed by Anthropic connecting models to secured data sources (GitHub, Slack, SQL databases and Docker environments) through a unified API. | ⭐⭐⭐⭐⭐ |
| A2A (Agent-to-Agent) | An emerging specification for message routing, subtask delegation and context negotiation between separate autonomous systems. | ⭐⭐⭐⭐⭐ |
| ACP (Agent Communication Protocol) | An open inter-agent messaging standard supporting consistent formatting and integrity across distributed communications. | ⭐⭐⭐⭐ |
| OpenAPI Specification | A formal description of REST API endpoints, allowing agents to generate HTTP requests dynamically without human intervention. | ⭐⭐⭐⭐ |
| JSON Schema | Strict definitions of input/output data structures. Essential for constraining model Structured Output and avoiding type-parsing errors. | ⭐⭐⭐⭐ |
| OAuth 2.0 | An authorisation delegation framework allowing agents to access third-party resources securely on the user’s behalf. | ⭐⭐⭐⭐ |
| SSE (Server-Sent Events) | A one-way streaming protocol for receiving token streams in real time (token streaming) and agent execution logs. | ⭐⭐⭐ |
| WebSocket | A persistent bidirectional communication channel for real-time state synchronisation and synchronous multi-agent collaboration. | ⭐⭐⭐ |
The word "agent" is everywhere. It's often misused. Here's the definition that matters operationally:
An AI agent is a model that can take actions in the real world: call APIs, read files, write code, browse the web and send messages, chaining those actions autonomously to pursue a goal.
What distinguishes an agent from a simple chatbot:
An agent doesn't respond — it does.
The most common confusion in AI projects is mixing two roles that must remain separate:
| Orchestration | Execution |
|---|---|
| Decides what to do | Does what is decided |
| Chooses the right agent for each task | Executes a specific task |
| Handles errors and redirects | Reports errors |
| Maintains global vision | Maintains local focus |
| Models: Claude Sonnet, GPT-5 | Models: DeepSeek, Haiku, Gemini Flash |
Classic error: using a powerful and expensive model for executing simple tasks. Result: exploding bill, unnecessary latency, no quality gain.
The right approach: lightweight model for execution, intelligent model for orchestration — and human for final supervision.
Before launching anything, you decompose. Practical example:
Objective: Create a user profile page with photo, bio, and activity history
Each step is clear, assignable, verifiable. That's agentic decomposition.
Routing is the real-time decision: For this specific task, which model?
Routing criteria:
A good routing system can automate these decisions. But even manually, developing this reflex changes everything.
Agents don't do everything right the first time. The strength is in the loop:
This loop short-circuits the mental model I send a prompt and hope. It replaces hope with control.
A major problem with agents: they forget. Most models don't have persistent memory between sessions.
Practical solutions:
Human supervision has a cost: your time and attention. It must be reserved for moments when it adds value.
| Supervise actively | Let run |
|---|---|
| Irreversible decisions | Repetitive, tested tasks |
| First execution of a workflow | Stable pipelines with logs |
| Public or client outputs | Internal preprocessing |
| Large amounts / sensitive data | Classification / low-value extraction |
| New agents / tools | Agents already validated on hundreds of cases |
The golden rule: supervise until you have confidence. Let go once you have reliable quality metrics.
Giving an agent access to critical systems before validating its behavior on simple cases. Result: badly executed irreversible actions.
Rule: always start in read-only mode, then grant permissions progressively.
Launching an agent on a long task without passing relevant history. It forgets the beginning, produces incoherent outputs.
Rule: Always include the minimum necessary context: neither too much (context pollution) nor too little (loss of consistency).
Using a premium model for all pipeline steps, including the simplest. Result: bill x10 with no quality gain.
Rule: profile each step, assign the cheapest model that does the job well.
“Do something interesting with this data.” Agents handle ambiguity less well than people. The result: unpredictable outputs and repeated retries.
Rule: Be as precise as you would with a junior colleague: expected format, constraints and examples where possible.
A pipeline that doesn't anticipate what happens when an agent fails. It crashes, nothing continues.
Rule: Always plan a fallback: another model, a reduced output or a human alert.
Moving from theory to production involves implementing agentic thinking on your machine (through configuration files such as CLAUDE.md or .clauderc) using a six-step protocol. This workflow is intended to turn a simple chatbot into a reliable autonomous software engineer.
Before any changes, the agent enters a planning phase. It maps the directory structure, inspects dependencies and lists affected files. A written action plan is submitted for approval before execution.
Before writing or changing code, begin a planning phase. Analyse the existing directory structure, read the necessary files and write a structured action plan. Wait for my explicit approval before execution.
To avoid context overload, the main agent delegates to specialised sub-agents. Each handles a focused task such as tests, parsing or UI, supporting precision and modularity.
For complex tasks involving more than three files or different technologies, such as frontend and backend, act as an orchestrator. Break down the work and generate focused micro-prompts for your sub-agents or your own future iterations.
The agent reviews and critiques its own code before submission. It checks for security issues, duplication, unnecessary complexity and missing types. Corrections are applied within this short loop.
After writing code, critically review it before presenting it. Check for security flaws, duplication (DRY), unnecessary complexity (KISS) and missing types. Correct your own errors during this phase.
A task is validated only after unit tests and the production build succeed. Otherwise, it remains open.
Do not declare a task complete or ask me to test it unless you have run the project’s tests and production build in the terminal. Successful execution of these commands is the acceptance criterion.
Code should remain simple, robust and readable. Avoid over-engineering or heavy frameworks when a native solution is sufficient. Prefer elegance to unnecessary complexity.
Seek architectural simplicity. Do not propose over-engineering or heavy frameworks when a simple native solution is suitable. Keep code minimal, modern, readable and documented to explain why it exists.
When tests or builds fail, the agent analyses logs, isolates the bug and proposes a correction. It repeats the edit loop without involving a person unless the blocker persists.
If a test or build command fails at step 4, do not interrupt execution to ask for help. Analyse the logs, locate the failing line, form a new hypothesis and correct the issue autonomously.
This guide is designed to be read and re-read as you progress. Here's how to approach it based on your current level.
You're discovering AI models or just started using them in your workflow.
You already use several models but intuitively, not yet systematically.
A simple agent that takes a React component specification, breaks it into steps and generates each part with an appropriate model. Keep it simple, while learning to think in workflows.
You master the basics and want to build robust agentic systems.
How do you build a system that remains reliable as its autonomy increases? Through tests, metrics, logs and progressively adjusted supervision.
| Level | Core skill | Typical setup | Next step |
|---|---|---|---|
| Beginner | Choose the right model for each use | Gemini + Qwen + 1 premium | Apply a stack pattern |
| Intermediate | Combine models, decompose tasks | SaaS or Low-cost Stack | Build a first simple agent |
| Advanced | Orchestration, routing and robust pipelines | Budget elite setup | Multi-agent architecture with metrics |
Key terms of this guide, defined without unnecessary jargon.
To quickly choose the right model according to the situation:
| Situation | Recommended model | Reason |
|---|---|---|
| Standard React/frontend framework component | Gemini Flash | Speed + frontend quality |
| Complex backend API model | Qwen 3.6 Plus | Excellent Python/ORM |
| Inexplicable bug | GLM-5 or Claude Sonnet | Deep reasoning |
| Creative landing page | Kimi K2.5 | Visual creativity |
| Automated pipeline | DeepSeek V4 | Very low cost, tool calling |
| Small CSS correction | Claude Haiku | Fast and cheap |
| Critical system architecture | Claude Sonnet / GPT-5 | Maximum intelligence |
| Long session (100k+ tokens) | Gemini or Claude | Large context |
| Massive multi-file refactoring | Claude Sonnet | Coherence on large context |
| High-volume testing/classification | DeepSeek or Haiku | Volume + cost |
The AI model market changes quickly. A model recommended today may be surpassed in six months. New competitors can emerge overnight.
This guide needs regular updates. Principles such as agentic thinking, orchestration, routing and stack patterns remain useful, while recommendations for specific models evolve.
Treat it as a living system: record your observations, add your use cases and challenge anything that no longer fits your reality.
The best guide is the one you adapt to your reality.
No passages found. Try another search term.