Skip to content

Installation

This guide covers installing the Akordi Agents SDK and setting up your development environment.

Prerequisites

  • Python 3.12 installed
  • Poetry or uv for dependency management
  • AWS credentials configured for Bedrock access

Installation Methods

Poetry

1. Add the GitLab package source

Add the following to your pyproject.toml:

[[tool.poetry.source]]
name = "gitlab-agents"
url = "https://gitlab.com/api/v4/projects/79863696/packages/pypi/simple"
priority = "primary"

2. Add the dependency

[tool.poetry.dependencies]
akordi-agents = "0.0.35"

Or add it via the CLI:

poetry add akordi-agents==0.0.35 --source gitlab-agents

3. Install

poetry install

Full example pyproject.toml

[tool.poetry]
name = "my-agent-project"
version = "0.1.0"
description = ""
authors = ["Your Name <you@example.com>"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.12"
akordi-agents = "0.0.35"

[[tool.poetry.source]]
name = "gitlab-agents"
url = "https://gitlab.com/api/v4/projects/79863696/packages/pypi/simple"
priority = "primary"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

uv

1. Add the GitLab index

Add the following to your pyproject.toml:

[[tool.uv.index]]
name = "gitlab-agents"
url = "https://gitlab.com/api/v4/projects/79863696/packages/pypi/simple"

2. Pin the package to the GitLab index

[tool.uv.sources]
akordi-agents = { index = "gitlab-agents" }

3. Add the dependency

[project]
dependencies = [
    "akordi-agents==0.0.35",
]

Or add it via the CLI:

uv add akordi-agents==0.0.35 --index gitlab-agents

4. Install

uv sync

Full example pyproject.toml (uv)

[project]
name = "my-agent-project"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "akordi-agents==0.0.35",
]

[[tool.uv.index]]
name = "gitlab-agents"
url = "https://gitlab.com/api/v4/projects/79863696/packages/pypi/simple"

[tool.uv.sources]
akordi-agents = { index = "gitlab-agents" }

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Environment Variables

Create a .env file with your configuration:

# AWS Configuration
AWS_REGION=ap-southeast-2
AWS_DEFAULT_REGION=ap-southeast-2

# Chat History (DynamoDB)
CHAT_SESSIONS_TABLE_NAME=your-sessions-table
CHAT_MESSAGES_TABLE_NAME=your-messages-table

# Token Usage Tracking (Optional)
AKORDI_TOKEN_USAGE_TABLE=your-token-usage-table

# Guardrails (Optional)
GUARDRAIL_ID=your-guardrail-id
GUARDRAIL_VERSION=1

# LangSmith Tracing (Optional)
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your-langsmith-key
LANGCHAIN_PROJECT=your-project-name

Verifying Installation

Test your installation:

import akordi_agents

print(f"Akordi Agents SDK v{akordi_agents.__version__}")

from akordi_agents.core import AgentBuilder, create_langgraph_agent
from akordi_agents.services import AWSBedrockService
from akordi_agents.tools import Tool

print("All components imported successfully!")

Optional Dependencies

For Development

poetry install --with dev

This includes:

  • pytest - Testing framework
  • pytest-cov - Coverage reporting
  • black - Code formatting
  • isort - Import sorting
  • flake8 - Linting
  • mypy - Type checking

For Documentation

pip install mkdocs-material mkdocstrings[python]

Troubleshooting

Import Errors

If you get import errors:

  1. Verify the package is installed: 

    pip show akordi-agents

  2. Check Python version: 

    python --version  # Should be 3.12+

  3. Ensure virtual environment is activated: 

    poetry shell

AWS Bedrock Access

If you get Bedrock access errors:

  1. Verify your IAM role has Bedrock permissions
  2. Check the model is available in your region
  3. Request model access in the AWS console if needed

Next Steps