These notes come from the current runtime behaviour and prevent common configuration mistakes.
Scope matters
Check the active Organization and Workspace before creating an Agent, Channel, MCP provider, Gateway, credential, or Trace query. Resources in different Workspaces cannot be combined in one request.
Publish after attaching a Channel
Attach the Channel to the Agent, save, and publish the Agent before configuring the provider callback. Use the generated URL with immutable Agent and Channel IDs:
Renaming a display name does not change those IDs.
Provider signatures are verified
Twilio and Mailgun callbacks are verified before GroundForge normalizes or processes the message. Copy the callback exactly and keep the signing credential current.
Twilio sender and test recipient are different
Store the WhatsApp sender in the Channel. Pass the recipient only when running a Channel test. In the Twilio sandbox, the recipient must have joined the sandbox, and sender and recipient must not be the same number.
External Agents must stay connected
An external Agent receives Channel jobs only while its SDK process is running with serve=True. Direct tracing with serve=False does not receive Channel jobs.
Credentials are write-only
Model keys and other generated secrets are not returned after they are saved. Store the original value in a protected secret manager. A model credential belongs to the Agent; a Channel credential belongs to the Channel; an MCP connection credential belongs to the provider.
Local stdio secrets stay local
When gforge discovers a local stdio MCP server, environment secret values remain on that machine. GroundForge uploads capability definitions, not raw local environment secrets.
Discovery is explicit
Opening Observations or Drifts reads saved records. It does not run Discovery. Start a new Discovery only when you want GroundForge to read the current Agent or MCP capability definitions.
Country, region, city, language, or campaign breakdowns appear only when a Channel or caller supplies reliable data. GroundForge does not perform IP geolocation and external-Agent examples do not assume custom user_id metadata.
Historical Traces keep their original detail
A newer SDK or UI can improve future Trace structure, but it cannot reconstruct model, tool, parent-run, or Channel details that were never recorded in older requests.
Example
Before testing the LangChain weather Agent, confirm the Workspace, keep the Agent running, publish the Channel attachment, run a dry-run delivery test, and then send one new request. This gives you a clean Trace to compare with the expected flow in LangChain Agent Example. Last modified on July 27, 2026
