agently

Agently

Agently is a Go framework for building and interacting with AI agents. It provides a flexible and extensible platform for creating, managing, and communicating with AI agents powered by Large Language Models (LLMs).

Features

• Agent-based Architecture: Create and manage AI agents with different capabilities and personalities
• Multi-LLM Support: Integrate with various LLM providers including OpenAI, Vertex AI, Bedrock, and more
• Conversation Management: Maintain conversation history and context across interactions
• Tool Integration: Extend agent capabilities with custom tools
• Embeddings: Support for text embeddings for semantic search and retrieval
• CLI Interface: Interact with agents through a command-line interface
• HTTP Server: Deploy agents as web services
• Workflow Engine: Built on Viant's Fluxor workflow engine for orchestrating complex agent tasks

Installation

Prerequisites

• Go 1.23.8 or higher

Installing

go get github.com/viant/agently

Quick Start

# Set your OpenAI API key
export OPENAI_API_KEY=your_key

# Clone the repository
git clone https://github.com/viant/agently.git
cd agently/agently

# Set the Agently root directory (defaults to ~/.agently if not set)
export AGENTLY_ROOT=./agently_workspace

# Create the directory
mkdir -p $AGENTLY_ROOT

# Build the application
go build -o agently .

# Check available commands
./agently -h

# Start a chat session
./agently chat

How to run MCP server

To run the MCP (Model Control Protocol) server with SQLKit support:

# Clone the MCP SQLKit repository
git clone https://github.com/viant/mcp-sqlkit.git

# Navigate to the project directory
cd mcp-sqlkit

# Start the MCP server on port 5000
go run ./cmd/mcp-sqlkit -a :5000

The server will be available at http://localhost:5000 and can be used with Agently for database operations.

Quick Start with MCP server and sqlkit tool

This guide will help you set up Agently with the MCP server and SQLKit tool for database operations.

Prerequisites

• Complete the Quick Start steps above to set up Agently
• Have a MySQL server running (this example uses a local MySQL server)

Step 1: Configure the MCP Server

1. First, ensure both Agently and any running MCP servers are stopped.

2. Create the MCP configuration file:

# Create the mcp directory if it doesn't exist
mkdir -p $AGENTLY_ROOT/mcp

# Create the SQLKit configuration file
cat > $AGENTLY_ROOT/mcp/sqlkit.yaml << EOF
name: sqlkit
version: ""
protocol: ""
namespace: ""
transport:
    type: sse
    command: ""
    arguments: []
    url: http://localhost:5000
auth: null
EOF

Step 2: Configure the Agent to Use SQLKit

Update your agent configuration to include the SQLKit tool:

# Create or update the chat agent configuration
mkdir -p $AGENTLY_ROOT/agents
cat > $AGENTLY_ROOT/agents/chat.yaml << EOF
description: Default conversational agent
id: chat
modelRef: openai_o4-mini
name: Chat
orchestrationFlow: workflow/orchestration.yaml
temperature: 0
tool:
  - pattern: system/exec
  - pattern: sqlkit
knowledge:
  - url: knowledge/
EOF

Step 3: Start the Services

1. Start the MCP server with SQLKit (follow the "How to run MCP server" steps above)
2. Start Agently (run ./agently chat)

Step 4: Test Database Connectivity

Ensure your MySQL server is running. For this example, we assume:

port: 3306
user: root
password: dev
database: my_db

Step 5: Query Your Database

Send a query to test the database connection:

> tell how many tables do we have in my_db db?

A configuration wizard will guide you through setting up the MySQL connector:

1. When prompted for connector name, enter: dev

2. For driver, enter: mysql

3. For host, enter: localhost

4. For connector name, accept the default: dev

5. For port, enter your MySQL port (e.g., 3306)

6. For project, just press Enter to skip (not needed for MySQL)

7. For DB/Dataset, enter: my_db

8. For flowURI:

   8.1 open given link in browser and submit user and password (e.g., root and dev)

   8.2 enter any value or accept the default

After configuration, Agently will execute your query and return the result, such as:

There are 340 base tables in the my_db schema when accessed via the dev connector.

You can now use natural language to query your database through Agently!

Usage

For the current status and plan of the Domain/DAO unification, see docs/domain-unification.md.

Recorder (domain write facade)

