For Agents: Collaboration Handbook

9/15/2025

Intent: This handbook is a contract for how other agents (and developers) collaborate with my site agent. It aligns with the Agent2Agent (A2A) protocol so your agent can interoperate cleanly now and in future upgrades.

TL;DR: Treat my agent as an A2A Server you call via JSON‑RPC 2.0 over HTTPS; send a Message (with parts); get back a Message or a stateful Task you can stream/poll; respect safety rules and escalation paths.

1) Capabilities & Scope (current → planned)

Current (v0.1):

Conversational Q&A about Graham, his writings, hobbies, and professional background; cites sources on request.
Grounding via chunk‑level retrieval over key pages (site posts and this repo content). No persistent memory; per‑request retrieval only.
No external tools or data writes; text I/O only. Preferred input ≤ ~2,000 chars; output text/plain or Markdown with bracketed citations [n].

Primary corpora the agent will cite:

Projects & Case Studies (structured outcomes).
Values, Constraints & Red Lines (safety policy; ethics).
Scheduling & Contact (handoff channels).
Resume (roles, stack, chronology).

Planned (v0.2+):

Public A2A endpoint (JSON‑RPC 2.0 over HTTPS) with optional SSE streaming; discovery via Agent Card at /.well-known/agent-card.json.
Optional authenticated extended Agent Card for partners; OAuth2 Bearer tokens at HTTP layer.

2) Protocol: how to talk to my agent (A2A‑aligned)

Transport & format

HTTPS only. Payloads are JSON‑RPC 2.0; streaming via SSE when enabled.
Authentication (when required) lives in HTTP headers (e.g., Authorization: Bearer …); identity is not in JSON‑RPC payloads.

Core data model (must understand)

Message: one turn with role ("user" or "agent"), messageId, and parts (see below).
Part (union): TextPart (kind: "text"), FilePart (bytes or URI), DataPart (structured JSON). Optional metadata per part.
Task: stateful unit of work with taskId, status.state (working, input-required, auth-required, completed, failed, canceled, rejected), history, and artifacts. Tasks are immutable once terminal.
Artifact: tangible outputs (documents/images/JSON), composed of parts. May stream incrementally.

Methods you can call

message/send → returns a Message or starts a Task.
message/stream → subscribe via SSE for live TaskStatusUpdateEvent / TaskArtifactUpdateEvent.
tasks/get, tasks/cancel, tasks/resubscribe → manage long‑running tasks.
agent/getAuthenticatedExtendedCard → fetch extended Agent Card after authenticating.

Discovery (when A2A is enabled)

Fetch the public Agent Card (JSON) at https://<domain>/.well-known/agent-card.json. For sensitive details, request the authenticated extended card.

3) Safety, privacy, and escalation (non‑negotiable)

Follow my Red Lines: no harmful use‑cases, no grifting/exploitation, and no unnecessary PII. If a request violates these, refuse and escalate.
PII & SSRF hygiene: Treat all inputs as untrusted; never request arbitrary webhook URLs; if push notifications are used, authenticate to client webhooks and verify incoming notifications (JWT/JWKS, HMAC, or mTLS).
Transport security: HTTPS, modern TLS; authenticate via headers; authorize by scope/skill. Log taskId/contextId and trace context for auditing.
Human handoff: For scheduling, approvals, or sensitive matters, direct to graham@grahampaasch.com and phone/SMS for urgent.

4) Inputs & outputs (contract)

Preferred input: TextPart ≤ ~2,000 chars; include target skill and key terms for retrieval. If you require JSON output, add a DataPart with the desired schema in metadata.
Preferred output: text/markdown or text/plain with bracketed citations [n] mapped to a Sources block.
Schema hints: A2A v0.x does not standardize schema negotiation; use Part.metadata to communicate a JSON Schema or media type; the server SHOULD honor when feasible.
No memory: Each request must include all necessary context (or a contextId you got earlier).

5) Worked examples (A2A‑style)

5.1 Basic Q&A (polling)

Request (message/send):

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "messageId": "msg-001",
      "parts": [{ "kind": "text", "text": "Summarize Graham's career vision with citations." }]
    },
    "configuration": {"acceptedOutputModes": ["text/markdown"], "historyLength": 0}
  }
}

Response: Server may return a short‑lived Task you can poll via tasks/get until status.state = completed.

5.2 Streaming long output (SSE)

Request (message/stream) to receive TaskStatusUpdateEvent and TaskArtifactUpdateEvent until final: true; reconnect with tasks/resubscribe if disconnected.

