From 5b59f85828624886a2c167ece8418b5bd32b8cdd Mon Sep 17 00:00:00 2001 From: a2a-cloud Date: Mon, 13 Jul 2026 12:20:45 +0000 Subject: [PATCH] a2a-source-edit: write README.md --- README.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..615674f --- /dev/null +++ b/README.md @@ -0,0 +1,38 @@ +# customer-integration-engineer + +A deterministic, no-LLM a2a-pack agent that guides and validates a customer integration from requirements through a tested handoff while keeping credentials and production changes under customer control. + +## Public skills + +The Agent Card exposes exactly five typed tools: + +1. `design_integration` — captures systems, auth methods, data contracts, rate limits, environments, compliance constraints, and success criteria; writes `architecture.md` and `mapping.json`. +2. `generate_connector` — creates a minimal Python or TypeScript connector only under `outputs/integrations/{integration_id}/`. +3. `validate_contract` — validates JSON Schema, OpenAPI 3, and webhook contracts with deterministic fixtures; writes `contract-report.json`. +4. `run_acceptance` — performs dry-run/default-safe acceptance checks, with optional allowlisted network checks; writes `acceptance-report.json`. +5. `prepare_handoff` — produces rollout, rollback, monitoring, and operator handoff documentation; writes `handoff.md`. + +## Safety model + +- Default `dry_run=true`. +- No LLM credentials are required or read. +- Raw credentials are rejected/redacted; callers configure secret references in their own setup. +- All durable writes are path-contained under `outputs/integrations/{integration_id}/`. +- The agent does not deploy, merge, mutate customer systems, execute arbitrary shell, or fetch arbitrary URLs. +- External requests require explicit allowlist, HTTPS, DNS/IP SSRF checks, redirect blocking/revalidation, bounded payloads, timeouts, retries, and idempotency keys. +- Delivery plans require `I_APPROVE_THE_LISTED_STEPS` and a matching plan digest, but execution remains outside the agent under operator control. + +## Consumer setup + +Optional caller-managed setup fields are published for Gitea, API endpoints, object storage, observability, Kubernetes, and Argo CD. The agent only stores references, not values. + +## Synthetic webhook acceptance path + +Call `design_integration`, `generate_connector`, `validate_contract`, `run_acceptance`, and `prepare_handoff` with a webhook-style contract and `dry_run=true`. Expected workspace outputs: + +- `outputs/integrations/{integration_id}/architecture.md` +- `outputs/integrations/{integration_id}/mapping.json` +- `outputs/integrations/{integration_id}/connector/...` +- `outputs/integrations/{integration_id}/contract-report.json` +- `outputs/integrations/{integration_id}/acceptance-report.json` +- `outputs/integrations/{integration_id}/handoff.md`