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

# Agents

> Understand managed and external Agents through the weather examples.

An Agent receives a request, decides what to do, and returns a response. It may answer directly, call one of its own tools, or call a capability from an MCP provider.

GroundForge supports two Agent operating models:

| Agent type     | Where the Agent runs | Who owns the model loop |
| -------------- | -------------------- | ----------------------- |
| Managed Agent  | GroundForge runtime  | GroundForge             |
| External Agent | Your Python process  | Your application        |

Both can use Channels, Gateway rules, Operator review, Traces, and Analytics.

## Managed Agent

A managed Agent is configured in the GroundForge platform. GroundForge sends the request to the configured model and invokes only capabilities attached through the Agent’s governed setup.

### Example

<Card title="modelcontextprotocol/quickstart-resources" icon="github" iconType="brands" href="https://github.com/modelcontextprotocol/quickstart-resources/tree/main/weather-server-python" horizontal cta="Open repository">
  Use the official Weather MCP as the capability source for a managed weather Agent.
</Card>

1. Complete [Weather MCP Example](/examples/weather-mcp) so GroundForge knows `get_alerts` and `get_forecast`.
2. In **Agents**, create a managed Agent and choose its model and model credential.
3. Attach the Weather MCP through an MCP-targeted Gateway.
4. Publish the Agent and attach a Channel if users should reach it through messaging.
5. Send a request and open its Trace.

A managed weather request may look like:

```text theme={null}
User asks for a forecast
→ Agent selects get_forecast
→ Gateway checks the rule
→ Weather MCP runs or waits for Review
→ Agent writes the response
→ GroundForge records the Trace
```

## External Agent

An external Agent stays in your application. The GroundForge SDK registers it, reports its tools, receives Channel jobs, applies Gateway decisions before a tool runs, and sends Trace events back to GroundForge.

### Example

<Card title="groundforgeai/demo" icon="github" iconType="brands" href="https://github.com/groundforgeai/demo" horizontal cta="Open repository">
  Run the LangChain weather Agent with automatic input handling or explicit adapters.
</Card>

Initialize GroundForge after constructing the Agent:

```python theme={null}
import os
from groundforge_langchain import init as init_groundforge

init_groundforge(
    agent=agent,
    endpoint="https://platform.groundforge.ai",
    api_key=os.environ["GROUNDFORGE_API_KEY"],
    agent_id=os.environ["GROUNDFORGE_AGENT_ID"],
    tenant_id=os.environ["GROUNDFORGE_TENANT_ID"],
    workspace_id=os.environ["GROUNDFORGE_WORKSPACE_ID"],
    params={"channelInputMode": "auto"},
    serve=True,
)
```

The example does not assume custom caller metadata. The SDK receives the normalized Channel input and passes it to the Agent.

Start with [LangChain Agent Example](/examples/langchain-agent), then compare [LangChain Agent with Adapters](/examples/langchain-adapter).

## Example paths

Use [Weather MCP Example](/examples/weather-mcp) for a managed Agent capability source and [LangChain Agent Example](/examples/langchain-agent) for an external Agent.


## Related topics

- [Agents](/platform/agents.md)
- [Get Agent](/api-reference/endpoints/agents/get-agent.md)
- [Publish Agent](/api-reference/endpoints/agents/publish-agent.md)
- [Update Agent](/api-reference/endpoints/agents/update-agent.md)