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

# Agent Connections

> Deploy and configure agents

Agents are containerized AI applications that process requests using configured model connections.

## Ways to Add Agents

There are two ways to add agents to your deployment:

1. **Via Index Connections**: Navigate to **[Index Connections](/fortress/configuration/index-connections)** to connect to community agent indexes, then browse and add agents from the **Discover** page
2. **Direct Configuration**: Manually configure agent connections when you know the exact container image details

<Warning>
  Before manually configuring agents on this page, you need:

  1. [Model connections](/fortress/configuration/model-connections) configured for AI providers
  2. [Registry connections](/fortress/configuration/registry-connections) for pulling agent images
</Warning>

## Managing via UI

Navigate to **Configuration → Agent Connections** in the AgentSystems UI at [http://localhost:3001](http://localhost:3001).

The UI allows you to:

* Manually configure agent deployments from known container images
* Edit agent settings and egress controls
* Remove agent connections

## Agent Configuration

Each agent deployment requires:

| Field                                  | Description                | Required  |
| -------------------------------------- | -------------------------- | --------- |
| `name`                                 | Unique agent identifier    | Yes       |
| `image`                                | Full image reference OR    | Choice of |
| `registry_connection` + `repo` + `tag` | Registry and image details | one       |
| `egress_allowlist`                     | Allowed outbound URLs      | No        |
| `artifact_permissions`                 | File access controls       | No        |

## Configuration Example

Agent with restricted internet access:

```yaml theme={null}
agents:
  - name: web-scraper-agent
    image: docker.io/agentsystems/scraper:latest
    egress_allowlist:
      - "https://api.example.com/*"
      - "https://data.provider.com/v1/*"
```

## Manual Configuration

Edit `agentsystems-config.yml` directly:

```yaml theme={null}
config_version: 1

agents:
  # Hello world demo agent
  - name: hello-world-agent
    image: docker.io/agentsystems/hello-world-agent:latest

  # Agent from private registry
  - name: custom-agent
    registry_connection: dockerhub_private
    repo: mycompany/custom-agent
    tag: v1.0.0

  # Agent with egress control
  - name: web-agent
    image: ghcr.io/company/agent:latest
    egress_allowlist:
      - "https://api.allowed.com/*"
```

After editing, restart the platform:

```bash theme={null}
agentsystems restart
```

## Agent Lifecycle

<Steps>
  <Step title="Deployment">
    When you add an agent to configuration:

    * The image is pulled from the specified registry
    * A Docker container is created with labels
    * Networking and volumes are configured
  </Step>

  <Step title="Discovery">
    The gateway discovers agents via Docker labels:

    * `agent.enabled=true` marks container as an agent
    * `agent.port=8000` specifies the agent's port
  </Step>

  <Step title="Idle Management">
    Agents may stop after periods of inactivity to save resources.
  </Step>
</Steps>