Agent Architecture, Tool Schemas, and Run-Log Diagnosis
Decide one agent vs. many, pick the orchestration pattern, write tool schemas, and diagnose run logs for cost, loops, and latency.
Before & after
Same prompt, same agent — the only difference is the skill.
Building a multi-agent system requires thinking about how different agents will coordinate work. You might have some agents gathering data while others process it. Communication patterns are important - you could use a central controller to orchestrate tasks or have agents pass messages directly. There are different orchestration approaches like supervisor patterns or pipeline architectures. You'd also need to think about error handling and what happens if one agent fails. Tool definitions are important so agents know what capabilities they have available. Performance and cost can be concerns depending on how many agents you need.
RESEARCH AGENT SYSTEM ARCHITECTURE:
ORCHESTRATION PATTERN: SUPERVISOR + SPECIALIZED AGENTS
Supervisor Agent (Claude 3.5 Sonnet)
- Receives research goal from user
- Decomposes into sub-tasks
- Delegates to specialist agents
- Aggregates results into final report
Data Gathering Agent (Claude 3.5 Haiku, optimized for speed)
- Tools: web_search, fetch_url, read_pdf, query_database
- Responsibility: Find primary sources, extract structured facts
- Output: Annotated findings with source citations
Synthesis Agent (Claude 3.5 Sonnet)
- Receives gathered facts
- Identifies patterns, contradictions, consensus
- Ranks claim credibility
- Output: Narrative synthesis + uncertainty labels
Report Agent (Claude 3.5 Haiku, cost-optimized for formatting)
- Templates: executive summary, detailed findings, appendix
- Tool: generate_markdown, render_charts
- Output: Ready-to-share research report
TOOL SCHEMA DEFINITIONS
web_search: { query, max_results, date_range }
fetch_url: { url, extract_section }
query_database: { table, filters, limit }
COST/LATENCY BREAKDOWN
• Total per research task: ~15-25 tokens (Sonnet) + 8K tokens (Haiku)
• Latency: parallel agent execution = ~45 seconds
• Bottleneck: data gathering (network I/O), not inference
FAILURE HANDLING
- If data agent timeout: skip source, note in final report
- If synthesis fails: supervisor retries with subset
- If report gen fails: return raw markdown output
About this skill
Your agent picks the wrong tool, loops until it hits max turns, or costs ten times what you expected, and you can't tell which part is broken. Generic advice says add more agents. This skill starts by asking whether you need more than one agent at all. It writes tool schemas the model can actually choose between, and it reads your traces to find the specific step that is burning money.
What it does
- Decides one agent vs. several, based on four concrete reasons to split. If none applies, it tells you to stay with one agent.
- Picks pipeline, supervisor/workers, handoff, or evaluator loop, and says when routing should be plain code instead of an LLM.
- Specifies each agent's inputs, tool allowlist, output schema, stop condition, turn cap, and token budget.
- Writes tool schemas in Anthropic or OpenAI format, including when-not-to-use lines, enums, and actionable error returns.
- Turns raw run logs into a step table, then computes cost per step and p50/p95 latency.
- Spots context bloat, duplicate calls, retry storms, and flaky tools, and ranks fixes by estimated savings.
What you get
You get an architecture spec with a justified pattern, ready-to-paste tool schemas, or a ranked bottleneck report with the arithmetic shown. The answer is sized to what you asked.
Best for
Engineers building LLM agents on the Anthropic or OpenAI APIs or on agent frameworks, plus anyone debugging an agent that is slow, expensive, or unreliable in production.
SKILL.md preview
---
name: agent-architecture-tool-schemas-run-logs
… (sign up to view the full skill)More ai & agents skills
View all AI & Agents skills →New Skill Scaffolder
Create a new Claude Code skill correctly: right mechanism, valid name and folder, a triggering description, and a smoke test.
Skill Library Lint and Overlap Report
Lint every skill in a repo at once: frontmatter, name-folder match, weak descriptions, overlapping triggers, broken refs, plus a CI script.
Self-Verifying Agent Loop: Plan, Check, Retry, Close
Turns a goal into a task plan with machine-run checks, executes with retry caps, escalates, and refuses to close until verified.
Skill Test Runner (Trigger and A/B)
Test a skill in fresh sessions: ready-to-run prompts, commands, and rubric for trigger recall, false triggers, and blind A/B.