> ## Documentation Index
> Fetch the complete documentation index at: https://docs.groundforge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# External Agents

> Connect and inspect a LangChain or LangGraph Agent that runs in your application.

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

<Card title="groundforgeai/demo" icon="github" iconType="brands" href="https://github.com/groundforgeai/demo" horizontal cta="Open repository">
  The weather Agent shows automatic Channel input handling and an explicit-adapter version.
</Card>

Follow [LangChain Agent Example](/examples/langchain-agent) for the complete setup. The basic local start is:

```bash theme={null}
git clone https://github.com/groundforgeai/demo.git
cd demo
python simple_agent_service.py
```

## 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:

```text theme={null}
get_weather(city: string)
```

## 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:

```bash theme={null}
gforge agents discovery <agent-resource-id> -o yaml
gforge agents discovery <agent-resource-id> --status -o yaml
gforge agents observations <agent-resource-id>
gforge agents drifts <agent-resource-id>
```

> **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](/guides/twilio-whatsapp) or [Mailgun](/guides/mailgun), and send `What is the weather in Ottawa?`. Then open the Trace and compare the result under Allow, Review, and Block.


## Related topics

- [Agents](/platform/agents.md)
- [LangChain Agent Example](/examples/langchain-agent.md)
- [Credentials](/administration/credentials.md)
- [Usage Notes](/operations/usage-notes.md)