How-To: Register a Hamming Agent

A Hamming agent has to be registered for a team's phone number before any of the team's test cases will appear in Simulation Testing. This is the one-time setup that every team needs before authoring test cases.

Order of operations

You must register the Hamming agent before opening the Simulation Testing UI for that team. Otherwise the agent dropdown will be empty and you'll get stuck.

What this is

A "Hamming agent" is Hamming's representation of the assistant under test. Internally it's a registration row tying a Hamming-side agent ID to one of the team's phone_numbers rows in Supabase (the hamming_agent_id + hamming_agent_name columns).

The Simulation Testing dropdown is populated by GET /api/hamming/agents?teamId=..., which lists phone numbers WHERE hamming_agent_id IS NOT NULL. If no rows have that column set, the dropdown is empty even though the page loads correctly.

When you need to do this

Once per team, before any Hamming testing happens for that team. If you're setting up tests for a new team (e.g., a new EAS replica enterprise's shops), each team needs its own Hamming agent registration.

Prerequisites by voice-assistant mode

The voice assistant mode determines what else needs to be in place before registration succeeds. The registration flow internally calls resolveHammingExternalAgentId(), which has mode-specific branches.

Voice assistant mode	Prerequisites	Notes
VAPI_ASSISTANT / BUILDER_ASSISTANT	Voice assistant's vapi_assistant_id is populated (true for any published assistant).	Cleanest path. Resolution maps directly to the assistant ID.
MULTI_AGENT (Blueprint)	(1) test_inbound_call_phone_id set on the voice assistant. (2) That test phone has been Synced to Vapi (a squadId exists). (3) The squad has at least one member with an assistantId.	Heaviest path. Blueprint requires a persistent Vapi squad; registration bridges to the squad's first-member assistant.

If the voice assistant is MULTI_AGENT and any of those prerequisites are missing, registration either fails or produces an agent with no externalAgentId (Hamming has nothing to bridge to). Fix the missing pieces first.

Where to do it

The registration UI lives in the v1 web app's admin section, not the v2 dashboard:

https://app.avoca.ai/admin/voice-assistants

Source: apps/web/app/(restricted)/(protected)/admin/voice-assistants/page.tsx. Registration is wired through POST /api/hamming/agents/create.

You need admin access. If you don't have it, ask Kareem (or the appropriate Avoca team admin) to either grant access or perform the registration on your behalf.

Steps

1. Navigate to https://app.avoca.ai/admin/voice-assistants.
2. Find the team you're setting up. Filter by team name or scroll to find it.
3. Click into the team's voice assistant.
4. Check the assistant's mode (one of VAPI_ASSISTANT, BUILDER_ASSISTANT, MULTI_AGENT).
5. If MULTI_AGENT:
   • Verify there's a test phone configured. If not, provision one first (see provision-test-phone.ts).
   • Verify the test phone has been Synced (squadId visible). If not, click "Sync Test Phone" or trigger syncTestPhoneForVoiceAssistant via the admin UI.
6. Click the "Create Hamming Agent" action (label may vary; the underlying POST goes to /api/hamming/agents/create).
7. Provide a name for the agent (e.g., the shop name or "EAS Ponderosa Test").
8. Confirm. The response should include the new id and name.
9. Verify: open https://dashboard.avoca.ai/team/<TEAM_ID>/settings/responder/simulation-testing and confirm the agent now appears in the dropdown.

Verifying the registration

You can confirm registration via API too:

curl "https://app.avoca.ai/api/hamming/agents?teamId=<TEAM_ID>" | jq

Expected response: a { agents: [...] } array with at least one entry where id matches the newly-created Hamming agent ID and phoneNumbers lists the team's phone numbers.

Troubleshooting

Symptom	Likely cause	Fix
Simulation Testing dropdown is empty	No hamming_agent_id set on any team phone number	Complete this how-to
Registration returns 403 / Forbidden	Your account isn't on the team OR doesn't have admin role	Get team membership / admin role from Kareem
Registration succeeds but agent has no externalAgentId	Voice assistant is MULTI_AGENT and a test-phone prerequisite is missing	Fix the missing prereq (test phone provisioned, synced, squad has members) and re-register
Dropdown still empty after registration	Browser cache / dashboard didn't refetch	Hard-refresh the Simulation Testing page

Related

• Overview
• Tool Call Mocks
• How-To: Run a Test
• resolve-hamming-assistant.ts, the mode-specific bridge resolver
• provision-test-phone.ts, the test-phone provisioning helper
• sync-test-phone.ts, the test-phone sync helper for Blueprint mode