Generative AI Google Brain

agents-adk-contract-compliance-pipeline-tutorial

3 min read

Repository doc · agents/adk/contract-compliance-pipeline/TUTORIAL.md · Open on GitHub · Part of Agents & ADK Notebooks

Tutorial: Run the Contract Compliance Multi-Agent Demo

This tutorial walks through the executable demo in this repository. A Python FastAPI service handles contract intake, deterministic extraction, ADK RemoteA2aAgent handoff, case state, and artifacts. A Go A2A service enforces deterministic compliance rules and returns a JSON-RPC message/send task verdict.

The live cockpit path does not require a Gemini API key.

1. Start the Services

Start the Go compliance agent:

cd go-compliance-agent
go run cmd/server/main.go

The Go service exposes:

http://localhost:8888/.well-known/agent.json
http://localhost:8888/

Start the Python cockpit:

cd python-extraction-agent
uv sync
uv run uvicorn app.fast_api_app:app --host 127.0.0.1 --port 8000

Open:

http://127.0.0.1:8000/live-compliance/

2. Run the Happy Path

  1. Select standard-vendor-agreement.pdf.
  2. Keep A2A Simulator Mode on Healthy.
  3. Click Run Pipeline Audit.
  4. Confirm the Agent Exchange panel shows:
    • source: python-extraction-agent
    • target: Security Compliance Validator
    • method: message/send
    • a task ID
    • a JSON-RPC payload
    • a passed Go verdict
  5. Open the generated compliance certificate artifact.

Expected result: the contract passes because value, term, insurance, liability, renewal, and exit terms are within policy.

3. Run the Review Paths

Test the bundled failure cases:

ContractExpected Result
high-risk-liability-contract.pdfReview because unlimited liability is prohibited.
non-compliant-contract.pdfReview with multiple policy violations.

For non-compliant-contract.pdf, the UI should show review required with these violation categories:

  • value above $500k
  • unlimited liability
  • auto-renewal longer than 3 years
  • insurance below $1M
  • term longer than 5 years
  • missing usable exit clause

4. Simulate A2A Failure

Use A2A Simulator Mode to test remote-agent failure behavior:

  • Healthy: normal Go service path.
  • Delayed: waits before the Go call, bounded by the backend.
  • Crashed (503): simulates Go service failure and routes to manual review.

Expected crashed result: Python fails closed to MANUAL_REVIEW and the certificate explains that manual legal review is required.

5. What the Browser Sends

The UI posts contract text and policy settings to:

POST /api/compliance/upload

Important form fields:

FieldPurpose
fileText contract fixture, including .pdf-named text samples.
custom_policiesActive policy values sent to Go.
simulated_latencyBounded delay for simulator testing.
simulated_server_statenormal or crashed.

The browser does not call the Go service directly.

6. What Python Sends to Go

python-extraction-agent/app/fast_api_app.py builds the A2A request in build_go_message_payload(...).

The live method is:

message/send

The payload contains:

  • jsonrpc: "2.0"
  • task_id
  • extracted contract fields
  • active policy settings

ADK sends the request through RemoteA2aAgent; it is not a manual browser-to-Go call.

7. What Go Validates

go-compliance-agent/internal/compliance/checker.go checks:

  • contract value ⇐ max_contract_value
  • insurance coverage >= required_insurance_minimum
  • term length ⇐ max_term_years
  • termination clause present when required
  • no prohibited unlimited liability clause
  • no prohibited auto-renewal longer than 3 years

Default thresholds live in:

go-compliance-agent/internal/policies/default_policy.json

8. Key Code To Read

FileWhy it matters
python-extraction-agent/app/fast_api_app.pyAPI routes, request validation, ADK handoff, simulator handling.
python-extraction-agent/app/tools.pyDeterministic contract extraction and risk classification.
python-extraction-agent/app/live_compliance.pyCase state and generated HTML artifacts.
python-extraction-agent/app/static/live-compliance/index.htmlLive cockpit UI and A2A payload display.
go-compliance-agent/internal/agentcard/card.goAgent Card discovery response.
go-compliance-agent/internal/handler/task_handler.goJSON-RPC message/send and legacy task handlers.
go-compliance-agent/internal/compliance/checker.goDeterministic policy verdict.

9. Test the Demo

Run Python tests:

cd python-extraction-agent
uv run pytest tests/unit -v

Run Go tests:

cd go-compliance-agent
go test -v ./...

Smoke-test the Agent Card:

curl http://127.0.0.1:8888/.well-known/agent.json

From the repository root, smoke-test a non-compliant upload:

curl -sS -X POST http://127.0.0.1:8000/api/compliance/upload \
  -F file=@sample-contracts/non-compliant-contract.pdf \
  -F simulated_latency=0 \
  -F simulated_server_state=normal \
  -F 'custom_policies={"max_contract_value":500000,"required_insurance_minimum":1000000,"max_term_years":5,"required_termination_clause":true,"prohibited_clauses":["unlimited liability","auto-renewal > 3yr"]}'

Expected result: response JSON contains passed: false and a list of Go policy violations.

Repository Docs · Home

Graph View

Backlinks