Clarify payload.json structure in large payload instructions#883
Conversation
- Updated agentInstructions to explicitly state that payload.json contains the complete original response data in valid JSON format - Clarified that payloadSchema shows structure/types but NOT actual values - Added explicit guidance on how to read and parse the JSON file - Updated AGENTS.md with new section explaining payload.json file structure - Updated .github/agentics/large-payload-tester.md with detailed response format explanation - Updated internal/middleware/README.md with code examples for reading payload files Co-authored-by: lpcox <15877973+lpcox@users.noreply.github.com>
Claude
AI
changed the title
There was a problem hiding this comment.
Pull request overview
This PR enhances documentation for large payload handling by clarifying the structure and usage of payload.json files. Previously, agents were discovering the file structure through trial and error; now they have explicit instructions across four documentation locations.
Changes:
- Updated
PayloadTruncatedInstructionsconstant to explicitly explain thatpayload.jsoncontains complete original data in valid JSON format, whilepayloadSchemashows only types - Added "Understanding the payload.json File" sections to AGENTS.md and large-payload-tester.md with concrete parsing examples
- Enhanced internal middleware README with code examples showing how to read payload files in bash/jq, Node.js, and Python
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| internal/middleware/jqschema.go | Updated PayloadTruncatedInstructions constant to provide clearer guidance about payload.json structure and usage |
| internal/middleware/README.md | Added "Understanding the response" and "Reading the payload.json file" sections with multi-language code examples |
| AGENTS.md | Added "Understanding the payload.json File" section explaining the distinction between payloadSchema (types) and payload.json (values) |
| .github/agentics/large-payload-tester.md | Added "Understanding the Response Format" section documenting each metadata field |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ```bash | ||
| # Using cat and jq | ||
| cat /tmp/gh-awmg/tools-calls/a1b2c3d4e5f6.../payload.json | jq . | ||
|
|
||
| # Using Node.js | ||
| const data = JSON.parse(fs.readFileSync(payloadPath, 'utf8')); | ||
|
|
||
| # Using Python | ||
| import json | ||
| with open(payload_path) as f: | ||
| data = json.load(f) | ||
| ``` |
There was a problem hiding this comment.
The code block mixes three different languages (bash, Node.js, and Python) within a single bash fence. This creates syntax issues since the Node.js and Python code aren't valid bash. Consider either:
- Using separate code blocks with appropriate language identifiers (
javascript,python), or - Using a generic code fence (```) without a language specifier
Additionally, there's a variable naming inconsistency: line 84 uses payloadPath (camelCase, JavaScript convention) while line 88 uses payload_path (snake_case, Python convention). This inconsistency is actually correct for each language's conventions, but the first issue with the bash fence makes the code block misleading.
2 participants
Agents were discovering the payload.json file structure through trial and error rather than immediately understanding what the file contains and how to use it.
Changes
Updated
PayloadTruncatedInstructionsconstant (internal/middleware/jqschema.go:22)payloadSchemashows structure/types only, not actual valuespayloadPathfor full dataEnhanced AGENTS.md (lines 393-399)
cat payload.json | jq .,JSON.parse(fs.readFileSync(path))Updated large-payload-tester.md (lines 14-23)
Enhanced middleware README.md (lines 71-90)
Example
The response now includes clear instructions:
{ "agentInstructions": "The payload was too large for an MCP response. The complete original response data is saved as a JSON file at payloadPath. The file contains valid JSON that can be parsed directly. The payloadSchema shows the structure and types of fields in the full response, but not the actual values. To access the full data with all values, read and parse the JSON file at payloadPath.", "payloadPath": "/tmp/jq-payloads/session-123/query-456/payload.json", "payloadSchema": {"items": [{"id": "number", "name": "string"}]}, ... }Agents can immediately parse the file:
Warning
Firewall rules blocked me from connecting to one or more addresses (expand for details)
I tried to connect to the following addresses, but was blocked by firewall rules:
example.com/tmp/go-build291532669/b275/launcher.test /tmp/go-build291532669/b275/launcher.test -test.testlogfile=/tmp/go-build291532669/b275/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true go1.25.6 -c=4 -nolocalimports -importcfg /tmp/go-build291532669/b256/importcfg -pack /opt/hostedtoolcache/go/1.25.6/x64/src/encoding/csv/reader.go rev-�� go ude-agent-sdk/ve--64 /home/REDACTED/.ca-o(dns block)invalid-host-that-does-not-exist-12345.com/tmp/go-build291532669/b260/config.test /tmp/go-build291532669/b260/config.test -test.testlogfile=/tmp/go-build291532669/b260/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true go1.25.6 -c=4 -nolocalimports -importcfg /tmp/go-build291532669/b186/importcfg -pack /opt/hostedtoolcache/go/1.25.6/x64/src/mime/multipart/formdata.go rev-�� go HEAD x_amd64/vet(dns block)nonexistent.local/tmp/go-build291532669/b275/launcher.test /tmp/go-build291532669/b275/launcher.test -test.testlogfile=/tmp/go-build291532669/b275/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true go1.25.6 -c=4 -nolocalimports -importcfg /tmp/go-build291532669/b256/importcfg -pack /opt/hostedtoolcache/go/1.25.6/x64/src/encoding/csv/reader.go rev-�� go ude-agent-sdk/ve--64 /home/REDACTED/.ca-o(dns block)slow.example.com/tmp/go-build291532669/b275/launcher.test /tmp/go-build291532669/b275/launcher.test -test.testlogfile=/tmp/go-build291532669/b275/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true go1.25.6 -c=4 -nolocalimports -importcfg /tmp/go-build291532669/b256/importcfg -pack /opt/hostedtoolcache/go/1.25.6/x64/src/encoding/csv/reader.go rev-�� go ude-agent-sdk/ve--64 /home/REDACTED/.ca-o(dns block)this-host-does-not-exist-12345.com/tmp/go-build291532669/b284/mcp.test /tmp/go-build291532669/b284/mcp.test -test.testlogfile=/tmp/go-build291532669/b284/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true go1.25.6 -c=4 -nolocalimports -importcfg /tmp/go-build291532669/b191/importcfg -pack /opt/hostedtoolcache/go/1.25.6/x64/src/net/http/internal/httpcommon/httpcommon.go rev-�� _.a HEAD .12/x64/bin/as(dns block)If you need me to access, download, or install something from one of these locations, you can either: