Series
Make your agents finish the job
Find missing context, fix unreliable tool calls, and keep completed work from being repeated.
21 articles
Reading list
In this series
- 01
· Engineering · 4 min
Why does the right document disappear when an agent adds a filter?
Trace empty retrieval through identity, metadata types, query construction, and ranking before changing the model.
- 02
· Engineering · 4 min
Your agent listed the first page. Did it finish the inventory?
Distinguish a sample, a complete inventory, and a time-bounded snapshot when tools return paginated data.
- 03
· Engineering · 4 min
When a tool response is too large, keep the fields the task needs
Reduce oversized tool results without cutting off identifiers, continuation state, or evidence needed for the next action.
- 04
· Engineering · 4 min
Why does an agent choose the wrong tool when both names sound right?
Diagnose overlapping tool descriptions with paired tasks, explicit side effects, and a smaller relevant tool set.
- 05
· Engineering · 4 min
The tool exists, but your agent cannot discover it
Separate tool catalog pagination, client capabilities, identity, and stale discovery state when an operation disappears.
- 06
· Engineering · 4 min
What happens when a tool schema changes halfway through an agent task?
Plan a tool contract migration that preserves old intent, validates new arguments, and keeps pending writes reviewable.
- 07
· Engineering · 4 min
A tool timed out. Did the change still happen?
Recover an ambiguous write by checking the target operation before retrying, compensating, or declaring failure.
- 08
· Engineering · 4 min
Why one failed agent call becomes many provider requests
Find overlapping retry loops across the agent, SDK, connector, and job worker, then assign a single retry owner.
- 09
· Engineering · 4 min
Your agent is under its limit. Why is the connector still throttled?
Account for shared provider quotas, interactive priorities, batch work, and retry-after before increasing agent concurrency.
- 10
· Engineering · 4 min
An expired sync token should trigger recovery, not an empty knowledge base
Rebuild a connector baseline after an invalid delta token while preserving scope, deletions, and honest freshness status.
- 11
· Engineering · 4 min
Why does an agent still quote a document after it was deleted?
Trace deletion across source IDs, chunks, embeddings, caches, and saved answers so removed content stops resurfacing.
- 12
· Engineering · 4 min
Your agent joined two correct facts from different moments
Avoid misleading cross-system answers by recording source times, effective periods, and the decision deadline.
- 13
· Engineering · 4 min
Two agents finished their parts. Why did one result disappear?
Separate parallel computation from shared writes, and choose merge rules that preserve every required result.
- 14
· Engineering · 4 min
When should the parent agent stop waiting for a missing child?
Define required results, deadlines, late arrivals, and partial completion for parallel agent workflows.
- 15
· Engineering · 4 min
An agent framework upgrade needs more than a passing import
Test tool arguments, injected state, message pairing, streaming, and stored-task recovery when changing framework versions.
- 16
· Engineering · 4 min
How to replace a connector without changing what the agent means
Compare identifiers, permissions, response completeness, writes, and recovery before moving an existing agent to a new connector.
- 17
· Engineering · 4 min
How to debug an agent without copying every secret into its traces
Capture enough identity, timing, schema, and result evidence to reproduce failures while limiting sensitive payload retention.
- 18
· Engineering · 4 min
A background job needs a result contract the agent can finish
Define submission, polling, terminal failure, result retrieval, and cleanup so an asynchronous task produces usable work.
- 19
· Engineering · 4 min
The write succeeded. Why does the agent still see the old value?
Choose the right read-back path and deadline when search indexes, replicas, or projections lag behind a successful update.
- 20
· Engineering · 4 min
Stopping an agent does not automatically undo its last tool call
Separate stopping new work, canceling external operations, reconciling accepted writes, and compensating completed effects.
- 21
· Engineering · 4 min
When a source is unavailable, should the agent use a fallback?
Choose fallback behavior by evidence, identity, freshness, and action consequence so an outage does not turn into a plausible wrong answer.