Why Is My AI Agent Not Following Instructions? A Context Debugging Guide

When an AI agent is not following instructions, start with one failed run. Write down the instruction it should have followed, what it did instead, and which system can confirm the result. That gives you a concrete failure to trace. A polished final answer can still hide a missed tool call, while a bad answer can start with a rule the agent never received.

The fastest useful question is: where did the expected behavior first break? The rule may have been absent, stale, in conflict, unclear, or blocked at the action boundary. Each cause needs a different fix.

TL;DR

Check the exact rule and version, then its route to the affected agent. Inspect what the distribution system compiled and issued for that run, and look for separate evidence of session injection when available. Next, compare the rule with higher-authority instructions and the task facts. Finally, check tool and target-system records to see what actually happened. Test a fix in a fresh session before widening it to other agents.

Why is an AI agent not following instructions?

The symptom alone does not tell you the cause. These cases look similar in a chat transcript but lead to different repairs:

What happened	What to check first	Likely repair
The agent never received the rule	Resource state, route, and bundle version	Publish or route the right version
The run used an old rule	Session start, cached or copied context, version	Load fresh context or start a new session
Two rules disagree	Authority, scope, and effective versions	Resolve the conflict in the governed source
The rule arrived but did not cover the case	Wording, examples, task facts	Clarify and test the rule
The agent described the right action but did not take it	Tool response, approval, and target record	Fix the execution path and verify the result

Start with the earliest failed step. Editing prose will not fix a missing route. Changing a route will not make a blocked tool action succeed.

Reconstruct the affected run

Record the agent identity, session or run ID, time, integration, user request, and expected outcome. Save the exact rule you expected the agent to use, including its version and authority. Check whether it was maintained Knowledge, a Skill, working Memory, a one-time request, or runtime data from a tool. Those forms do not carry the same authority or lifecycle.

For example, suppose a support agent should escalate an invoice dispute above an approved threshold, but it drafts a routine reply. Ask which threshold version was current for that run, which agents were meant to receive it, and what the invoice data actually said. An earlier screenshot of the policy is not proof that this agent received that version.

The point-in-time audit guide explains which identifiers and version records make this reconstruction possible. Keep the evidence tied to this run, because a successful test today does not establish what happened yesterday.

Check routing before rewriting the rule

For maintained context, inspect the published or current version and the affected agent’s direct and Group routes. A route decides automatic delivery. Repository roles separately decide who can discover, read on demand, or change the Resource. Giving an agent repository access does not automatically put the rule into its context bundle.

In Alignbase’s current model, an Always route includes published Knowledge content or current Memory in the agent’s fresh context bundle. A routed Skill appears there by published metadata, and the agent reads its package separately. Check that package read if the missed instruction lives in a Skill. Task-based When relevant routing and Context Search are planned, so they cannot explain a missing item in today’s Always bundle.

Compare the failed run’s recorded bundle and response with the version you expected. Then load fresh context for the affected agent and a second agent that should not receive the rule. Those new loads test today’s routes; they do not establish what the earlier run received. A route that is too broad can create a different failure: an agent sees an instruction that belongs to another workflow. The context routing guide walks through that separation in more detail.

Separate delivery from behavior

If the correct version was compiled and issued, the investigation moves forward, but the evidence has a limit. Compilation says what the distribution system assembled. Response issuance says what it sent. An integration acknowledgment and confirmed injection are separate events. None of these alone proves the model consumed or obeyed the rule.

Check whether an existing session held an earlier copy, whether another current instruction disagreed, and whether a user request or tool result tried to claim authority it did not have. The guide to conflicting agent instructions covers how to compare authority, scope, and versions. Do not promote text from an attachment, Memory file, or tool result into a company rule merely because it sounds imperative.

If the rule was available and consistent, test its wording against the failed case and a nearby case where it must not apply. “Escalate large disputes” leaves the threshold and source unclear. “Escalate invoice disputes above the approved threshold in the current billing policy” points the agent to a decision, but the policy and threshold still need a current governed source. Keep tool permissions and approval checks outside the prose.

Check the action in the system that owns it

An agent may say it escalated a case when it only drafted a reply. Inspect the tool call, its authorization result, any required approval, and the case record. If the call failed or no record changed, fix that execution path. The transcript is useful evidence of what the agent said, not proof that the action completed.

If an unauthorized action succeeded, contain it at the tool or target system and review that boundary. An instruction can guide behavior, but it cannot grant itself authority or replace an execution-time check.

Test the repair on a fresh session

Change the smallest thing that addresses the first broken step. A missing route needs a route correction. A stale session needs a fresh context load or a new session. Conflicting or vague shared guidance needs a proposed Knowledge or Skill change through the applicable review and publication path. Permitted Memory updates are live and versioned; they should not become a second policy store.

Run the original failed case again with a fresh context load, then run one case that should behave differently. Compare exact versions and outcomes, including the downstream record. If the repair changes a published rule, the instruction review guide shows what to check before it guides other agents. Record what remains unknown, especially model consumption when no trusted attestation exists.

Where Alignbase fits

Alignbase manages versioned Knowledge and Skills, working Memory, independent Always routes, and audit records for context compilation and response issuance across supported integrations. Those records help a team find whether the expected context reached the distribution boundary for a run. They do not replace session-specific injection evidence, tool authorization logs, or outcome checks. Automated Context Evaluation and Context Improvement remain planned; teams can test their repairs using their own cases today.

The Alignbase blog also covers context governance, version control, and point-in-time audits for teams tracing repeated failures.