Skip to main content
An external Agent runs in your application rather than inside GroundForge. The GroundForge Python SDK keeps an outbound connection to the SaaS platform so the Agent can receive Channel requests, report its tools, apply Gateway decisions, and publish Traces. Use this model when you already own the Agent code or need full control of the model loop.

​
Start with the demo

groundforgeai/demo

The weather Agent shows automatic Channel input handling and an explicit-adapter version.
Follow LangChain Agent Example for the complete setup. The basic local start is:

​
What GroundForge receives

When the process connects, GroundForge can show:
  • whether the Agent is connected;
  • the stable external Agent identity and GroundForge resource ID;
  • discovered tools and their input schemas;
  • attached Channels and Gateway rules;
  • Observations and Drifts from Discovery;
  • Traces and Analytics from requests.
For the demo, Discovery should list:

​
What happens for a Channel request

  1. A Channel receives and verifies the provider callback.
  2. The running SDK process claims the request.
  3. Automatic mode or your adapter converts the normalized Channel input.
  4. The Agent decides whether to call get_weather.
  5. GroundForge applies the matching Gateway action before the tool runs.
  6. The SDK returns the final text for Channel delivery.
  7. GroundForge records one Trace for the request.
Check the current records with:
Screenshot placeholder
Add /images/platform/external-agent.png showing connection state, identities, get_weather, attached Channel, and Gateway.

​
Example

Run the weather Agent, attach Twilio WhatsApp or Mailgun, and send What is the weather in Ottawa?. Then open the Trace and compare the result under Allow, Review, and Block.
Last modified on July 27, 2026

Related topics

AgentsLangChain Agent ExampleCredentialsUsage Notes