Agenetix

Agent SDK

Test and debug Agent SDK integrations

Verify auth, conversation recovery, client tools, interruptions, and tool execution before you ship an App Agent into production.

6 sections

A production Agent SDK integration needs more than a successful happy-path prompt.

You should explicitly test:

  • same-user auth and account switching
  • resumed conversations
  • stale-conversation recovery after tool-catalog changes
  • client tools
  • approvals
  • structured input requests
  • feedback submission
  • MCP reconnect flows

A practical checklist#

1. Auth and identity#

Verify:

  • appSessionKey changes on logout/login
  • userIdentity matches the real host user
  • a second user on the same machine does not inherit the first user's MCP auth
  • reconnect flows surface clearly when a server needs auth

2. Conversations#

Verify:

  • a conversation resumes after refresh or app reopen when it should
  • a conversation resets when the user explicitly starts over
  • an old conversation does not continue if tool compatibility has changed

3. Client tools#

Verify:

  • the right client tool runs after the right MCP mutation
  • client tools return structured results
  • invalid client-tool params fail safely
  • the agent prompt and appContext teach the MCP-to-client-tool handoff clearly

4. Interruptions#

Verify:

  • destructive flows trigger requestApproval
  • missing structured inputs trigger requestInput
  • reject and cancel paths are handled cleanly
  • the agent continues correctly after approval or request submission

5. UI state#

Verify:

  • pending-turn state appears while the turn is running
  • statusLabel reflects attention states accurately
  • connection banners and reconnect affordances line up with connections.needsAttention
  • feedback state disables duplicate submissions

Debugging the hook surface#

When debugging a custom integration, inspect these first:

  • agent.conversation.error
  • agent.conversation.issue
  • agent.conversation.statusLabel
  • agent.connections.items
  • agent.connections.needsAttention
  • agent.approvals.pending
  • agent.requests.pending

If those are right, the bug is often in your app UI.

If those are wrong, the bug is usually in configuration, auth, or client-tool policy.

Common failure patterns#

Wrong-session auth reuse#

Usually caused by:

  • missing appSessionKey
  • unstable or incorrect session key

Auth works in playground but not in app#

Usually caused by:

  • missing or wrong userIdentity
  • missing allowed origins
  • host auth callback mismatch
  • custom onAuthRequired logic diverging from the built-in flow

Tool works on server but UI does not update#

Usually caused by:

  • the agent used the MCP tool but no follow-up client tool refreshed the page
  • the client tool exists but the prompt/context does not teach the agent when to call it

The agent keeps asking vague follow-ups#

Usually caused by:

  • no prompt policy telling it to use requestInput
  • no structured request UI being rendered by the app

Local development tips#

For local development:

  • confirm your serviceUrl points to the correct local API
  • verify the local help/web app is serving the default OAuth callback and metadata routes when using the built-in popup flow
  • test both fresh auth and resume flows
  • test with at least one page refresh or app restart

Before shipping:

  • test the agent in playground
  • test the same agent in the real app
  • test a fresh user session
  • test a reconnect-required session
  • test an approval flow
  • test a requestInput flow
  • test feedback submission
  • test logout/login with a different user