GECX companion forms¶

Status: Current | Last reviewed: 2026-10-08

Connect your GECX agent to the standalone TrueServe multimodal service to show forms alongside a conversation and read the customer's submitted answers. The Cloud Run sandbox includes an Auto Club Group driver/vehicle example. Use synthetic details; submitting the demo does not change an insurance policy.

Add the MCP tool¶

In your GECX application's agent builder, open Tools, then add an MCP tool with these settings:

GECX authenticates with its own Google service identity. The service is private, and the GECX service agent in this project already has permission to invoke it. No API key is required in the agent. If your GECX app is in another project, the operator must grant its CES service agent Cloud Run invocation permission and add that identity to the multimodal service's allowlist.

Create a string session variable named experienceSessionId. Add a custom MCP header named X-Trueserve-Session-Id and select that variable as its value. The API form of the binding is $context.variables.experienceSessionId.

For the driver/vehicle example, attach these tools to the agent:

• list_catalog
• get_session_info
• start_auto_change
• await_auto_change
• submit_spoken_auto_change if you want a spoken-intake option

For a client with a general A2UI renderer, you can also attach render_preset, create_surface, update_components, update_data_model, delete_surface, and wait_for_submission.

Leave connect_auto_experience unselected: this Cloud Run deployment does not send SMS. The operator supplies the browser link for a demo, and a customer's application supplies it in an integrated experience.

Start an experience¶

Start the authenticated browser proxy in a devcontainer terminal and leave it open:

gcloud run services proxy trueserve-multimodal-demo \
  --project=us-con-gcp-sbx-0000500-032725 \
  --region=us-central1 --port=18085

Forward devcontainer port 18085 privately in VS Code's Ports panel. This preview uses your Google login to reach Cloud Run. Directly opening the Cloud Run URL without Google authentication returns 403. Keep the forwarded port private.

In another terminal, create an experience:

python apps/multimodal-service/examples/create_gecx_session.py \
  --google-iam --app-origin=http://127.0.0.1:18085 \
  --output=/tmp/gecx-experience.json

Open that private file locally. Open app_url in a browser and set experienceSessionId in the GECX test session to the value under gecx_variables. The launcher also prints the experience ID. Keep the browser link and session token private. If your environment gives the forwarded port a different address, use that address for --app-origin instead. GECX itself calls Cloud Run directly and does not use the local proxy.

For a manual simulator test, use the simulator's session-variable input. If your simulator only exposes variable defaults, set the ID temporarily on a dedicated test agent and clear it afterwards. For application-driven sessions, populate the variable when starting the conversation. Every conversation needs its own experience; the MCP connection does not create it.

For the REST session API, send the variable with the first user input:

{
  "config": {"useToolFakes": false},
  "inputs": [
    {"variables": {"experienceSessionId": "EXPERIENCE_ID_FROM_LAUNCHER"}},
    {"text": "Please add a driver using the companion form."}
  ]
}

Send this body to POST /v1beta/projects/PROJECT/locations/us/apps/APP/sessions/SESSION:runSession on ces.googleapis.com, using your application's authorized Google API client. SESSION is the GECX conversation identifier; it is separate from the multimodal experience ID. For streaming clients, verify the same variable binding before allowing form tools to run.

Agent instructions¶

Add this guidance to your agent's instructions and adapt the conversation wording:

You can show an Auto Club Group form in the customer's companion browser.
First call get_session_info with no arguments. It resolves the trusted
experienceSessionId header binding. Use its returned session_id as the
experience_session_id argument for subsequent session-scoped tools.
If that lookup fails, ask the operator to connect the companion experience.
Never invent an experience ID or ask the customer to read one aloud.

When the customer asks to add a driver, call start_auto_change with
workflow "driver". For a vehicle, use workflow "vehicle".
Tell the customer that the form is available in their companion browser.

Use the returned surface_id with await_auto_change to check for submission.
Use a timeout of up to 20 seconds. A pending result is not a submission.
Read again when appropriate; do not claim that you monitor indefinitely.
When the tool returns completed_demo, summarize the submitted details and
explain that this is a demo receipt, not an insurance policy change.
Handle cancellation without claiming completion.

If the customer chooses spoken intake, collect the actual required details
and explicit confirmation before calling submit_spoken_auto_change.
Never infer missing details or confirmation from silence or a timeout.

The browser and GECX must use the same experience. The form's Form session connected label confirms its SSE connection; it does not confirm GECX tool authentication.

Check the complete flow¶

1. Start a fresh experience and open its private browser link.
2. In GECX, ask to add a driver. Confirm the ACG form appears.
3. Submit synthetic details and the acknowledgement checkbox.
4. Confirm a subsequent tool result contains those submitted details.
5. Ask to add a vehicle using the same experience and repeat.

Submissions return through an outstanding or subsequent tool call. If the agent has stopped checking, another conversational turn may be necessary. The verified pilot uses synchronous execution. A waiting tool can hold the agent turn for up to 20 seconds. Asynchronous execution returned pending placeholders and did not complete reliably in the validation session; do not enable it for the pilot without testing result delivery in your target channel. Voice interruption and PSTN/SIP calls have not been validated for this deployment.

The sandbox keeps one instance warm. Restarts, instance replacement and deployments clear experiences, so create a new one if the service reports an unknown session. Sessions also expire after one hour.

Available catalogues¶

The bundled page renders the ACG forms and legacy AutoChangeForm. Other components need your application's renderer. Spoken submissions currently do not fill fields in the open browser form.

See also¶

• Combined GECX, MCP and SMS architecture

• Interactive architecture and ANI/SMS flow

• ACG auto forms

• Auto insurance voice demos
• Cloud Run deployment runbook