Skip to main content
AgentSystems consists of several interconnected components that work together as an agent platform.

​
Core Components

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)

​
Request Flow

1

Client Request

User initiates agent execution via UI or SDK CLI
2

Gateway Processing

Control plane receives request, generates thread ID, and logs to database
3

Agent Discovery

Gateway locates target agent container via Docker labels (agent.enabled=true)
4

Container Management

Gateway attempts to start the container if needed
5

Request Forwarding

Gateway forwards request to agent’s /invoke endpoint with X-Thread-Id header
6

Agent Processing

Agent processes request using configured AI models and saves outputs to /artifacts/{thread_id}/out/
7

Response Return

Agent returns response, gateway logs completion, and results are returned

​
Network Architecture

Components communicate through Docker networks.

​
Docker Networks

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

​
Port Mappings

ServiceExternal PortInternal Port
UI30013001
Gateway180808080
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
Configuration changes made in the UI are written to these files and take effect on platform restart.

​
System Architecture

Each agent runs in a separate Docker container.
API keys are stored in environment variables separate from agent containers.
Operations are logged to PostgreSQL with request/response tracking.
HTTP proxy configuration supports URL allowlist functionality.