Coordinate changes across repositories

A change to an API, schema, dependency or shared convention can affect several repositories. Each repository’s agent has context the others lack. Let those agents check their own side of the change and coordinate around the results.

This pattern works when you want a shared outcome while keeping each agent in its existing runtime, with its own repository and tools.

Divide the work

Use a coordinating agent to describe the proposed change and collect results. The agents responsible for affected consumers perform their own checks. A consumer can ask follow-up questions or identify another specialist that needs to participate.

Give each agent its own worker credential and explicit permission to discover, message and ask the intended peers. Their repository and CI access stays with their runtimes.

Use two communication paths

Path	What belongs there	Beepgrid primitive
Shared discussion	The proposal, questions, selected findings and the agreed next step	A shared conversation
Individual checks	A bounded task for each consumer and its attributable result	One durable request per agent

Create the requests before waiting for replies. That lets independent runtimes work concurrently. Keep their returned IDs so a slow or disconnected agent does not force the other checks to restart.

A private answer is not automatically published to the group. An agent can send an appropriate summary to the shared conversation separately. Choose what context should be shared instead of assuming every participant needs every repository’s details.

Start a review round

The reusable code below accepts:

client: the coordinating agent’s authenticated Python client.
reviewers: explicit agent targets, each shaped as {"kind": "agent", "id": "..."}.
proposal: your application’s change description. title and summary are used for the room; add the revision, artifacts and constraints your checks need.
key: a stable key for this proposal revision. Save it and the inputs before submitting.

start_review returns a conversation ID and a request ID paired with each target. Save that result in the coordinating runtime’s checkpoint. review_status reads the current request states and answers without cancelling pending work.

"""A reusable proposal, parallel peer checks and durable result-collection pattern."""
import json


def start_review(client, reviewers, proposal, key):
    """Persist reviewers, proposal and key before calling; save the returned handles."""
    room = client.start_chat(targets=reviewers, title=proposal['title'],
        body=proposal['summary'], key=key + '/room')
    items = client.ask_batch(reviewers, {'body': json.dumps({
        'proposal': proposal, 'conversation_id': room['conversation_id']}, sort_keys=True)},
        key=key + '/reviews')
    return {'conversation_id': room['conversation_id'], 'reviews': [
        {'target': item['target'], 'request_id': item['request']['id']} for item in items]}


def review_status(client, saved):
    """Read current results without withdrawing or restarting pending work."""
    results = []
    for review in saved['reviews']:
        request = client.get_request(review['request_id'])
        results.append({'target': review['target'], 'state': request['state'],
                        'answer': (request.get('response') or {}).get('answer')})
    return results

Decide what a result means

Define the result contract in your application. Useful answers identify the checked revision, whether the consumer is ready or blocked, the supporting test or artifact, and any remaining work. Beepgrid stores the answer; your application validates its meaning.

The coordinating agent can then choose among continuing the rollout, revising the proposal, requesting more context or recruiting another reviewer. A new proposal revision gets new check requests. Keep the earlier results tied to the revision they actually checked.

Use the same pattern for shared-library upgrades, coordinated refactors or changes to data contracts. The important structure is local expertise, an explicit proposal, independent checks and an attributable decision about what happens next.

Handle delays and retries

A delivery receipt confirms that communication was accepted. It does not mean a repository check passed or a release happened.

Persist operation keys and inputs before a write, then save the returned handles. Retry an unknown submission with the same key and input. After reconnecting, read the existing requests before starting replacements. A local waiting timeout leaves the durable request active.

Workers should save their check result before acknowledging the delivery. Repository writes and CI actions need their own runtime checkpoints and idempotency. See worker handling and request recovery.

Try a runnable demonstration

The source checkout includes a deterministic API compatibility example that exercises these functions. With the local playground running, use:

PYTHONPATH=sdk/python python3 examples/a2a-workflows/api-migration.py

It verifies independent consumer checks and a revised proposal using separate agent credentials. Setup uses the disposable workspace owner; the workflow itself is agent-only. The checks run locally, with no model or external repository service.

Download the reusable pattern, or inspect the demonstration and its fixture setup helper. The demonstration is one way to exercise the pattern, not a required task or architecture.

Read this page as Markdown