• The domain write surface is exposed as internal/domain/recorder (Recorder).
• Recorder composes smaller, focused interfaces:
  • Enablement: Enabled() mode gate (off|shadow|full via AGENTLY_DOMAIN_MODE).
  • MessageRecorder: RecordMessage(...).
  • TurnRecorder: RecordTurnStart(...), RecordTurnUpdate(...).
  • ModelCallRecorder: RecordModelCall(...) – accepts DAO write modelcall/write.ModelCall fields (via helper), creates payloads, persists, and passes payload IDs.
  • ToolCallRecorder: RecordToolCall(...) – same pattern for tools.
  • UsageRecorder: RecordUsageTotals(...).
• Exec uses the aggregated Recorder; narrower interfaces can be used where only one facet is needed.

Operations (DAO-first)

• Low-level operations persistence and reads live under internal/domain/adapter/operations.
• Write signatures accept DAO write structs and payload IDs:
  • RecordModelCall(ctx, *modelcall/write.ModelCall, requestPayloadID, responsePayloadID string)
  • RecordToolCall(ctx, *toolcall/write.ToolCall, requestPayloadID, responsePayloadID string)
• Reads are exposed in v2 HTTP as DAO read views (see below).

HTTP v2 quick examples (DAO views)

List transcript (message rows with embedded model/tool where present):

curl -s "http://localhost:8080/v2/api/agently/conversation/CONV_ID/transcript?includeModelCalls=1&includeToolCalls=1&payloadLevel=preview" | jq

List operations grouped by kind (message):

curl -s "http://localhost:8080/v2/api/agently/messages/MESSAGE_ID/operations" | jq
# {
#   "status": "ok",
#   "data": {
#     "modelCalls": [ { ... ModelCallView ... } ],
#     "toolCalls":  [ { ... ToolCallView  ... } ]
#   }
# }

List operations grouped by kind (turn):

curl -s "http://localhost:8080/v2/api/agently/turns/TURN_ID/operations" | jq

Notes:

• Model and tool call views include finishReason, latency_ms, and optional cost.
• Tool call views include status and error_message when available.
• Payload snapshots are fetched via /v2/api/agently/payload/{id}; transcript returns payload/read.PayloadView with preview/inline based on query options.

Configuration (environment variables)

• AGENTLY_DOMAIN_MODE: controls domain persistence integration

  • off (default): legacy in-memory only; no domain writes
  • shadow: write to domain (DAO) and keep legacy reads
  • full: reserved for future (Phase 2+); read/write via domain

• AGENTLY_V1_DOMAIN: v1 compatibility layer for reads

  • 1: v1 endpoints (e.g., /v1/api/conversations/{id}/messages) read from domain store when available
  • (unset): v1 endpoints read from in-memory history

• AGENTLY_DB_DRIVER and AGENTLY_DB_DSN: enable SQL-backed v2 API

  • When both are set, the server builds a datly connector named agently and wires a SQL-backed domain store for /v2/api/agently/... endpoints.
  • Examples:
    • SQLite: AGENTLY_DB_DRIVER=sqlite, AGENTLY_DB_DSN=file:/path/to/db.sqlite?cache=shared
    • Postgres: AGENTLY_DB_DRIVER=postgres, AGENTLY_DB_DSN=postgres://user:pass@host:5432/db?sslmode=disable
  • When unset, v2 defaults to an in-memory DAO store.

• AGENTLY_REDACT_KEYS: comma-separated list of JSON keys to scrub from request/response payload snapshots before persistence

  • Default: api_key,apikey,authorization,auth,password,passwd,secret,token,bearer,client_secret
  • Example: AGENTLY_REDACT_KEYS=apiKey,Authorization,password

• AGENTLY_POLICY: default tool policy for the server

  • auto (default), ask, deny

Note: When shadow mode is enabled, the system writes to the domain store (DAO) but continues to read from legacy in-memory endpoints unless AGENTLY_V1_DOMAIN=1 is set or v2 endpoints are used.

Command Line Interface

Agently provides a command-line interface for interacting with agents:

# Chat with an agent
agently chat 

# Chat with an agent with a specific query
agently chat -l <agent-location> -q "Your query here"

# Continue a conversation
agently chat -l <agent-location> -c <conversation-id>

# List existing conversations
agently list

# Manage MCP servers
agently mcp list                         # view configured servers
agently mcp add   -n local -t stdio \
  --command "my-mcp" --arg "--flag"
agently mcp add   -n cloud -t sse   --url https://mcp.example.com/sse
agently mcp remove -n local

# List available tools (names & descriptions)
agently list-tools

# Show full JSON definition for a tool
agently list-tools -n system/exec.execute --json

