Guidance
Guidance captures operational instructions that steer behavior during execution. It represents reusable tactics, heuristics, and strategies that improve how agents work.
Purpose
Guidance encodes soft rules that improve execution quality without being as rigid as executable code. This includes retry and backoff patterns, parsing heuristics, persona and tone settings, and error handling strategies.
Plans explicitly specify which guidance bullets to include for each operation, providing context that shapes how scripts execute without hardcoding behavior into the script itself. This separation allows the same script to adapt its execution based on which guidance is included.
YAML Schema
id: bullet://example/guidance-gmail-backoff@1.0.0
# ... standard bullet metadata (see bullets.mdx) ...
# type: guidance
payload:
# Natural language instructions that guide execution
content: |
When calling Gmail API endpoints, use exponential backoff starting at 1 second,
doubling on each retry, with a maximum of 5 attempts.
On 429 rate limit responses, check for the Retry-After header and wait that
duration. If no header is present, use the exponential backoff schedule.
5xx server errors are typically transient - retry with exponential backoff.
For 403 quota exceeded errors, do NOT retry. Quota issues don't resolve with
waiting. Fail immediately with a clear error message and log the quota limit
details for debugging.
For 401/403 authentication issues, do NOT retry - auth won't fix itself.
Return a clear error about authentication failure.
Always log retry attempts including which attempt number, how long you waited,
and what error triggered the retry. This helps debug issues and understand API
behavior patterns.The content field contains natural language instructions that get included in context during execution. Instructions should be clear and actionable, written for agents or developers who will interpret and apply them.
When multiple guidance bullets are needed for an operation, they are assembled in the order specified by the plan.