# Agent Connections Source: https://docs.agentsystems.ai/fortress/configuration/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 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 ## 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 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 The gateway discovers agents via Docker labels: * `agent.enabled=true` marks container as an agent * `agent.port=8000` specifies the agent's port Agents may stop after periods of inactivity to save resources. # Credentials Source: https://docs.agentsystems.ai/fortress/configuration/credentials Managing API keys and authentication tokens Credentials are the foundation of your AgentSystems configuration. They provide access to AI providers and container registries. Credentials are stored as environment variables. The system design separates credentials from agent containers. ## Managing Credentials via UI Navigate to **Configuration → Credentials** in the AgentSystems UI at [http://localhost:3001](http://localhost:3001). The UI allows you to: * Add new credentials * Update existing credentials * Remove unused credentials Changes made in the UI are written to the `.env` file in your deployment directory. ## Manual Configuration If editing the `.env` file directly: 1. Open `.env` in your deployment directory 2. Add credentials as key=value pairs 3. Save the file 4. Restart the platform: `agentsystems restart` ## Credential Usage Credentials are used by: * **Model Connections**: Reference credentials via environment variable names * **Registry Connections**: Authenticate to pull agent images * **Agents**: Credentials are managed by the platform at runtime # GPU Acceleration Source: https://docs.agentsystems.ai/fortress/configuration/gpu-acceleration Enable NVIDIA GPU acceleration for Ollama ## Prerequisites * Linux with NVIDIA GPU * [NVIDIA drivers and nvidia-container-toolkit](https://hub.docker.com/r/ollama/ollama) installed ## Configuration After running `agentsystems init`, edit `compose/local/docker-compose.yml` and add this to the `ollama` service: ```yaml theme={null} ollama: image: ollama/ollama:latest # ... existing configuration ... deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] ``` Then run: ```bash theme={null} agentsystems up ``` ## Verify Check GPU usage while running a model: ```bash theme={null} nvidia-smi ``` macOS does not support NVIDIA GPUs in Docker. AMD/Intel GPU support is not currently available. # Configuration Overview Source: https://docs.agentsystems.ai/fortress/configuration/index Configure the AgentSystems platform AgentSystems offers two ways to add agents: browse community indexes or configure agents directly. Most agents require AI provider configuration via Model Connections. ## Configuration Paths **Browse and discover community agents** Add API keys for AI providers Navigate to **Configuration → Credentials** Connect to AI providers using your credentials Navigate to **Configuration → Model Connections** Connect to community agent indexes Navigate to **Configuration → Index Connections** Discover and add agents from indexes Navigate to **Discover** to browse available agents **Manually configure agents from known images** Add API keys for AI providers and container registries Navigate to **Configuration → Credentials** Connect to AI providers using your credentials Navigate to **Configuration → Model Connections** Set up container registries to pull agent images Navigate to **Configuration → Registry Connections** Configure agent deployments from container images Navigate to **Configuration → Agent Connections** ## Configuration Methods Use the AgentSystems UI at [http://localhost:3001](http://localhost:3001) The UI includes: * Visual configuration forms * Form validation * Direct file management Edit configuration files directly: **`.env`** - API keys and credentials ```bash theme={null} OPENAI_API_KEY=sk-... ANTHROPIC_API_KEY=sk-ant-... ``` **`agentsystems-config.yml`** - Platform configuration ```yaml theme={null} config_version: 1 model_connections: # Model configs registry_connections: # Registry configs agents: # Agent deployments ``` ## Quick Links ### Connections Connect to AI providers Browse community agents Add container registries Configure agent deployments ### System Manage API keys ## Configuration Files Location Configuration files are stored in your deployment directory: ``` my-deployment/ ├── .env # API keys and credentials ├── agentsystems-config.yml # Platform configuration └── docker-compose.yml # Service definitions ``` After making configuration changes, restart the platform with `agentsystems restart` for changes to take effect. # Index Connections Source: https://docs.agentsystems.ai/fortress/configuration/index-connections Discover community agents from public indexes Index connections allow AgentSystems to discover and browse community agents from public agent indexes. Connect to multiple indexes to expand your agent library. AgentSystems does not review or endorse software in any index. ## Managing via UI Navigate to **Configuration → Index Connections** in the AgentSystems UI at [http://localhost:3001](http://localhost:3001). The UI allows you to: * Add public agent indexes * Enable/disable index connections * Browse agents from enabled indexes on the Discover page ## Configuration Structure Each index connection requires: | Field | Description | Required | | ------------- | ------------------------------------------------------------ | -------- | | `name` | Unique identifier (lowercase, numbers, hyphens, underscores) | Yes | | `url` | Index API URL (must be http\:// or https\://) | Yes | | `enabled` | Whether this index is active | Yes | | `description` | Human-readable description | No | ## Manual Configuration Edit `agentsystems-config.yml` directly: ```yaml theme={null} config_version: 1 index_connections: # AgentSystems community index agentsystems-community: url: https://agentsystems.github.io/agent-index enabled: true description: AgentSystems community index # Custom company index mycompany-index: url: https://index.mycompany.com enabled: true description: Internal agent catalog ``` After editing, restart the platform: ```bash theme={null} agentsystems restart ``` ## Index Structure Agent indexes may provide: * Agent metadata (name, description, developer) * Container image location and tag * Model requirements * Egress allowlist * Additional metadata ## Enabling an Index When enabling an index, you acknowledge that this third-party software has not been reviewed or endorsed by AgentSystems. Provide the index URL and a unique name for the connection. Check the "Enabled" checkbox and acknowledge the community software disclaimer. Navigate to **Discover** to browse and add agents from enabled indexes. ## Disabling an Index Disabling an index connection will: * Hide agents from that index on the Discover page * Not affect already-deployed agents from that index * Allow you to re-enable the connection at any time ## Index Security AgentSystems does not review or endorse software in any index. If you change an index URL while it's enabled, you must re-acknowledge that this third-party software has not been reviewed or endorsed by AgentSystems. # Model Connections Source: https://docs.agentsystems.ai/fortress/configuration/model-connections Connect to AI providers Model connections define how agents access AI providers. Each connection maps a model ID to a specific provider and authentication method. Set up [credentials](/fortress/configuration/credentials) before configuring model connections. ## Managing via UI Navigate to **Configuration → Model Connections** in the AgentSystems UI at [http://localhost:3001](http://localhost:3001). The UI allows you to: * Add connections to AI providers * Enable/disable connections ## Supported Models | Model ID | Display Name | Providers | Required Credentials | | ------------------- | ----------------- | ---------------------- | -------------------------------------- | | `gpt-4o` | GPT-4o | OpenAI | `OPENAI_API_KEY` | | `gpt-4o-mini` | GPT-4o mini | OpenAI | `OPENAI_API_KEY` | | `claude-3-5-sonnet` | Claude 3.5 Sonnet | Anthropic, AWS Bedrock | `ANTHROPIC_API_KEY` or AWS credentials | | `claude-3-5-haiku` | Claude 3.5 Haiku | Anthropic, AWS Bedrock | `ANTHROPIC_API_KEY` or AWS credentials | | `llama3.1:8b` | Llama 3.1 8B | Ollama, AWS Bedrock | None (Ollama) or AWS credentials | | `gemma3:1b` | Gemma 3 1B | Ollama | None (local) | | `nova-pro` | Amazon Nova Pro | AWS Bedrock | AWS credentials | For the full list of supported models, check the Model Connections page in the UI at [http://localhost:3001](http://localhost:3001). ## Configuration Structure Each model connection requires: | Field | Description | Required | | --------------------------- | ----------------------------------------------------------------- | -------- | | `hosting_provider` | Provider name (`openai`, `anthropic`, `amazon_bedrock`, `ollama`) | Yes | | `hosting_provider_model_id` | Provider-specific model identifier | Yes | | `enabled` | Whether this connection is active | Yes | | `auth` | Authentication configuration | Yes | | `hosting_provider_base_url` | Custom endpoint (Ollama only) | No | | `hosting_provider_region` | AWS region (Bedrock only) | No | ## Manual Configuration Edit `agentsystems-config.yml` directly: ```yaml theme={null} config_version: 1 model_connections: # Give each connection a unique ID my-gpt4-connection: hosting_provider: openai hosting_provider_model_id: gpt-4 enabled: true auth: method: api_key api_key_env: OPENAI_API_KEY my-claude-connection: hosting_provider: anthropic hosting_provider_model_id: claude-3-opus-20240229 enabled: true auth: method: api_key api_key_env: ANTHROPIC_API_KEY ``` After editing, restart the platform: ```bash theme={null} agentsystems restart ``` # Registry Connections Source: https://docs.agentsystems.ai/fortress/configuration/registry-connections Configure container registry access Registry connections allow AgentSystems to pull agent images from container registries. You can connect to multiple registries simultaneously. Public registries typically work without credentials; some images may require authentication or be rate-limited. Private registries require authentication configured in [credentials](/fortress/configuration/credentials). ## Managing via UI Navigate to **Configuration → Registry Connections** in the AgentSystems UI at [http://localhost:3001](http://localhost:3001). The UI allows you to: * Add public and private registries * Configure authentication methods * Enable/disable registry connections ## Configuration Structure Each registry connection requires: | Field | Description | Required | | ------------------- | ------------------------------------------------ | -------- | | `url` | Registry hostname (e.g., `docker.io`, `ghcr.io`) | Yes | | `enabled` | Whether this connection is active | Yes | | `auth.method` | Authentication type: `none`, `basic`, `bearer` | Yes | | `auth.username_env` | Environment variable for username (basic auth) | No | | `auth.password_env` | Environment variable for password (basic auth) | No | | `auth.token_env` | Environment variable for token (bearer auth) | No | ## Manual Configuration Edit `agentsystems-config.yml` directly: ```yaml theme={null} config_version: 1 registry_connections: # Public Docker Hub (no auth needed) dockerhub_public: url: docker.io enabled: true auth: method: none # Private Docker Hub dockerhub_private: url: docker.io enabled: true auth: method: basic username_env: DOCKERHUB_USER password_env: DOCKERHUB_TOKEN # GitHub Container Registry github: url: ghcr.io enabled: true auth: method: basic username_env: GHCR_USER password_env: GHCR_TOKEN ``` After editing, restart the platform: ```bash theme={null} agentsystems restart ``` ## Registry Usage in Agent Configuration Agents reference registry connections when specifying their image source: ```yaml theme={null} agents: - name: my-agent registry_connection: dockerhub_private # References the connection ID repo: mycompany/my-agent tag: v1.0.0 ``` ## Authentication Methods For public registries and images. No credentials required. Username and password/token authentication. Used by Docker Hub, GHCR, and many private registries. Token-based authentication. Common for enterprise registries. # List on Index Source: https://docs.agentsystems.ai/fortress/deploy-agents/list-on-index Add your agent to the public index for discovery Publishing metadata to the agent index makes your agent **discoverable** in the AgentSystems platform. The index contains metadata only - your actual agent image can be public or private. Metadata submissions are automatically validated and merged. ## Prerequisites * GitHub account with commit signing enabled ([Setup Guide](https://docs.github.com/en/authentication/managing-commit-signature-verification)) * Agent deployed (see [Quickstart](/fortress/deploy-agents/quickstart)) * 5 minutes **Commit Signing Required**: All commits in your PR must be signed with a verified GPG or SSH key. Unverified commits will be rejected by the auto-merge workflow. This requirement helps verify that commits are cryptographically signed and match the author identity. ## Overview The [agent-index repository](https://github.com/agentsystems/agent-index) is an open-source, Git-based registry for agent metadata enabling federated discovery. Instead of a centralized API: * Developers manage their own YAML files in `developers/your-github-username/` * Pull requests are automatically validated and merged—no manual approval needed * Metadata is published to `https://agentsystems.github.io/agent-index/` * The AgentSystems UI consumes this index (and can connect to multiple indexes) * Anyone can fork the repository and run their own independent index **Disclaimer**: Inclusion in the index does not constitute endorsement. The index provides metadata submitted by developers and does not verify agent quality, functionality, or security. ## Step 1: Fork the Repository Go to [github.com/agentsystems/agent-index](https://github.com/agentsystems/agent-index) and click **"Fork"**. Clone your fork: ```bash theme={null} git clone https://github.com/your-github-username/agent-index.git cd agent-index ``` ## Step 2: Create Your Developer Profile Create your developer folder (must match your GitHub username): ```bash theme={null} mkdir -p developers/your-github-username ``` Copy the example profile: ```bash theme={null} cp examples/profile.yaml developers/your-github-username/profile.yaml ``` Edit `developers/your-github-username/profile.yaml`: ```yaml theme={null} name: Your Name or Company developer: your-github-username # Must match folder name type: individual # individual, organization, company, or enterprise bio: Developer of AI agents for... website: https://example.com support_email: hello@example.com # Optional fields tagline: Building the future of AI agents location: San Francisco, CA twitter_handle: yourhandle linkedin_url: https://linkedin.com/in/yourprofile expertise: - Natural Language Processing - Data Analysis - Multi-Agent Systems open_to_collaboration: true ``` **Required**: * `name` (string): Display name * `developer` (string): Developer namespace - must match folder name **Optional**: * `type` (string): "individual", "organization", "company", or "enterprise" * `avatar_url` (string): Profile image URL * `bio` (string): Short biography * `tagline` (string): Short tagline or slogan * `company` (string): Company name * `location` (string): Geographic location * `years_experience` (integer): Years in AI/ML * `website` (string): Your website URL * `support_email` (string): Support email * `documentation_url` (string): Docs URL * `twitter_handle` (string): Twitter/X handle (without @) * `linkedin_url` (string): LinkedIn profile * `discord_username` (string): Discord username * `expertise` (array): Areas of expertise * `featured_work` (array): URLs to featured projects * `open_to_collaboration` (boolean): Open to collaboration * `sponsor_url` (string): GitHub Sponsors or similar ## Step 3: Add Your Agent Metadata Create the agents folder: ```bash theme={null} mkdir -p developers/your-github-username/agents ``` Copy the example agent: ```bash theme={null} # Create your agent directory mkdir -p developers/your-github-username/agents/your-agent # Copy example files cp examples/agents/demo-agent/agent.yaml developers/your-github-username/agents/your-agent/ cp examples/agents/demo-agent/versions.yaml developers/your-github-username/agents/your-agent/ cp examples/agents/demo-agent/0.1.0.yaml developers/your-github-username/agents/your-agent/ ``` The directory structure will be: ``` developers/your-github-username/agents/your-agent/ agent.yaml # Agent identity (who/what it is) versions.yaml # Version management (which versions) 0.1.0.yaml # Version specification (how it behaves) ``` Edit the three YAML files: **`agent.yaml`** - Set your agent identity: * `developer` - Must match your GitHub username * `name` - Must match directory name * `description`, `container_image`, `tags`, `capabilities` - See examples folder for all fields **`versions.yaml`** - Set version management: * `latest_version: "0.1.0"` * `listed_versions:` with `- "0.1.0"` (use dash notation) **`0.1.0.yaml`** - Set version-specific attributes: * `version` - Must match filename ("0.1.0") * `model_dependencies:` with `- gemma3:1b` (use dash notation) * `readiness_level`, `input_schema`, `facets` - See examples folder for all fields See `examples/agents/demo-agent/` in the repository for complete examples of all three files with all available fields and documentation. **Required in agent.yaml (Agent Identity)**: * `name` (string): Agent name (lowercase, alphanumeric, hyphens) * `developer` (string): Your GitHub username (must match folder name) * `description` (string): Short description * `container_image` (string): Container image reference without tag (e.g., docker.io/user/agent) **Optional in agent.yaml (Agent Identity)**: * `source_repository_url` (string): Source code URL * `primary_function` (string): Primary function category * `tags` (array): Searchable tags * `capabilities` (array): High-level capability descriptions **Required in versions.yaml (Version Management)**: * `latest_version` (string): Latest version (must match an existing .yaml file) * `listed_versions` (array): Versions visible in discovery (each must match an existing .yaml file) **Required in .yaml files (Version Specification)**: * `version` (string): Semantic version (e.g., "0.1.0" or "1.0.0-beta.1"), used as container image tag * `model_dependencies` (array): Required AI models (at least one) **Optional in .yaml files**: * `readiness_level` (string): "experimental", "beta", "production", or "deprecated" * `container_image_access` (string): "public" or "private" * `source_repository_access` (string): "public" or "private" * `required_egress` (array): Required network egress URLs * `required_integrations` (array): Required external integrations * `input_types` (array): Supported input data types * `output_types` (array): Supported output data types * `input_schema` (object): Input parameter schema * `facets` (object): Behavioral characteristics and categorization * `context` (string): Operating context (personal, professional, general) * `autonomy` (string): Autonomy level (Assist, Co-pilot, Auto-pilot) * `latency` (string): Latency profile (real-time, interactive, batch) * `cost_profile` (string): Cost model (free, $/task, $/month) * `modalities` (array): Supported modalities (text, image, audio, video) * `domains` (array): Application domains * `model_tooling` (array): Model frameworks (LLM, RAG, fine-tuned, embeddings) * `industries` (array): Target industries * `integrations` (array): Supported integrations * `release_notes` (string): Markdown-formatted release notes See the schemas for complete details: * [agent-identity.schema.json](https://github.com/agentsystems/agent-index/blob/main/schema/agent-identity.schema.json) - agent.yaml * [versions.schema.json](https://github.com/agentsystems/agent-index/blob/main/schema/versions.schema.json) - versions.yaml * [agent-version.schema.json](https://github.com/agentsystems/agent-index/blob/main/schema/agent-version.schema.json) - .yaml ## Step 4: Validate Locally (Optional) Validation runs automatically on your PR, but testing locally helps catch issues early. ```bash theme={null} python3 -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate pip install pyyaml jsonschema python scripts/validate.py all ``` Should output: ``` ✅ All validations passed! ``` ## Step 5: Submit Pull Request Commit and push: ```bash theme={null} git add developers/your-github-username/ git commit -m "Add your-github-username profile and your-agent" git push origin main ``` Go to your fork on GitHub and click **"Contribute"** → **"Open pull request"**. ## What Happens Next Your PR triggers automated workflows: 1. **Policy Gate**: Validates folder ownership (checks your GitHub username matches folder name) 2. **YAML Validation**: Checks syntax and schema compliance 3. **Auto-Merge**: If all checks pass, PR is automatically approved and merged 4. **Build & Deploy**: Index is rebuilt and published to GitHub Pages Your agent should appear at `https://agentsystems.github.io/agent-index/` shortly after the build completes. ## Publishing New Versions To publish a new version of your agent: 1. Create a new version file in your agent directory: ```bash theme={null} # Copy your current version as a template cp developers/your-github-username/agents/your-agent/0.1.0.yaml \ developers/your-github-username/agents/your-agent/0.2.0.yaml ``` 2. Edit the new version file: * Update `version: "0.2.0"` (must match filename) * Modify any behavioral changes (model, facets, schema, etc.) * Add release notes 3. Update versions.yaml: * Change `latest_version: "0.1.0"` to `latest_version: "0.2.0"` * Add `"0.2.0"` to `listed_versions` array * Optionally remove old versions from `listed_versions` to hide them ```yaml theme={null} latest_version: "0.2.0" listed_versions: - "0.1.0" # Keep if users might want old version - "0.2.0" # New version ``` 4. Commit and push: ```bash theme={null} git add developers/your-github-username/agents/your-agent/ git commit -m "Release 0.2.0 of your-agent" git push origin main ``` **Git diff clarity**: Adding 0.2.0 shows as a clean new file in your PR, making reviews simple and clear. ## Updating Agent Identity To update your agent's identity (description, tags, capabilities): 1. Edit `developers/your-github-username/agents/your-agent/agent.yaml` 2. Commit and push to your fork 3. Open a new pull request 4. Auto-merge handles the rest Note: Identity fields affect all versions. Version-specific changes go in the .yaml files. ## Security Model The index uses **fork-based ownership**: * ✅ Only you can modify `developers/your-github-username/` (checked via fork ownership) * ✅ PRs touching only your folder auto-merge * ✅ PRs touching core files require maintainer approval * ✅ Multiple validation layers protect the index ## Troubleshooting ### PR not auto-merging **Check**: 1. All files are in `developers/your-github-username/` (folder name must match your GitHub username exactly) 2. YAML validation passes (check the workflow logs) 3. You're submitting from a fork (not a branch in the main repo) 4. All commits are signed and verified (see below) ### YAML validation fails Common issues: * **Syntax error**: Check YAML indentation (use spaces, not tabs) * **Missing required field**: Ensure `name`, `developer` (in profile.yaml), `version`, `description`, and `model_dependencies` are present * **Invalid value**: Check enum fields like `readiness_level` Run `python scripts/validate.py all` locally to see detailed error messages. ### Folder ownership check fails **Error**: "Developer folder (your-name) does not match PR head repository owner (different-name)" **Solution**: Your folder name must exactly match your GitHub username. If your fork is under a different account, the folder name must match that account. ### Unverified commits **Error**: "PR contains unverified commits. All commits must be signed with a verified GPG or SSH key." **Solution**: 1. Verify your git config matches your signing key: ```bash theme={null} git config user.name # Should match your GitHub username git config user.email # Should match your signing key email ``` 2. Set up commit signing: [GitHub Docs](https://docs.github.com/en/authentication/managing-commit-signature-verification) 3. Configure auto-signing: ```bash theme={null} git config commit.gpgsign true # For GPG # or git config gpg.format ssh # For SSH keys git config user.signingkey ~/.ssh/id_ed25519.pub ``` 4. If commits are already pushed, you'll need to amend and force-push (or create a new PR with signed commits) ## Next Steps * **Discover agents**: Browse the index at [agentsystems.github.io/agent-index](https://agentsystems.github.io/agent-index/) * **Deploy private agents**: See [Deploying Private Agents](/fortress/deploy-agents/private-agents) * **Review schemas**: Full schemas at [github.com/agentsystems/agent-index/tree/main/schema](https://github.com/agentsystems/agent-index/tree/main/schema) # Deploying Private Agents Source: https://docs.agentsystems.ai/fortress/deploy-agents/private-agents Deploy agents using private Docker registries Private agents use private repositories to control access to your agent images. You can use private Docker Hub repositories, GitHub Container Registry (GHCR), or Harbor. ## Docker Hub Private Repository This guide shows how to deploy an agent using a private Docker Hub repository with access tokens. ### Prerequisites * AgentSystems platform running ([Installation Guide](/fortress/getting-started/quickstart)) * Docker installed and running * Docker Hub account (free at [hub.docker.com](https://hub.docker.com)) ### Step 1: Get the Template Go to [github.com/agentsystems/agent-template](https://github.com/agentsystems/agent-template) and click **"Use this template"** → **"Create a new repository"**. Name it `demo-agent-private` and clone it: ```bash theme={null} git clone https://github.com/your-org/demo-agent-private.git cd demo-agent-private ``` ### Step 2: Review the Template The template includes a demo agent. This guide deploys it as a private agent (not publicly discoverable). To customize the agent logic, edit `main.py` and modify the agent's behavior. For this guide, we'll deploy the template as-is. ### Step 3: Build and Push to Private Repository Log in to Docker Hub: ```bash theme={null} docker login ``` Build and push (replace `your-org`): ```bash theme={null} docker buildx build \ --platform linux/amd64,linux/arm64 \ -t your-org/demo-agent-private:0.1.0 \ -t your-org/demo-agent-private:latest \ --push \ . ``` This takes 5-10 minutes. ### Step 4: Keep Repository Private Docker Hub creates new repositories as **public by default**. Make sure to change it to private. 1. Go to [hub.docker.com](https://hub.docker.com) 2. Open your repository: `your-org/demo-agent-private` 3. Click **Settings** → **Visibility settings** → Change to **Private** → **Save** ### Step 5: Generate Access Token Generate a read-only access token for the platform to pull your private image. Use **read-only tokens with expiration dates** for security. The platform only needs read access to pull images. **For Personal Repositories:** 1. Go to Settings 2. Click **Personal access tokens** 3. Click **Generate new token** 4. Access token description: `AgentSystems Read Access` 5. Set an expiration date (recommended for demos) 6. Access permissions: **Read-only** 7. Click **Generate** 8. **Copy the token** (you won't see it again) **For Organization Repositories:** 1. Go to your organization settings 2. Navigate to **Access tokens** 3. Click **Generate access token** 4. Label: `AgentSystems Image Pull Access` 5. Set an expiration date (recommended for demos) 6. Give the token the Image Pull scope for the necessary repository 7. Click **Generate token** 8. **Copy the token** (you won't see it again) ### Step 6: Add Credentials to Platform Open [localhost:3001/configuration/credentials](http://localhost:3001/configuration/credentials) Add your Docker Hub username: * Click **"Add Credential"** * **Name**: `PRIVATE_DOCKERHUB_USERNAME` * **Value**: Your Docker Hub username or organization * Click **Add Variable** Add your access token: * Click **"Add Credential"** again * **Name**: `PRIVATE_DOCKERHUB_TOKEN` * **Value**: Paste the token from Step 5 * Click **Add Variable** ### Step 7: Create Registry Connection Open [localhost:3001/configuration/registries](http://localhost:3001/configuration/registries) and click **"Add Registry"**: * **Name**: `dockerhub_yourorg_private` (replace `yourorg` with your username/org) * **URL**: `docker.io` * **Authentication Method**: `Basic (Username/Password)` * **Username Environment Variable**: `PRIVATE_DOCKERHUB_USERNAME` * **Password Environment Variable**: `PRIVATE_DOCKERHUB_TOKEN` * **Enabled**: ✓ (checked) Click **Add Registry**. ### Step 8: Add Agent to Platform Open [localhost:3001/configuration/agents](http://localhost:3001/configuration/agents) and click **"Add Agent"**: * **Name**: `demo-agent-private` * **Repository**: `your-org/demo-agent-private` * **Registry**: `dockerhub_yourorg_private` * **Tag**: `latest` * **Egress Allowlist**: Leave blank (no external API calls needed) Click **"Add Agent"**. ### Step 9: Restart and Test Navigate to your AgentSystems deployment directory and restart: ```bash theme={null} cd /path/to/agentsystems agentsystems restart ``` Test it: 1. Go to [localhost:3001/agents](http://localhost:3001/agents) 2. Click on `demo-agent-private` 3. Click **"Turn On"** 4. Click **"Execute"** You should see historical events and a story! ### What You Built Your private agent is deployed: * Uses a **private Docker Hub repository** * Requires credentials to pull and deploy * Runs in a Docker container * Accessible at `http://localhost:18080/invoke/demo-agent-private` ## GitHub Container Registry (GHCR) Coming soon: A guide to deploying private agents using GitHub Container Registry (ghcr.io). ## Harbor Coming soon: A guide to deploying private agents using Harbor registry. # Quickstart Source: https://docs.agentsystems.ai/fortress/deploy-agents/quickstart Deploy your first agent to AgentSystems in under 10 minutes AgentSystems is an **open agent platform** where agents can be **public or private**. This quickstart deploys a public agent - your agent will be available on Docker Hub for others to pull and run. You can also deploy private agents for your organization - see the next steps after completing this guide. ## Prerequisites * AgentSystems platform running ([Installation Guide](/fortress/getting-started/quickstart)) * Docker installed and running * Docker Hub account (free at [hub.docker.com](https://hub.docker.com)) ## Step 1: Get the Template Go to [github.com/agentsystems/agent-template](https://github.com/agentsystems/agent-template) and click **"Use this template"** → **"Create a new repository"**. Name it `demo-agent` and clone it: ```bash theme={null} git clone https://github.com/your-org/demo-agent.git cd demo-agent ``` ## Step 2: Review the Template The template includes a demo agent that: * Accepts a date (e.g., "April 1") * Returns historical events for that date * Creates a story from those events * Uses `gemma3:1b` model This quickstart deploys the template as-is without modification. ## Step 3: Build and Push Docker Hub creates new repositories as **public by default**. Your agent image will be publicly accessible immediately after pushing, allowing anyone to pull and run your agent. Log in to Docker Hub: ```bash theme={null} docker login ``` Build and push (replace `your-org`): ```bash theme={null} docker buildx build \ --platform linux/amd64,linux/arm64 \ -t your-org/demo-agent:0.1.0 \ -t your-org/demo-agent:latest \ --push \ . ``` This takes 5-10 minutes. ## Step 4: Verify Repository Visibility Confirm your repository is public: 1. Go to [hub.docker.com](https://hub.docker.com) 2. Open your repository: `your-org/demo-agent` 3. Check **Settings** → **Visibility settings** shows **Public** If it shows Private, change it to Public and save. ## Step 5: Add Agent to Platform Open [localhost:3001/configuration/agents](http://localhost:3001/configuration/agents): * **Name**: `demo-agent` * **Repository**: `your-org/demo-agent` * **Registry**: `dockerhub_public` * **Tag**: `latest` * **Egress Allowlist**: Leave blank (no external API calls needed) Click **"Add Agent"**. ## Step 6: Restart and Test Navigate to your AgentSystems deployment directory and restart: ```bash theme={null} cd /path/to/agentsystems agentsystems restart ``` Test it: 1. Go to [localhost:3001/agents](http://localhost:3001/agents) 2. Click on `demo-agent` 3. Click **"Turn On"** 4. Click **"Execute"** You should see historical events and a story! ## What You Built Your agent is now deployed on the **open AgentSystems platform**. Your agent: * Uses `gemma3:1b` (local model, no API keys needed) * Accepts a date and returns historical events * Runs in a Docker container * Is accessible at `http://localhost:18080/invoke/demo-agent` * Is publicly available on Docker Hub for others to use ## Next Steps **Deploy a Private Agent**: This quickstart deployed a public agent. To keep your agent private for your organization, see [Deploying Private Agents](/fortress/deploy-agents/private-agents). # Supported Frameworks Source: https://docs.agentsystems.ai/fortress/deploy-agents/supported-frameworks List of agent frameworks supported by AgentSystems # Supported Frameworks Use these frameworks to build agents with `get_model()`: ```python theme={null} from agentsystems_toolkit import get_model model = get_model("claude-sonnet-4", "langchain", temperature=0) ``` ## Currently Supported * **LangChain** - Use with LangChain chains and LangGraph ## Planned Support * OpenAI SDK * Anthropic SDK * LlamaIndex * CrewAI * Google ADK *** **Note:** The framework parameter determines which type of model object is returned. # Supported Models Source: https://docs.agentsystems.ai/fortress/deploy-agents/supported-models List of model IDs supported by AgentSystems # Supported Models Use these model IDs in your agent code with `get_model()`: ```python theme={null} from agentsystems_toolkit import get_model model = get_model("claude-sonnet-4", "langchain", temperature=0) ``` ## Claude (Anthropic) * `claude-opus-4.1` * `claude-opus-4` * `claude-sonnet-4` * `claude-sonnet-3.7` * `claude-3-5-sonnet` * `claude-3-5-haiku` * `claude-haiku-3` ## GPT (OpenAI) * `gpt-5` * `gpt-5-mini` * `gpt-5-nano` * `gpt-4.1` * `gpt-4o` * `gpt-4o-mini` * `gpt-4-turbo` * `o1` * `o1-mini` ## Amazon Nova * `nova-premier` * `nova-pro` * `nova-lite` * `nova-micro` ## Llama (Meta) * `llama3.3:70b` * `llama3.1:8b` * `llama3.2:3b` * `llama3.2:1b` ## Gemma (Google) * `gemma3:4b` * `gemma3:1b` * `gemma2:2b` *** ## Configuration Required **Before using any model in your agent**, the platform operator must configure the model connection in the AgentSystems UI: 1. Navigate to **Configuration → Model Connections** 2. Add the model ID (e.g., `claude-sonnet-4`) 3. Select hosting provider (Anthropic, OpenAI, Bedrock, Ollama) 4. Configure authentication (API keys, AWS credentials, etc.) 5. Enable the connection Agent builders reference the model ID in code, but the actual hosting provider and credentials are configured by whoever runs the AgentSystems platform. # Introduction Source: https://docs.agentsystems.ai/fortress/getting-started/index Self-hosted platform for discovering and running AI agents ## Self-hosted platform for discovering and running AI agents Deploy specialized agents on your infrastructure—without building from scratch or using SaaS. **What is AgentSystems?** A self-hosted platform that combines a federated agent ecosystem, provider portability, and container isolation. Browse community agents, deploy on your infrastructure, and switch between AI providers through configuration. ## Why AgentSystems? Teams want to use specialized AI agents but face a dilemma: * 🔒 **SaaS agents** require sending data to third parties * 🛠️ **Building from scratch** takes weeks of development per agent (most teams lack ML expertise) * 🐳 **Manual Docker orchestration** means configuring networks, volumes, proxies, and API keys for each agent **AgentSystems provides** a standardized runtime and ecosystem: * **Federated Agent Ecosystem**: Git-based agent index where developers publish via GitHub forks * **Provider Portability**: Switch from OpenAI to Anthropic to Ollama through configuration * **Container Isolation**: Each agent runs in its own Docker container with configurable egress filtering * **Audit Trail**: Hash-chained logs for operation tracking ## Key Capabilities Browse and add agents from community indexes Deploy AI agents on your hardware with Docker Use OpenAI, Anthropic, AWS Bedrock, or local models Operation logging to PostgreSQL database ## Use Cases The platform targets scenarios requiring local AI execution: * Processing documents on your infrastructure * Running AI workloads on-premise * Keeping data within your own environment * Testing multiple AI providers * Building containerized AI agents # Key Concepts Source: https://docs.agentsystems.ai/fortress/getting-started/key-concepts How AgentSystems components work together 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) **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) **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`) **PostgreSQL** Persistent storage for: * Execution history * Audit logs with hash-chaining * Agent metadata * Configuration data ## Request Flow User initiates agent execution via UI or SDK CLI Control plane receives request, generates thread ID, and logs to database Gateway locates target agent container via Docker labels (`agent.enabled=true`) Gateway attempts to start the container if needed Gateway forwards request to agent's `/invoke` endpoint with `X-Thread-Id` header Agent processes request using configured AI models and saves outputs to `/artifacts/{thread_id}/out/` 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 | 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 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. # Manual Installation Source: https://docs.agentsystems.ai/fortress/getting-started/manual-installation Step-by-step guide to manually install AgentSystems ## Prerequisites ### 1. Python 3.11 or Higher AgentSystems requires Python 3.11+. Check your version: ```bash theme={null} python3 --version ``` If you need to upgrade, see the [Python downloads page](https://www.python.org/downloads/). ### 2. Docker Docker is required to run AgentSystems containers. * **macOS**: Install [Docker Desktop](https://www.docker.com/products/docker-desktop/) * **Linux**: Follow the [official Docker Engine installation guide](https://docs.docker.com/engine/install/) Verify Docker is running: ```bash theme={null} docker ps ``` ## Installation Steps ### 1. Install pipx Install [pipx](https://pipx.pypa.io/stable/installation/) using your system's package manager or pip: ```bash theme={null} python3 -m pip install --user pipx python3 -m pipx ensurepath ``` Restart your terminal, then verify: ```bash theme={null} pipx --version ``` ### 2. Install agentsystems-sdk ```bash theme={null} pipx install agentsystems-sdk agentsystems --version ``` ## Initialize and Start ```bash theme={null} agentsystems init agent-platform cd agent-platform agentsystems up ``` Open your browser to `http://localhost:3001` # Quick Start Source: https://docs.agentsystems.ai/fortress/getting-started/quickstart Deploy AgentSystems in 5 minutes ## System Requirements AgentSystems requires: * **Python 3.11 or higher** * **Docker** (Docker Desktop on macOS, Docker Engine on Linux) * **Operating System**: macOS or Ubuntu Linux Run the installation script: ```bash theme={null} curl -fsSL https://github.com/agentsystems/agentsystems/releases/latest/download/install.sh | sh ``` Create and enter your deployment directory: ```bash theme={null} agentsystems init my-deployment cd my-deployment ``` The init command prompts for: * Langfuse credentials for observability * Admin credentials for the UI Launch all platform services: ```bash theme={null} agentsystems up ``` This starts: * Agent Control Plane (Gateway) * AgentSystems UI at [http://localhost:3001](http://localhost:3001) * PostgreSQL database Download a small model for local testing: ```bash theme={null} docker exec agentsystems-ollama-1 ollama pull gemma3:1b ``` This downloads a local AI model without needing API keys. Open [http://localhost:3001](http://localhost:3001) in your browser to execute your first local agent. ## Stop the Platform When you're done: ```bash theme={null} agentsystems down ``` # Agent Index Source: https://docs.agentsystems.ai/fortress/user-guide/agent-index Future agent discovery platform The Agent Index is a planned feature for discovering and deploying community agents. The Agent Index is currently in development. This page describes the planned functionality. ## Vision The Agent Index will simplify finding and deploying agents by providing: * Browse available agents * One-click agent deployment * Community contributions # Artifacts Source: https://docs.agentsystems.ai/fortress/user-guide/artifacts Understanding the artifacts system The artifacts system uses separate file storage for each agent execution. Each thread has its own input and output directories. Files are thread-scoped by design; cross-thread access is blocked by platform policy but should not be relied on as a hard security boundary. ## How Artifacts Work Each agent execution gets a unique thread ID and isolated storage Uploaded files are placed in the thread's input directory Agent reads input files and generates output files Results are written to the thread's output directory Download output files via UI, CLI, or API ## File Structure Each thread has this directory layout: ``` artifacts/ └── threads/ └── abc123-def456/ # Thread ID ├── input/ # Input files │ ├── data.csv │ └── config.json └── output/ # Output files ├── results.csv └── report.pdf ``` ## Uploading Input Files ### Via UI In the agent detail page at [http://localhost:3001](http://localhost:3001): 1. Click **Choose Files** 2. Select files to upload 3. Files appear in the input list ## Downloading Output Files ### Via UI Navigate to the execution details to see output files. Click to download. # Audit Logs Source: https://docs.agentsystems.ai/fortress/user-guide/audit-logs Hash-chained audit trail system AgentSystems includes an audit trail feature that uses cryptographic hash chaining for agent executions. Agent executions are logged with cryptographic hashing for audit purposes. ## How It Works The audit system creates a hash-chained log of execution records: System records agent executions automatically Each log entry includes a SHA-256 hash of its contents Each hash includes the previous entry's hash, creating a chain Changes to past entries can be detected via hash verification (for tamper-evidence) ## Viewing Audit Logs ### Via UI Navigate to **Executions** in the AgentSystems UI at [http://localhost:3001](http://localhost:3001). The UI displays: * Execution timeline * Agent details * Request/response data * Hash verification (for tamper-evidence) status * Filter and search options ## Audit Features Can help detect modifications to past logs Cryptographic hashing (for tamper-evidence) of execution history Records chronological sequence of events Uses SHA-256 hashing for verification (tamper-evidence) # CLI Commands Source: https://docs.agentsystems.ai/fortress/user-guide/cli-commands SDK command reference The AgentSystems SDK includes command-line tools for managing your platform deployment. The `agentsystems` CLI includes platform management commands. ## Platform Management ### Lifecycle Control the platform lifecycle with these commands: ```bash theme={null} # Start all services agentsystems up # Start in detached mode (default) agentsystems up --detach # Start with fresh containers agentsystems up --fresh # Start without Langfuse tracing agentsystems up --no-langfuse ``` The platform starts at: * UI: [http://localhost:3001](http://localhost:3001) * Gateway: [http://localhost:18080](http://localhost:18080) ```bash theme={null} # Stop all services agentsystems down # Stop and remove volumes agentsystems down --volumes ``` ```bash theme={null} # Quick restart agentsystems restart # Restart with fresh volumes agentsystems restart --volumes ``` ### Monitoring Check platform status and view logs: ```bash theme={null} # Show all container status agentsystems status # Check specific service agentsystems status --service gateway ``` ```bash theme={null} # Stream all logs agentsystems logs # View gateway logs agentsystems logs --service gateway # Tail last 100 lines agentsystems logs --tail 100 # Follow log output agentsystems logs --follow ``` ## Running Agents Execute agents with JSON payloads and optional file uploads: ```bash theme={null} agentsystems run hello-world-agent '{"date": "October 15, 1979"}' ``` ```bash theme={null} agentsystems run my-agent '{"format": "csv"}' \ --input-file data.csv ``` ## Artifact Management Access input and output files from agent executions: ```bash theme={null} # Get output directory for a thread agentsystems artifacts-path abc123-def456 # Get specific output file path agentsystems artifacts-path abc123-def456 result.json # Get input directory agentsystems artifacts-path abc123-def456 --input # Get specific input file agentsystems artifacts-path abc123-def456 data.csv --input ``` ## System Maintenance Manage platform resources and updates: ```bash theme={null} # Nuclear cleanup agentsystems clean # Skip Docker prune agentsystems clean --no-prune-system ``` Removes all containers, volumes, and optionally prunes Docker. ```bash theme={null} # Update core images agentsystems update ``` Pulls latest versions of platform components. ## Command Reference ### Platform Commands | Command | Description | | ----------------------------- | ------------------------- | | `agentsystems init [DIR]` | Initialize new deployment | | `agentsystems up` | Start platform services | | `agentsystems down` | Stop platform services | | `agentsystems restart` | Restart platform | | `agentsystems logs` | View service logs | | `agentsystems status` | Check service status | | `agentsystems run` | Execute an agent | | `agentsystems artifacts-path` | Get artifact file paths | | `agentsystems clean` | Deep clean system | | `agentsystems update` | Update platform images | | `agentsystems version` | Show SDK version | | `agentsystems info` | Show diagnostics | ## Command Alias For convenience, a shorter alias is available: * `agntsys` → `agentsystems` ## Getting Help All commands support `--help` to display detailed usage information, available options, and examples: ```bash theme={null} # Show all available commands and global options agentsystems --help # Show options for running agents (payloads, file uploads, polling) agentsystems run --help # Show options for viewing logs (filtering, following, tail) agentsystems logs --help ``` # Running Agents Source: https://docs.agentsystems.ai/fortress/user-guide/running-agents Execute agents via UI or CLI Agents process requests with JSON payloads and optional file uploads. You can run them through the UI or CLI. ## Running via UI Navigate to **Agents** in the AgentSystems UI at [http://localhost:3001](http://localhost:3001). Browse available agents and click **Turn On** on your chosen agent (agents auto-start if invoked while off) * Enter JSON payload in the request editor * Upload input files if needed * Review agent requirements Click **Execute** to start execution Watch real-time progress updates and logs Download output files when complete ## Running via CLI Use the SDK CLI to run agents programmatically. See [CLI Commands](/fortress/user-guide/cli-commands) for details. ## Request Structure Every agent request includes: JSON object with agent-specific parameters: ```json theme={null} { "action": "analyze", "format": "csv", "options": { "verbose": true } } ``` Upload files for processing: * Via UI: Drag & drop or browse * Via CLI: Use `--input-file` flag * Multiple files supported * All common formats accepted Unique identifier for the execution: * Auto-generated if not provided * Used to track progress * Required for accessing artifacts ## Response Handling Agents return structured responses: ```json theme={null} { "thread_id": "abc123-def456", "status": "completed", "progress": 100, "messages": [ { "type": "result", "content": "Analysis complete" } ], "artifacts": [ "output/results.csv", "output/report.pdf" ] } ``` ### Status Values | Status | Description | | ------------- | ---------------- | | `pending` | Request queued | | `in_progress` | Agent processing | | `completed` | Success | | `failed` | Error occurred | ## Accessing Output Files After execution, download output files through the UI execution details page. ## Progress Tracking Agents provide real-time progress updates in the UI. ## Error Handling When agents fail, error details appear in the UI execution log. # Troubleshooting Source: https://docs.agentsystems.ai/fortress/user-guide/troubleshooting Common issues and solutions ## Quick Fix Most issues can be resolved by restarting the platform: ```bash theme={null} agentsystems restart ``` This command stops and restarts all AgentSystems services, which often resolves: * Connection issues * Stuck agents * UI not updating * Configuration not applying ## Still Having Issues? If restarting doesn't help: 1. Check logs: `agentsystems logs` 2. Review status: `agentsystems status` 3. Report issues: [GitHub Issues](https://github.com/agentsystems/agentsystems/issues) # AgentSystems Source: https://docs.agentsystems.ai/index Infrastructure for AI agents Audit trail infrastructure for AI agent operations. Dual-write architecture stores hashes to a shared ledger and raw logs to your own storage. Self-hosted platform for discovering and running AI agents. Deploy containerized agents on your infrastructure with provider portability and audit logging. # Hash Storage Source: https://docs.agentsystems.ai/notary/configuration/hash-storage Configure where cryptographic hashes are stored Hash storage is where the SHA-256 hashes of your audit payloads are written. Only hashes and metadata are stored externally — raw data stays in your infrastructure. You can use one or both options. ## Decentralized (Arweave) Hashes are written to a public, append-only ledger. Not controlled by any single vendor. ```python theme={null} from agentsystems_notary import ArweaveHashStorage, LocalKeySignerConfig arweave_storage = ArweaveHashStorage( namespace="tenant_a1b2c3d4", # anonymous tenant identifier signer=LocalKeySignerConfig( private_key_path="/path/to/arweave-key.pem", ), # bundler_url defaults to ArDrive Turbo ) ``` ### Parameters | Parameter | Required | Description | | ------------- | -------- | --------------------------------------------------------------------------------- | | `namespace` | Yes | Anonymous tenant identifier (written to public ledger — do not use company names) | | `signer` | Yes | Signing configuration (see [Signers](/notary/configuration/signing)) | | `bundler_url` | No | Arweave bundler endpoint (defaults to ArDrive Turbo) | ### Verification Verify with the open-source CLI — no account required: ```bash theme={null} npm install -g agentsystems-verify agentsystems-verify --logs logs.zip ``` See [Independent Verification](/notary/verification/arweave) for full documentation. ## Custodied (AgentSystems) Hashes are written to AgentSystems' write-once compliance storage. Provides a vendor relationship for enterprise compliance and procurement. ```python theme={null} from agentsystems_notary import CustodiedHashStorage custodied_storage = CustodiedHashStorage( api_key="sk_asn_prod_...", slug="customer-123", ) ``` ### Parameters | Parameter | Required | Description | | --------- | -------- | --------------------------------------------------------- | | `api_key` | Yes | AgentSystems API key (`sk_asn_test_*` or `sk_asn_prod_*`) | | `slug` | Yes | Tenant slug (human-readable identifier) | | `api_url` | No | API endpoint (defaults to production) | ### Get an API Key 1. Sign up at [notary.agentsystems.ai](https://notary.agentsystems.ai) 2. From the Dashboard, click **Add** under API Keys 3. Name your key and select environment 4. Copy and save the key — it's only shown once ### Verification Verify via the [Verify UI](https://verify.agentsystems.ai) or see [Verification Guide](/notary/verification/guide). ## Using Both You can write hashes to both Arweave and custodied storage: ```python theme={null} notary = LangChainNotary( raw_payload_storage=raw_payload_storage, hash_storage=[ ArweaveHashStorage(...), CustodiedHashStorage(...), ], ) ``` This provides independent verification via Arweave plus a vendor relationship via AgentSystems. # Raw Payload Storage Source: https://docs.agentsystems.ai/notary/configuration/raw-payload-storage Configure where full audit payloads are stored Raw payload storage is where the full JSON payload of every LLM interaction is written. This is your storage — you maintain full control. ## AWS S3 ```python theme={null} from agentsystems_notary import RawPayloadStorage, AwsS3StorageConfig raw_payload_storage = RawPayloadStorage( storage=AwsS3StorageConfig( bucket_name="acme-corp-audit-logs", aws_access_key_id="AKIA...", aws_secret_access_key="...", aws_region="us-east-1", # default ), ) ``` ### Required IAM Permissions ```json theme={null} { "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": ["s3:PutObject", "s3:GetObject", "s3:ListBucket"], "Resource": [ "arn:aws:s3:::acme-corp-audit-logs", "arn:aws:s3:::acme-corp-audit-logs/*" ] }] } ``` ## GCP Cloud Storage Coming soon ```python theme={null} from agentsystems_notary import RawPayloadStorage, GcpCloudStorageConfig raw_payload_storage = RawPayloadStorage( storage=GcpCloudStorageConfig( bucket_name="acme-corp-audit-logs", credentials_path="/path/to/service-account.json", # optional, uses ADC if not provided ), ) ``` ## Azure Blob Storage Coming soon ```python theme={null} from agentsystems_notary import RawPayloadStorage, AzureBlobStorageConfig raw_payload_storage = RawPayloadStorage( storage=AzureBlobStorageConfig( container_url="https://acme.blob.core.windows.net", container_name="audit-logs", ), ) ``` ## Storage Path Structure Payloads are stored with the following path structure: ``` {env}/{namespace}/{YYYY}/{MM}/{DD}/{hash}.json ``` * `env`: `arweave`, `prod`, or `test` * `namespace`: Your tenant identifier * `hash`: SHA-256 hash of the canonical payload # Signers Source: https://docs.agentsystems.ai/notary/configuration/signing Configure signing for Arweave hash storage Signers are used to cryptographically sign data items before uploading to Arweave. All signers use RSA-4096 keys with PSS padding. ## Local Key For development and testing. Generate a key with: ```bash theme={null} openssl genrsa -out arweave-key.pem 4096 ``` ```python theme={null} from agentsystems_notary import LocalKeySignerConfig # From file path signer = LocalKeySignerConfig( private_key_path="/path/to/arweave-key.pem", ) # Or from environment variable signer = LocalKeySignerConfig( private_key_env_var="ARWEAVE_PRIVATE_KEY", ) ``` Local keys are for development and testing only. Use a cloud key management service in production. ## AWS KMS ```python theme={null} from agentsystems_notary import AwsKmsSignerConfig signer = AwsKmsSignerConfig( kms_key_arn="arn:aws:kms:us-east-1:123456789:key/abcd-1234-...", aws_access_key_id="AKIA...", aws_secret_access_key="...", aws_region="us-east-1", # default ) ``` ### KMS Key Requirements Create an asymmetric RSA-4096 key with: * Key spec: `RSA_4096` * Key usage: `SIGN_VERIFY` * Signing algorithm: `RSASSA_PSS_SHA_256` ### Required IAM Permissions ```json theme={null} { "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": ["kms:Sign", "kms:GetPublicKey"], "Resource": "arn:aws:kms:us-east-1:123456789:key/abcd-1234-..." }] } ``` ## GCP Cloud KMS Coming soon ```python theme={null} from agentsystems_notary import GcpKmsSignerConfig signer = GcpKmsSignerConfig( key_resource_name="projects/.../locations/.../keyRings/.../cryptoKeys/.../cryptoKeyVersions/...", credentials_path="/path/to/service-account.json", # optional, uses ADC if not provided ) ``` ## Azure Key Vault Coming soon ```python theme={null} from agentsystems_notary import AzureKeyVaultSignerConfig signer = AzureKeyVaultSignerConfig( vault_url="https://acme-vault.vault.azure.net", key_name="arweave-signing-key", key_version="abc123", # optional, uses latest if not provided ) ``` # Introduction Source: https://docs.agentsystems.ai/notary/getting-started/index Third-party attestation for AI agent operations AgentSystems Notary provides independent verification of your AI system's behavior. When buyers ask "how do we trust your AI logs?", you have an answer. ## How It Works 1. **Record** - The SDK captures LLM interactions as they happen 2. **Dual-Write** - Raw logs go to your S3 bucket. SHA-256 hashes go to your chosen storage. 3. **Verify** - Anyone with an audit ticket can verify logs ## Hash Storage Options Notary supports two hash storage methods. You can use one or both. | Option | Description | Verification | | --------- | ---------------------------------- | ----------------------------------------------------------------------------- | | Arweave | Hashes stored on public blockchain | [Independent verification](/notary/verification/arweave) with open-source CLI | | Custodied | Hashes stored by AgentSystems API | Via [portal](https://verify.agentsystems.ai) | **Arweave** provides decentralized, permanent storage on a public blockchain. Verification requires no AgentSystems infrastructure — anyone can verify using the open-source `agentsystems-verify` CLI. No vendor lock-in. **Custodied** is a managed option if you prefer AgentSystems to handle the complexity. Verify through our portal. ## Components | Component | URL | Purpose | | ------------------- | -------------------------------------------------------- | ----------------------------------------------------- | | Dashboard | [notary.agentsystems.ai](https://notary.agentsystems.ai) | View tenants, manage API keys, generate audit tickets | | Verification Portal | [verify.agentsystems.ai](https://verify.agentsystems.ai) | Verify logs and download attestation packets | | SDK | [PyPI](https://pypi.org/project/agentsystems-notary/) | Python SDK for LangChain and CrewAI | | Verify CLI | [npm](https://www.npmjs.com/package/agentsystems-verify) | Open-source CLI for Arweave verification | ## Key Concepts **Tenants** represent your customers. They're auto-discovered when the SDK logs its first interaction with a given slug. You don't need to create them in advance. **Audit Tickets** are signed tokens that grant access to verify logs for a specific tenant and date range. They don't contain the hashes themselves — they authorize the verification portal to check logs against AgentSystems records. **Attestation Packets** are self-contained proof bundles you can share with customers, compliance teams, or regulators. They contain the logs, audit ticket, a signed attestation certificate, and instructions for independent signature verification — everything needed to confirm the logs were checked against AgentSystems records. End-to-end tutorial: signup → integration → verification # Quickstart Source: https://docs.agentsystems.ai/notary/getting-started/quickstart Add independently verifiable audit logging to your AI agents ## 1. Set Up Your S3 Bucket The SDK writes raw logs directly to your S3 bucket — you maintain full control. 1. Create an S3 bucket (names are globally unique, so include your company name — e.g., `acme-corp-raw-ai-logs`) 2. Create the following IAM policy: ```json theme={null} { "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": ["s3:PutObject", "s3:GetObject", "s3:ListBucket"], "Resource": [ "arn:aws:s3:::acme-corp-raw-ai-logs", "arn:aws:s3:::acme-corp-raw-ai-logs/*" ] }] } ``` 3. Create an IAM user and attach the policy 4. Generate access keys for the user (select "Application running outside AWS") and save them ## 2. Install the SDK ```bash theme={null} mkdir notary-demo && cd notary-demo python3 -m venv .venv source .venv/bin/activate pip install agentsystems-notary langchain-anthropic python-dotenv ``` ```bash theme={null} mkdir notary-demo && cd notary-demo python3 -m venv .venv source .venv/bin/activate pip install agentsystems-notary crewai python-dotenv ``` ## 3. Configure Environment Create a `.env` file: ```bash theme={null} # AWS credentials for your S3 bucket ORG_AWS_S3_BUCKET_NAME=acme-corp-raw-ai-logs ORG_AWS_S3_ACCESS_KEY_ID=... ORG_AWS_S3_SECRET_ACCESS_KEY=... ORG_AWS_S3_REGION=us-east-1 # Arweave hash storage ARWEAVE_BUNDLER_URL=https://node2.bundlr.network ARWEAVE_PRIVATE_KEY_PATH=path/to/rsa-4096-private.pem # Your LLM provider ANTHROPIC_API_KEY=... ``` ## 4. Integrate the SDK Create `test_langchain.py`: ```python theme={null} import os from dotenv import load_dotenv from agentsystems_notary import ( LangChainNotary, RawPayloadStorage, ArweaveHashStorage, LocalKeySignerConfig, AwsS3StorageConfig, ) from langchain_anthropic import ChatAnthropic load_dotenv() # Where full audit payloads are stored (your S3 bucket) raw_payload_storage = RawPayloadStorage( storage=AwsS3StorageConfig( bucket_name=os.environ["ORG_AWS_S3_BUCKET_NAME"], aws_access_key_id=os.environ["ORG_AWS_S3_ACCESS_KEY_ID"], aws_secret_access_key=os.environ["ORG_AWS_S3_SECRET_ACCESS_KEY"], aws_region=os.environ["ORG_AWS_S3_REGION"], ), ) # Where hashes are stored — Arweave for independent verification hash_storage = [ ArweaveHashStorage( namespace="my_namespace", signer=LocalKeySignerConfig( private_key_path=os.environ["ARWEAVE_PRIVATE_KEY_PATH"], ), bundler_url=os.environ["ARWEAVE_BUNDLER_URL"], ), ] # Initialize notary notary = LangChainNotary( raw_payload_storage=raw_payload_storage, hash_storage=hash_storage, debug=True, ) # Add to any LangChain model model = ChatAnthropic( model="claude-sonnet-4-5-20250929", api_key=os.environ["ANTHROPIC_API_KEY"], callbacks=[notary], ) # All LLM calls are now logged response = model.invoke("What is 2 + 2?") print(response.content) ``` Run it: ```bash theme={null} python test_langchain.py ``` Create `test_crewai.py`: ```python theme={null} import os from dotenv import load_dotenv from agentsystems_notary import ( CrewAINotary, RawPayloadStorage, ArweaveHashStorage, LocalKeySignerConfig, AwsS3StorageConfig, ) from crewai import Agent, Task, Crew, LLM load_dotenv() # Where full audit payloads are stored (your S3 bucket) raw_payload_storage = RawPayloadStorage( storage=AwsS3StorageConfig( bucket_name=os.environ["ORG_AWS_S3_BUCKET_NAME"], aws_access_key_id=os.environ["ORG_AWS_S3_ACCESS_KEY_ID"], aws_secret_access_key=os.environ["ORG_AWS_S3_SECRET_ACCESS_KEY"], aws_region=os.environ["ORG_AWS_S3_REGION"], ), ) # Where hashes are stored — Arweave for independent verification hash_storage = [ ArweaveHashStorage( namespace="my_namespace", signer=LocalKeySignerConfig( private_key_path=os.environ["ARWEAVE_PRIVATE_KEY_PATH"], ), bundler_url=os.environ["ARWEAVE_BUNDLER_URL"], ), ] # Initialize notary (hooks register automatically) notary = CrewAINotary( raw_payload_storage=raw_payload_storage, hash_storage=hash_storage, debug=True, ) # Create LLM llm = LLM( model="anthropic/claude-sonnet-4-5-20250929", api_key=os.environ["ANTHROPIC_API_KEY"], ) # Create agent and task agent = Agent( role="Research Analyst", goal="Answer questions accurately", backstory="You are an expert analyst.", llm=llm, ) task = Task( description="What is 2 + 2?", expected_output="The answer to the math question", agent=agent, ) crew = Crew(agents=[agent], tasks=[task]) # All LLM calls are now logged result = crew.kickoff() print(result) ``` Run it: ```bash theme={null} python test_crewai.py ``` With `debug=True`, you'll see confirmation that the log was written to S3 and the hash was uploaded to Arweave. ## 5. Verify Anyone can verify your logs using the open-source CLI — no account required: ```bash theme={null} npm install -g agentsystems-verify ``` ```bash theme={null} agentsystems-verify \ --namespace my_namespace \ --start 2026-01-01 \ --end 2026-01-31 \ --logs logs.zip ``` See [Independent Verification](/notary/verification/arweave) for full CLI documentation. ## Signer Options The examples above use a local RSA-4096 private key. You can also use managed key services: * `LocalKeySignerConfig` — Local RSA-4096 private key (PEM file or env var) * `AwsKmsSignerConfig` — AWS KMS managed key * `GcpKmsSignerConfig` — GCP Cloud KMS managed key * `AzureKeyVaultSignerConfig` — Azure Key Vault managed key *** ## Using Custodied Storage (Optional) If you prefer AgentSystems to manage hash storage, you can use our custodied option instead of (or in addition to) Arweave. ### Create Account Go to [notary.agentsystems.ai](https://notary.agentsystems.ai) and sign up. ### Generate an API Key 1. From the Dashboard, click **Add** under API Keys 2. Name your key and select environment 3. Copy and save the key — it's only shown once ### Add to Environment ```bash theme={null} AGENTSYSTEMS_NOTARY_API_KEY=sk_asn_test_... ``` ### Add Custodied Hash Storage ```python theme={null} from agentsystems_notary import CustodiedHashStorage hash_storage = [ ArweaveHashStorage(...), # Keep Arweave for independent verification CustodiedHashStorage( api_key=os.environ["AGENTSYSTEMS_NOTARY_API_KEY"], slug="customer-123", ), ] ``` ### Verify via Portal 1. Go to [notary.agentsystems.ai](https://notary.agentsystems.ai) → Tenants → Generate Verification Ticket 2. Export logs from your S3 bucket 3. Upload both to [verify.agentsystems.ai](https://verify.agentsystems.ai) See [Verification Guide](/notary/verification/guide) for full portal documentation. # Independent Verification Source: https://docs.agentsystems.ai/notary/verification/arweave Verify Arweave-notarized logs with open-source tooling ## Overview For logs notarized to the Arweave blockchain, you can verify them independently using our open-source verification tool. This approach: * Requires no API keys or AgentSystems infrastructure * Is fully open-source and auditable * Queries the public Arweave network directly ## Prerequisites * Logs exported from your S3 bucket (ZIP file) * Verification ticket (generated from notary dashboard or your records) ## Installation ```bash theme={null} npm install -g agentsystems-verify ``` ## CLI Usage ### With a ticket file ```bash theme={null} agentsystems-verify --ticket ticket.json --logs logs.zip ``` ### With CLI flags ```bash theme={null} agentsystems-verify \ --owner \ --namespace my_namespace \ --start 2026-01-01 \ --end 2026-01-31 \ --logs logs.zip ``` ### Interactive mode ```bash theme={null} agentsystems-verify --logs logs.zip # Prompts for missing values ``` ## Understanding Results | Result | Meaning | | ----------- | -------------------------------------- | | Verified | Found in ZIP and on Arweave blockchain | | Unnotarized | In ZIP but not on Arweave | | Missing | On Arweave but not in ZIP | ## Library Usage (JavaScript/TypeScript) ```typescript theme={null} import { verify, validateTicket } from "agentsystems-verify"; import { readFileSync } from "fs"; const ticket = validateTicket(JSON.parse(readFileSync("ticket.json", "utf-8"))); const zipBuffer = readFileSync("logs.zip"); const results = await verify(ticket, zipBuffer, { onProgress: (msg) => console.log(msg), }); console.log(`Verified: ${results.verified.length}`); console.log(`Unnotarized: ${results.unnotarized.length}`); console.log(`Missing: ${results.missing.length}`); ``` ## How It Works 1. Extracts JSON files from the ZIP archive 2. Canonicalizes and hashes each file (SHA-256) 3. Queries Arweave blockchain for matching transactions 4. Compares local hashes against blockchain records ## Source Code [github.com/agentsystems/agentsystems-verify](https://github.com/agentsystems/agentsystems-verify) # Verification Source: https://docs.agentsystems.ai/notary/verification/guide How to verify log integrity This guide covers verification for custodied hash storage (AgentSystems API). For Arweave (decentralized) verification, see [Independent Verification](/notary/verification/arweave). Verification compares logs against AgentSystems records to identify any discrepancies. Anyone with an audit ticket can verify — your customers, their compliance teams, or third-party reviewers. ## What You Need | Item | How to Get It | | ---------------- | ---------------------------------------------------------------------------------------- | | **Audit Ticket** | Generate from [notary.agentsystems.ai](https://notary.agentsystems.ai) → Tenants → Audit | | **Logs ZIP** | Export from your S3 bucket (commands shown in the Audit modal) | The audit ticket is a signed token that grants access to check logs against AgentSystems records for a specific tenant and date range. ## Running Verification 1. Go to [verify.agentsystems.ai](https://verify.agentsystems.ai) 2. Upload the audit ticket (`.json`) 3. Upload the logs (`.zip`) 4. Click **Start Verification** No account is required to run verification. ## Understanding Results | Result | Meaning | | ------------------------ | -------------------------------------------------------- | | **Verified Records** | Records in the ZIP that match AgentSystems records | | **Unrecognized Records** | Records in the ZIP that weren't recorded by AgentSystems | | **Missing Records** | Records that AgentSystems recorded but aren't in the ZIP | ## Attestation Packets After verification, download an attestation packet — a self-contained proof bundle you can share with customers, compliance teams, or regulators. Recipients can verify the cryptographic signature themselves without needing to re-run verification or trust your word. ## Verifying the Signature The attestation certificate is signed with AgentSystems' notary key. To verify independently: ```bash theme={null} # Download the public key curl -o notary.pem https://verify-api.agentsystems.ai/.well-known/notary.pem # Verify the signature openssl dgst -sha256 -verify notary.pem -signature attestation.pdf.sig attestation.pdf ``` Expected output: `Verified OK`