# Run an agentic workflow from JSON input
agently run -i <input-file>

# Start HTTP server
agently serve

# Workspace management (new)

Agently stores all editable resources under **`$AGENTLY_ROOT`** (defaults to
`~/.agently`).  Each kind has its own sub-folder:

~/.agently/ agents/ # *.yaml agent definitions models/ # LLM or embedder configs workflows/ # Fluxor workflow graphs mcp/ # MCP client definitions

Use the generic `ws` command group to list, add or remove any resource kind:

```bash
# List agents
agently ws list   -k agent

# Add a model from file
agently ws add    -k model   -n gpt4o -f gpt4o.yaml

# Get raw YAML for workflow
agently ws get    -k workflow -n plan_exec_finish

# Delete MCP server definition
agently ws remove -k mcp -n local

Clearing agents cache

1. Close all running agents.
2. Delete content of ~/.emb

Model convenience helpers

# Switch default model for an agent
agently model-switch -a chat -m gpt4o

# Reset agent to inherit executor default
agently model-reset  -a chat

MCP helpers (now stored in workspace)

# Add/update server definition (stored as ~/.agently/mcp/local.yaml)
agently mcp add    -n local -t stdio --command my-mcp

# List names or full JSON objects (with --json)
agently mcp list   [--json]

# Remove definition
agently mcp remove -n local

### Options

### Templated agent queries (velty)

Agently supports rendering prompts with the velty template engine so you can
compose rich queries from structured inputs.

Where you can use templates:
- Agent workflow run (Fluxor): llm/agent:run input accepts queryTemplate in
  addition to query. The template is rendered with variables:
  - Prompt – the original query string
  - everything from context – each key becomes a template variable

Example (Fluxor task):

action: llm/agent:run input: agentName: designer query: "Initial feature brief" queryTemplate: | Design this feature based on:\n Brief: ${Prompt}\n Product: ${productName}\n Constraints: ${constraints} context: productName: "Acme WebApp" constraints: "Ship MVP in 2 sprints"

In addition, the core generation service uses the same unified templating for
Template (with ${Prompt}) and SystemTemplate (with ${SystemPrompt}) together
with any values placed in Bind.

- `-f, --config`: Executor config YAML/JSON path
- `-l, --location`: Agent definition path
- `-q, --query`: User query
- `-c, --conv`: Conversation ID (optional)
- `-p, --policy`: Tool policy: auto|ask|deny (default: auto)
- `-t, --timeout`: Timeout in seconds for the agent response (0=none)
- `--log`: Unified log (LLM, TOOL, TASK) (default: agently.log)

#### mcp list / add / remove

- `mcp list` — lists configured servers. `--json` to output full objects.

- `mcp add` flags:
  - `-n, --name`  – unique identifier
  - `-t, --type`  – transport: `stdio`, `sse`, or `streaming`
  - `--command`   – stdio command (when `-t stdio`)
  - `--arg`       – repeatable extra arguments for stdio (when `-t stdio`)
  - `--url`       – HTTP endpoint (when `-t sse|streaming`)

- `mcp remove` flags:
  - `-n, --name`  – identifier to delete

#### list-tools

- `-n, --name` – Tool name (`service/method`) to display full schema
- `--json` – Print tool definitions in JSON (applies to single or all tools)

#### exec

- `-n, --name` – Tool name to execute
- `-i, --input` – Inline JSON arguments (object)
- `-f, --file` – Path to JSON file with arguments (use `-` for STDIN)
- `--timeout` – Seconds to wait for completion (default 120)
- `--json` – Print result as JSON

Example (properly quoted for Bash/Zsh):

```bash
./agently exec -n system/exec.execute \
  -i '{"commands":["echo '\''hello'\''"]}'

Development

Project Structure

• cmd/agently: Command-line interface
• genai/agent: Agent-related functionality
• genai/conversation: Conversation management
• genai/embedder: Text embedding functionality
• genai/executor: Executes agent tasks or workflows
• genai/extension: Extensions or plugins
• genai/llm: Large Language Model integration
• genai/memory: Conversation memory or history
• genai/tool: Tools or utilities for agents

Further documentation

For an in-depth walkthrough of how Agently processes a request – from the CLI invocation through agent resolution, planning, LLM call and response – see docs/agent_flow.md. The document also explains the $AGENTLY_ROOT workspace mechanism introduced in the 2025-06 release.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

This product includes software developed at Viant (http://viantinc.com/).