5.3 Structured JSON output

Include a metadata schema hint on your text part:

{
  "jsonrpc": "2.0",
  "id": "req-009",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "messageId": "msg-009",
      "parts": [{ 
        "kind": "text",
        "text": "Return a JSON array of 3 recent, measurable projects.",
        "metadata": {
          "mimeType": "application/json",
          "schema": {"type": "array", "items": {"type":"object","properties":{"title":{"type":"string"},"year":{"type":"integer"},"result":{"type":"string"}}}}
        }
      }]
    },
    "configuration": {"acceptedOutputModes": ["application/json"]}
  }
}

The server can respond with an Artifact containing a DataPart matching your schema.

6) Skills exposed by my agent (initial set)

Skill IDs are stable names your client can reference in the Agent Card once published.

summarize.career_vision — Summarize and cite the career vision page. Sources: site writings.
facts.resume_extract — Extract verified facts from the resume (roles/dates/stack).
projects.list — Return concise case studies with metrics.
policy.values_check — Check a draft request against Values & Red Lines; suggest safe phrasing or refusal rationale.
handoff.schedule_contact — Provide escalation channels and meeting rules.

Each skill declares inputModes = ["text/plain"] and outputModes = ["text/markdown","application/json"] initially. The Agent Card will enumerate examples and limits.

7) Error handling & states (what to expect)

JSON‑RPC errors: Standard codes (-32700, -32600, -32601, -32602, -32603).
A2A‑specific server errors (subset): TaskNotFound (-32001), UnsupportedOperation (-32004), ContentTypeNotSupported (-32005).
Task states you must handle: working, input-required, auth-required, terminal states (completed, failed, canceled, rejected). Terminal tasks are immutable; start a new task for refinements within the same contextId.

8) Security & enterprise features (do this, no excuses)

TLS 1.2+, cert validation, strict HTTPS. No HTTP.
Auth in headers, not payload; scopes may gate skills.
Tracing: Propagate W3C trace context; log taskId, contextId. Use OpenTelemetry where available.
Push notifications (if enabled): allowlist destinations; sign with JWT/HMAC; publish JWKS for key rotation; verify tokens on receipt.

9) Escalation & contact

If a request requires human approval or scheduling—or hits safety policy—return a refusal/explanation and give my direct contact:

Primary: mailto:graham@grahampaasch.com
Urgent: SMS/phone +1‑608‑620‑4651 (CT business hours)
LinkedIn (recruiters): https://www.linkedin.com/in/grahampaasch
All paths and hours are defined in my scheduling policy.

10) Versioning & discovery timeline

Spec target: A2A v0.3.0 features (JSON‑RPC core, SSE streaming, Authenticated Extended Card). Production rollout will publish an Agent Card at a well‑known URI.
This page: v0.2 (A2A‑aligned design), updated 2025-09-15.

Appendix A — Minimal Agent Card (preview, non‑authoritative)

{
  "version": "0.3.0",
  "id": "agent:graham-site",
  "name": "GrahamPaasch.com Site Agent",
  "description": "Answers about Graham, projects, and policies; enforces red lines; escalates to human when needed.",
  "url": "https://<domain>/a2a", 
  "capabilities": { "streaming": false, "pushNotifications": false, "supportsAuthenticatedExtendedCard": true },
  "securitySchemes": [{ "type": "oauth2", "scheme": "bearer" }],
  "skills": [
    {"id":"summarize.career_vision","name":"Summarize career vision","inputModes":["text/plain"],"outputModes":["text/markdown","application/json"]},
    {"id":"facts.resume_extract","name":"Extract resume facts","inputModes":["text/plain"],"outputModes":["application/json"]},
    {"id":"projects.list","name":"List case studies","inputModes":["text/plain"],"outputModes":["text/markdown","application/json"]},
    {"id":"policy.values_check","name":"Policy check","inputModes":["text/plain"],"outputModes":["text/markdown"]},
    {"id":"handoff.schedule_contact","name":"Handoff to human","inputModes":["text/plain"],"outputModes":["text/markdown"]}
  ]
}

Exact fields will follow the published Agent Card schema in the A2A spec; discovery path will be /.well-known/agent-card.json.

Appendix B — Example output style

My career vision emphasizes meaningful impact, continuous growth, and healthy culture. [1]

Sources:
[1] Career Vision page (/writings/...)

Style mirrors the current agent output contract.

Change Log

2025‑09‑15: Converted to A2A‑aligned handbook; added methods, states, security, examples (this revision).
2025‑09‑14: Initial draft.

Version

v0.2