API automation with coding agents sounds exciting, but real QA work is rarely just “edit one test file.”

Most agent demos show a coding assistant editing a small repo. QA/API automation work is usually messier.

A real API test change may require the agent to understand:

• the endpoint and OpenAPI contract,
• the existing API test framework,
• shared request/assertion utilities,
• service behavior,
• test data or fixtures,
• and whether a failing expectation is actually a product gap.

This repo explores a practical pattern for that problem:

small task context + generated repo context + reusable QA playbooks + verification

The current implementation uses local agents on an 8 GB MacBook Air, but the framework is not local-agent specific. The same structure can be used with cloud coding agents because the core idea is context routing, not model hosting.

Repo:

https://github.com/balajiregt/agentic-workspace

The QA Problem
API automation agents often fail in predictable ways:

• create a new test file when the endpoint already has coverage,
• invent endpoint paths, base URLs, or request bodies,
• ignore shared API-test utilities,
• update tests without checking OpenAPI,
• delete or rewrite a failing test just to make the suite green.

From a QA point of view, the last one is especially dangerous. If a test expects behavior that the service does not implement and OpenAPI does not document, the agent should call it out as a product/contract gap. It should not hide the gap.

Workspace Shape
The sample validation slice uses Spring Boot and RestAssured, but the pattern is API-framework neutral.

agentic-workspace/
AGENTS.md # repo-level agent rules
contexts/current/ # current ticket context
skills/ # compact QA/API agent playbooks
scripts/ # context resolver and token reports
local-agents/ # optional local Pi + llama.cpp runtime
projects/
microservices/
xyz-service/ # dummy Spring Boot API
xyz-deployments/ # deployment companion files
qa-steps/ # shared API-test utilities
qa-projects/xyz-service-api-tests/ # service API tests

The dummy service is intentionally small. The value is that it crosses the same boundaries real QA automation changes cross: service behavior, contract, shared test utilities, service-specific API tests, and verification.

Agent Flow

The agent starts from a small ticket context, then expands into exact files only when needed.

The Context Split
Earlier, I tried putting too much into the YAML: exact paths, target files, commands, examples, and behavior hints. That made the framework harder to maintain.

The cleaner split is:

service-context.yml -> small ticket facts
OpenAPI + repo layout -> stable service facts
resolved-context.yml -> generated exact paths and commands
SKILL.md -> reusable QA/API playbook rules

The current task context stays small:

service_name: "xyz-service"
work_item:
source: "jira"
key: "ABC-123"
summary: "Add API coverage for the medium customer risk category response"
change_type: "test"
affected_endpoints:
- "GET /xyz"
affected_fields:
- "riskCategory"
repository_topology:
service_and_tests: "split-qa"
deployment: "separate-repo"

Then the resolver generates paths such as:

resolved_files.openapi
resolved_files.service
resolved_files.api_test
resolved_files.shared_fixtures
resolved_files.shared_assertions
verification.commands

This helps when the user gives a short prompt like:

For the existing API test, add one assertion that riskCategory is not empty.

Even if the user forgets to say “read the YAML,” AGENTS.md routes the agent back to the current context.

*Same Repo or Split QA
*

For many teams, same-repo is simpler and more common: endpoint code, OpenAPI, and API tests live together. Split QA or separate deployment repos are useful when the organization already owns them separately.

The framework should not force one layout. It should make the layout explicit so the agent knows where to edit and where not to invent.

QA Guardrail: Protect Test Intent

One important rule:

If a test expects behavior that is not implemented or documented, stop and report a QA/product gap.

Example:

GET /xyz?customerId=INVALID_ID_FORMAT should return 400

If OpenAPI only says customerId is a nonblank string, and service code only trims/uppercases the value, then INVALID_ID_FORMAT is not invalid yet.

The right QA answer is:

This is a product/contract gap. Add service validation and update OpenAPI, or mark the test pending with a reason.

That is different from simply making tests pass. The agent should preserve QA signal.

Local Agent Validation
The local runtime is included to prove this can work on a modest machine:

npm run setup:8gb
npm run agent:8gb

Validated local model:

unsloth/gemma-4-E2B-it-qat-GGUF:UD-Q4_K_XL
contextWindow: 4096
maxTokens: 1536

Before trusting edits, run:

npm run agent:doctor

Expected:

TOOL_CALL_CHECK=PASS

This matters because some GGUF models print tool-shaped JSON as text instead of returning structured tool calls. Those models may be useful for analysis, but not for reliable file edits.

Token Efficiency Proof
Current focused API-test-change report:

Central context tokens: 174
Central context plus playbook tokens: 2386
Full microservices corpus tokens: 5309
Task profile tokens: 4810
Central context compression ratio: 30.51x

I treat these as approximate local measurements, not formal benchmark numbers. The token estimator is a simple yardstick for comparing one workspace version against another. It is useful for direction: the maintained ticket context is small, and the agent expands into task files only when needed. The exact number will vary by tokenizer, model, repo size, file format, and how the agent runtime packs tool/context messages.

Tokens should be as low as possible while still preserving useful signal. The goal is not tiny context at any cost. The goal is:

low noise, high signal, staged file reads

For larger changes, the workflow should be split:

`1. service behavior + OpenAPI

1. API tests + shared utilities
2. deployment impact + verification`

That approach works for local agents with small context windows and also helps cloud agents stay precise.

How QA Teams Can Adopt This
Start small:

• Add AGENTS.md with the rule: always read current task context.
• Add contexts/current/service-context.yml for the active ticket.
• Generate resolved-context.yml from repo layout and OpenAPI.
• Add one compact API-test playbook. In this repo it is stored as SKILL.md.
• Add a QA gap prompt for unsupported expectations.
• Measure context tokens and verification pass rate.

Do not start by cataloging hundreds of services by hand. Let repo conventions, OpenAPI, and source files supply stable facts.

What This Proves
This is not a replacement for QA judgment, CI, code review, or product ownership.

It proves a narrower but useful point:

Agents become more useful for API automation when test intent, repo topology, contract evidence, and verification are explicit.

Local agents make the experiment cheaper and more transparent. Cloud agents can use the same workspace pattern for stronger reasoning and larger context.

The framework is really about QA discipline: route the agent, protect the test intent, verify the result, and report gaps instead of hiding them.

*Notes and Limits
*

Verification is not just about making tests green. The loop should preserve QA signal, validate contract evidence, and report product gaps when expectations are unsupported.

I am writing this from the perspective of a senior SDET who has built and maintained API/UI automation frameworks hands-on, not as someone claiming to define a standard agentic-development framework.

This workspace came from day-to-day testing work: repeated API automation changes, shared utility drift, missed OpenAPI checks, and the risk of agents making tests pass while losing the real QA signal. I also borrowed ideas from patterns that are becoming common in agent workflows, such as compact instruction files, explicit context routing, and loop-style validation.

So this is a practical reference implementation, not a universal answer. Some projects may not need this structure. Some may need a different repo topology, test framework, model, or context resolver. The important idea to adapt is the discipline: keep task context small, derive stable facts from source and contracts, make repo ownership explicit, and verify the result.

Thanks for reading. I’d love to hear your thoughts, feedback, or ideas for improving this framework further.