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

# Key Concepts

> How AgentSystems components work together

AgentSystems consists of several interconnected components that work together as an agent platform.

## Core Components

<Tabs>
  <Tab title="Control Plane">
    **Agent Control Plane (Gateway)**

    The gateway is the central orchestration layer that:

    * Discovers agent containers via Docker labels
    * Routes requests to agents
    * Handles container lifecycle operations
    * Routes requests via HTTP proxy
    * Logs operations to database

    Runs on port 18080 (external) / 8080 (internal)
  </Tab>

  <Tab title="UI">
    **AgentSystems UI**

    Web interface for platform management:

    * Agent discovery and execution
    * Configuration management
    * Execution monitoring and history
    * Audit log viewing

    Accessible at [http://localhost:3001](http://localhost:3001)
  </Tab>

  <Tab title="SDK">
    **AgentSystems SDK**

    Command-line tool for platform operations:

    * Deployment initialization (`agentsystems init`)
    * Service management (`agentsystems up/down`)
    * Agent execution (`agentsystems run`)
    * Log viewing (`agentsystems logs`)
  </Tab>

  <Tab title="Database">
    **PostgreSQL**

    Persistent storage for:

    * Execution history
    * Audit logs with hash-chaining
    * Agent metadata
    * Configuration data
  </Tab>
</Tabs>

## Request Flow

<Steps>
  <Step title="Client Request">
    User initiates agent execution via UI or SDK CLI
  </Step>

  <Step title="Gateway Processing">
    Control plane receives request, generates thread ID, and logs to database
  </Step>

  <Step title="Agent Discovery">
    Gateway locates target agent container via Docker labels (`agent.enabled=true`)
  </Step>

  <Step title="Container Management">
    Gateway attempts to start the container if needed
  </Step>

  <Step title="Request Forwarding">
    Gateway forwards request to agent's `/invoke` endpoint with `X-Thread-Id` header
  </Step>

  <Step title="Agent Processing">
    Agent processes request using configured AI models and saves outputs to `/artifacts/{thread_id}/out/`
  </Step>

  <Step title="Response Return">
    Agent returns response, gateway logs completion, and results are returned
  </Step>
</Steps>

## Network Architecture

<Info>
  Components communicate through Docker networks.
</Info>

### Docker Networks

* **agents-net**: Platform services communication
* **agents-int**: Agent-to-gateway isolated network

### Port Mappings

| Service    | External Port | Internal Port |
| ---------- | ------------- | ------------- |
| UI         | 3001          | 3001          |
| Gateway    | 18080         | 8080          |
| PostgreSQL | -             | 5432          |
| Proxy      | -             | 3128          |

## File System Structure

### Artifacts Directory

Each agent invocation gets isolated storage:

```
/artifacts/
├── {thread-id}/
│   ├── in/          # Input files from client
│   └── out/         # Output files from agent
```

### Configuration Files

The UI manages configuration files that control the platform:

* **`.env`**: API keys and credentials
* **`agentsystems-config.yml`**: Model connections, registries, and agents

<Note>
  Configuration changes made in the UI are written to these files and take effect on platform restart.
</Note>

## System Architecture

<Accordion title="Container Isolation">
  Each agent runs in a separate Docker container.
</Accordion>

<Accordion title="Credential Management">
  API keys are stored in environment variables separate from agent containers.
</Accordion>

<Accordion title="Audit Trail">
  Operations are logged to PostgreSQL with request/response tracking.
</Accordion>

<Accordion title="Egress Control">
  HTTP proxy configuration supports URL allowlist functionality.
</Accordion>