8 · ReferenceFAQ & gotchas

FAQ & common gotchas

Questions that trip up new joiners. If you hit something not covered here, ask in #cs-team on Slack and we’ll add it.

Agents & platform

Q: Are Clara, Vera, Nexa, Maya, Atlas actual code-level entities?

No. They are customer-facing brand names for workflows built from reusable agent templates. The codebase has templates like control_tower_supervisor, default_voice_agent_elevenlabs, and address_intelligence_supervisor. Brand names are assigned when deploying to a specific customer.

Q: Why isn’t my agent’s tool call working?

Most common causes:

  1. The tool isn’t assigned to the agent node in the workflow definition. Check the node’s tool list in the Dashboard.
  2. The external system (ProjectX, LIA) is returning an error. Check the job’s task detail in the Dashboard — it shows the tool call input and response.
  3. Rate limiting kicked in. The platform has per-minute/hour/day limits. Check agents-helper/rate_limiting.md in the repo.

Q: Why does my eval pass locally but fail in prod?

Usually one of:

  1. Different model version. Prod may be on a different model than your local setup.
  2. Different data. Prod has real customer data; your eval uses test data. Edge cases in real data break assumptions.
  3. Rate limiting. Prod has tighter rate limits. Your eval may be hitting tool calls that get throttled.
  4. Environment config. Check that env vars (especially QUERY_BUILDER_BASE_URL_MAP) point to the right environment.

Q: How do I switch the model an agent uses?

Model assignment is per-node in the workflow. Open the Dashboard → select the agent → select the node → change the model field. No code deployment needed. See Models.

Access & setup

Q: How do I get sandbox/demo access?

Ask your team lead for demo environment credentials. Demo environments are at *.demo.shipsy.in. Never use production for testing.

Q: How do I get access to the agent-platform repo?

Request GitHub access to shipsy/agent-platform via your manager. You’ll need a GitHub account added to the Shipsy org.

Q: How do I set up Claude Code?

Follow the setup guide in Cowork & Claude tools. Takes about 15 minutes.

Customer conversations

Q: A customer asks “where does our data go?”

Answer depends on their deployment mode:

  • Cloud: Data in Shipsy’s AWS infrastructure. LLM calls go to Azure OpenAI / GCP / Anthropic.
  • Hybrid: Data at rest stays on customer infra. LLM inference goes to cloud.
  • On-prem: Everything stays on customer infra.

See Security & compliance and Deployment modes for the full picture.

Q: A customer asks “can we use our own models?”

Yes, if on-prem. The platform supports Llama and Mistral for on-prem deployments. For cloud, we support OpenAI, Anthropic, and Gemini. Custom model integration is possible via the BaseLLM interface.

Q: Who do I ask about pricing?

Pricing is handled by the sales/account team. CS doesn’t quote pricing directly. If a customer asks, route to your account manager.

Q: A customer’s security team sent us a questionnaire. Where do I start?

Start with Security & compliance — it covers the most common questions (encryption, tenant isolation, PII masking, data residency, audit trail). For SOC 2 / ISO 27001 certification status, check with the security team.

Debugging

Q: An agent gave a customer wrong information. How do I investigate?

  1. Get the job ID from the Dashboard (or ask the customer for their query timestamp).
  2. Open the job in the Dashboard — see the full execution trace.
  3. Check each task: what was the LLM input, what was the response, what tools were called.
  4. Cross-reference tool call results with the actual data in TMS.
  5. If the data was correct but the agent misinterpreted it, it’s a prompt issue.
  6. If the data was wrong, it’s a tool/integration issue.

Q: The agent keeps escalating instead of answering. What’s wrong?

Usually the HITL policy threshold is too aggressive. Check:

  1. The HITL policy on the workflow/node level in the Dashboard.
  2. The confidence threshold — if set too high, low-confidence responses trigger escalation.
  3. The guardrails — content safety may be blocking legitimate responses.

Sources

Changelog

  • 26 May 2026: Full content with 15+ FAQs covering agents, access, customer conversations, and debugging.
TemplatesChangelog