Docs: Pallas agents
This commit is contained in:
254
docs/iolaus.md
Normal file
254
docs/iolaus.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# iolaus
|
||||
|
||||
Personal agents for Daedalus — powered by [Pallas](https://git.helu.ca/r/pallas).
|
||||
|
||||
Iolaus is a pure agent project: Python agent definitions + YAML configuration.
|
||||
The runtime (serving, registry, health checks, multimodal support) lives in Pallas.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Daedalus Backend — FastAPI
|
||||
│ MCP over StreamableHTTP
|
||||
▼
|
||||
Pallas MCP Bridge (pallas.server:main)
|
||||
│ reads agents.yaml for topology
|
||||
│ reads fastagent.config.yaml for LLM + model capabilities
|
||||
│
|
||||
├── Registry → /.well-known/mcp/server.json (agent discovery)
|
||||
├── Shawn → kairos, neo4j_cypher, argos, research, time
|
||||
├── Watson → argos, neo4j_cypher, time
|
||||
├── Cristiano → nike, neo4j_cypher, time
|
||||
├── Nate → periplus, argos, neo4j_cypher, time
|
||||
├── David → orpheus, argos, neo4j_cypher, research, time
|
||||
├── Research → argos, neo4j_cypher
|
||||
├── Tech Research → context7, github, argos
|
||||
└── Mikael → argos, time (news briefings; reads `news:` config)
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
.
|
||||
├── agents.yaml # Deployment topology — agents, ports, host, namespace
|
||||
├── fastagent.config.yaml # LLM provider, MCP servers, model capabilities (committed)
|
||||
├── fastagent.secrets.yaml # API keys and tokens (gitignored — never commit)
|
||||
├── agents/ # Agent definitions (FastAgent @fast.agent decorators)
|
||||
│ ├── shawn.py
|
||||
│ ├── watson.py
|
||||
│ ├── cristiano.py
|
||||
│ ├── nate.py
|
||||
│ ├── david.py
|
||||
│ ├── research.py
|
||||
│ └── tech_research.py
|
||||
├── systemd/
|
||||
│ └── iolaus.service
|
||||
├── pyproject.toml
|
||||
└── .env.example
|
||||
```
|
||||
|
||||
## Agents
|
||||
|
||||
| Agent | Port | MCP URL | Purpose |
|
||||
|-------|------|---------|---------|
|
||||
| Shawn | 24001 | `http://puck.incus:24001/mcp` | Personal general assistant — calendar, contacts, email, and daily life |
|
||||
| Watson | 24005 | `http://puck.incus:24005/mcp` | Relationship memory & emotional safety — reflection, values, habits, emotional experiences, dialogue notes |
|
||||
| Cristiano | 24006 | `http://puck.incus:24006/mcp` | Football analyst — live data, match tracking, tactics |
|
||||
| Nate | 24007 | `http://puck.incus:24007/mcp` | Travel and adventure companion — trip planning, navigation |
|
||||
| David | 24008 | `http://puck.incus:24008/mcp` | Arts & culture — music, film, art, fashion, and Kawai piano |
|
||||
| Infrastructure | 24050 | `http://puck.incus:24050/mcp` | Shell, git, and Grafana router |
|
||||
| Research | 24051 | `http://puck.incus:24051/mcp` | Web search + knowledge graph chain |
|
||||
| Tech Research | 24052 | `http://puck.incus:24052/mcp` | Technical investigation — library docs, code examples, API comparisons |
|
||||
| Mikael | 24053 | `http://puck.incus:24053/mcp` | News briefings — topic-driven, source-verified, image-rich |
|
||||
| Registry | 24000 | `http://puck.incus:24000/.well-known/mcp/server.json` | Agent discovery |
|
||||
|
||||
## Configuration
|
||||
|
||||
### `agents.yaml` — Deployment Topology
|
||||
|
||||
Single source of truth for agent names, ports, dependencies, host, and namespace.
|
||||
Read by Pallas at startup.
|
||||
|
||||
```yaml
|
||||
name: iolaus
|
||||
version: "1.0.0"
|
||||
host: puck.incus
|
||||
namespace: ca.helu.iolaus
|
||||
registry_port: 24000
|
||||
|
||||
agents:
|
||||
shawn:
|
||||
module: agents.shawn
|
||||
port: 24001
|
||||
title: Shawn
|
||||
description: "Personal general assistant — calendar, contacts, email, and daily life management"
|
||||
depends_on: [research]
|
||||
# ...
|
||||
```
|
||||
|
||||
To deploy a different agent group, swap `agents.yaml` — no code changes needed.
|
||||
Override the config path with `PALLAS_AGENTS_CONFIG` env var.
|
||||
|
||||
### `fastagent.config.yaml` — LLM + Model Capabilities
|
||||
|
||||
Committed to the repo. Contains LLM provider settings and explicit model capability
|
||||
declarations.
|
||||
|
||||
```yaml
|
||||
default_model: openai.Qwen3.5-35B-A3B-UD-Q4_K_XL.gguf
|
||||
|
||||
model_capabilities:
|
||||
vision: false
|
||||
context_window: 40960
|
||||
max_output_tokens: 8192
|
||||
```
|
||||
|
||||
The `model_capabilities` section declares capabilities explicitly rather than
|
||||
inferring from the model name. Exposed in the registry for Daedalus to use when
|
||||
routing requests.
|
||||
|
||||
### `news:` — Mikael News Agent Configuration
|
||||
|
||||
Top-level block in `fastagent.config.yaml`, consumed by `agents/mikael.py` at
|
||||
startup. Edits take effect on restart — no code changes needed to tweak
|
||||
topics or sources.
|
||||
|
||||
```yaml
|
||||
news:
|
||||
topics:
|
||||
- Canadian federal politics
|
||||
- Generative AI and LLM research
|
||||
# ... add/remove freely
|
||||
preferred_sources: # seeded into queries, not exclusive
|
||||
- reuters.com
|
||||
- apnews.com
|
||||
- cbc.ca
|
||||
avoided_sources: # excluded via -site: AND post-filtered by host
|
||||
- foxnews.com
|
||||
- breitbart.com
|
||||
- dailymail.co.uk
|
||||
default_lookback_hours: 24
|
||||
max_items_per_topic: 5
|
||||
```
|
||||
|
||||
Mikael excludes `avoided_sources` from search results with `-site:` operators
|
||||
*and* post-filters by hostname as a second line of defence. It will never
|
||||
summarize or cite content from an avoided source, even if another outlet
|
||||
syndicates the claim.
|
||||
|
||||
### `fastagent.secrets.yaml` — API Keys and Tokens
|
||||
|
||||
Gitignored — never commit. Place in the repo root alongside `fastagent.config.yaml`.
|
||||
|
||||
```yaml
|
||||
openai:
|
||||
api_key: "your-key-here"
|
||||
|
||||
mcp:
|
||||
servers:
|
||||
angelia:
|
||||
headers:
|
||||
Authorization: "Bearer your-token"
|
||||
kairos:
|
||||
headers:
|
||||
Authorization: "Bearer your-token"
|
||||
periplus:
|
||||
headers:
|
||||
Authorization: "Bearer your-token"
|
||||
nike:
|
||||
headers:
|
||||
Authorization: "Bearer your-token"
|
||||
# ...
|
||||
```
|
||||
|
||||
## Quickstart
|
||||
|
||||
```bash
|
||||
# 1. Install dependencies (Python 3.13 required)
|
||||
source ~/env/iolaus/bin/activate
|
||||
pip install -e .
|
||||
|
||||
# 2. Configure secrets
|
||||
cp fastagent.secrets.yaml.example fastagent.secrets.yaml
|
||||
# Edit: set api_key and service tokens
|
||||
|
||||
# 3. Start all agents
|
||||
iolaus
|
||||
|
||||
# 4. Verify
|
||||
curl http://localhost:24001/mcp
|
||||
|
||||
# 5. Start a single agent
|
||||
iolaus --agent shawn
|
||||
```
|
||||
|
||||
## Daedalus Integration
|
||||
|
||||
Daedalus connects to agents via the MCP Python SDK's `streamable_http_client`.
|
||||
|
||||
Registry endpoint: `http://puck.incus:24000/.well-known/mcp/server.json`
|
||||
|
||||
The registry includes model capabilities on each agent entry:
|
||||
|
||||
```json
|
||||
{
|
||||
"capabilities": {
|
||||
"model": "Qwen3.5-35B-A3B-UD-Q4_K_XL.gguf",
|
||||
"vision": false,
|
||||
"context_window": 40960,
|
||||
"max_output_tokens": 8192
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Deployment (systemd)
|
||||
|
||||
```bash
|
||||
# 1. Copy project to /srv/iolaus
|
||||
sudo cp -r . /srv/iolaus
|
||||
sudo chown -R iolaus:iolaus /srv/iolaus
|
||||
|
||||
# 2. Install into venv
|
||||
cd /srv/iolaus
|
||||
source ~/env/iolaus/bin/activate
|
||||
pip install -e .
|
||||
|
||||
# 3. Configure secrets
|
||||
cp fastagent.secrets.yaml.example fastagent.secrets.yaml
|
||||
# Fill in API keys and tokens
|
||||
|
||||
# 4. Install and start systemd service
|
||||
sudo cp systemd/iolaus.service /etc/systemd/system/
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now iolaus
|
||||
sudo systemctl status iolaus
|
||||
```
|
||||
|
||||
## Downstream MCP Servers
|
||||
|
||||
| Server | Host | URL |
|
||||
|--------|------|-----|
|
||||
| argos | miranda.incus | `http://miranda.incus:25534/mcp` |
|
||||
| neo4j_cypher | circe.helu.ca | `http://circe.helu.ca:22034/mcp` |
|
||||
| kernos | caliban.incus | `http://caliban.incus:22021/mcp` |
|
||||
| rommie | caliban.incus | `http://caliban.incus:22031/mcp` |
|
||||
| gitea | miranda.incus | `http://miranda.incus:25535/mcp` |
|
||||
| grafana | miranda.incus | `http://miranda.incus:25533/mcp` |
|
||||
| korax | korax.helu.ca | `http://korax.helu.ca:22021/mcp` |
|
||||
| orpheus | orpheus.helu.ca | `https://orpheus.helu.ca/mcp` |
|
||||
| angelia | ouranos.helu.ca | `https://ouranos.helu.ca/mcp/` |
|
||||
| kairos | ouranos.helu.ca | `https://kairos.ouranos.helu.ca/mcp/` |
|
||||
| periplus | ouranos.helu.ca | `https://periplus.ouranos.helu.ca/mcp/` |
|
||||
| nike | ouranos.helu.ca | `https://nike.ouranos.helu.ca/mcp/` |
|
||||
| github | local (Docker stdio) | `ghcr.io/github/github-mcp-server` |
|
||||
| context7 | local (stdio) | `npx -y @upstash/context7-mcp` |
|
||||
| time | local (stdio) | `mcp-server-time` |
|
||||
|
||||
## Notes
|
||||
|
||||
- **Python 3.13** required (`fast-agent-mcp` pins `>=3.13`)
|
||||
- **Runtime:** [Pallas](https://git.helu.ca/r/pallas) — `pallas-mcp @ git+ssh://git@git.helu.ca:22022/r/pallas.git`
|
||||
- **Transport:** StreamableHTTP (`/mcp`) throughout — not SSE
|
||||
- **LLM:** OpenAI-compatible API at `http://nyx.helu.ca:22079/v1` (personal Qwen model)
|
||||
- **Logging:** Console output — stdout → syslog → Alloy → Loki in production
|
||||
- **Port scheme:** registry at 24000, personal agents 24001–24049, sub-agents 24050–24099
|
||||
189
docs/kottos.md
Normal file
189
docs/kottos.md
Normal file
@@ -0,0 +1,189 @@
|
||||
# kottos
|
||||
|
||||
Engineering agents for Daedalus — powered by [Pallas](https://git.helu.ca/r/pallas).
|
||||
|
||||
Kottos is a pure agent project: Python agent definitions + YAML configuration.
|
||||
The runtime (serving, registry, health checks, multimodal support) lives in Pallas.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Daedalus Backend — FastAPI
|
||||
│ MCP over StreamableHTTP
|
||||
▼
|
||||
Pallas MCP Bridge (pallas.server:main)
|
||||
│ reads agents.yaml for topology
|
||||
│ reads fastagent.config.yaml for LLM + model capabilities
|
||||
│
|
||||
├── Registry → /.well-known/mcp/server.json (agent discovery)
|
||||
├── Harper → kernos_harper, gitea, argos, neo4j_cypher, grafana,
|
||||
│ rommie, angelia, time, research, tech_research
|
||||
├── Scotty → kernos_scotty, argos, tech_research, neo4j_cypher, grafana, time
|
||||
├── Research → argos, neo4j_cypher
|
||||
└── Tech Research → context7, github, argos
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
.
|
||||
├── agents.yaml # Deployment topology — agents, ports, host, namespace
|
||||
├── fastagent.config.yaml # LLM provider, MCP servers, model capabilities (committed)
|
||||
├── fastagent.secrets.yaml # API keys and tokens (gitignored — never commit)
|
||||
├── fastagent.secrets.yaml.example
|
||||
├── agents/ # Agent definitions (FastAgent @fast.agent decorators)
|
||||
│ ├── harper.py
|
||||
│ ├── scotty.py
|
||||
│ ├── research.py
|
||||
│ └── tech_research.py
|
||||
├── docs/
|
||||
│ └── pallas_integration.md
|
||||
├── pyproject.toml
|
||||
└── LICENSE
|
||||
```
|
||||
|
||||
## Agents
|
||||
|
||||
| Agent | Port | MCP URL | Purpose |
|
||||
|-------|------|---------|---------|
|
||||
| Harper | 24101 | `http://puck.incus:24101/mcp` | Scrappy engineer — rapid prototyping, hacking, and creative problem-solving |
|
||||
| Scotty | 24102 | `http://puck.incus:24102/mcp` | Systems administration — infrastructure diagnostics and security hardening |
|
||||
| Research | 24150 | `http://puck.incus:24150/mcp` | Web search + knowledge graph chain |
|
||||
| Tech Research | 24151 | `http://puck.incus:24151/mcp` | Technical investigation — library docs, code examples, API comparisons |
|
||||
| Registry | 24100 | `http://puck.incus:24100/.well-known/mcp/server.json` | Agent discovery |
|
||||
|
||||
## Configuration
|
||||
|
||||
### `agents.yaml` — Deployment Topology
|
||||
|
||||
Single source of truth for agent names, ports, dependencies, host, and namespace.
|
||||
Read by Pallas at startup.
|
||||
|
||||
```yaml
|
||||
name: kottos
|
||||
version: "1.0.0"
|
||||
host: puck.incus
|
||||
namespace: ca.helu.kottos
|
||||
registry_port: 24100
|
||||
|
||||
agents:
|
||||
harper:
|
||||
module: agents.harper
|
||||
port: 24101
|
||||
title: Harper
|
||||
description: "Scrappy engineer — rapid prototyping, hacking, and creative problem-solving"
|
||||
depends_on: [research, tech_research]
|
||||
# ...
|
||||
```
|
||||
|
||||
To deploy a different agent group, swap `agents.yaml` — no code changes needed.
|
||||
Override the config path with `PALLAS_AGENTS_CONFIG` env var.
|
||||
|
||||
### `fastagent.config.yaml` — LLM + Model Capabilities
|
||||
|
||||
Committed to the repo. Contains LLM provider settings and explicit model capability
|
||||
declarations.
|
||||
|
||||
In Ansible-managed deployments this file is replaced by the
|
||||
`fastagent.config.yaml.j2` template which renders environment-specific values
|
||||
for model, MCP URLs, etc.
|
||||
|
||||
```yaml
|
||||
default_model: openai.Qwen3.5-35B-A3B-UD-Q4_K_XL.gguf
|
||||
|
||||
model_capabilities:
|
||||
vision: false
|
||||
context_window: 192000
|
||||
max_output_tokens: 16384
|
||||
```
|
||||
|
||||
The `model_capabilities` section declares capabilities explicitly rather than
|
||||
inferring from the model name. Exposed in the registry for Daedalus to use when
|
||||
routing requests.
|
||||
|
||||
### `fastagent.secrets.yaml` — API Keys and Tokens
|
||||
|
||||
Gitignored — never commit. Place in the repo root alongside `fastagent.config.yaml`.
|
||||
|
||||
In Ansible-managed deployments this file is replaced by the
|
||||
`fastagent.secrets.yaml.j2` template which renders secrets from OCI Vault.
|
||||
|
||||
```yaml
|
||||
openai:
|
||||
api_key: "your-key-here"
|
||||
|
||||
mcp:
|
||||
servers:
|
||||
angelia:
|
||||
headers:
|
||||
Authorization: "Bearer your-token"
|
||||
github:
|
||||
env:
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN: "your-token"
|
||||
# ...
|
||||
```
|
||||
|
||||
## Quickstart
|
||||
|
||||
```bash
|
||||
# 1. Install dependencies (Python 3.13 required)
|
||||
source ~/env/kottos/bin/activate
|
||||
pip install -e .
|
||||
|
||||
# 2. Configure secrets
|
||||
cp fastagent.secrets.yaml.example fastagent.secrets.yaml
|
||||
# Edit: set api_key and service tokens
|
||||
|
||||
# 3. Start all agents
|
||||
kottos
|
||||
|
||||
# 4. Verify
|
||||
curl http://localhost:24101/mcp
|
||||
|
||||
# 5. Start a single agent
|
||||
kottos --agent harper
|
||||
```
|
||||
|
||||
## Daedalus Integration
|
||||
|
||||
Daedalus connects to agents via the MCP Python SDK's `streamable_http_client`.
|
||||
|
||||
Registry endpoint: `http://puck.incus:24100/.well-known/mcp/server.json`
|
||||
|
||||
The registry includes model capabilities on each agent entry:
|
||||
|
||||
```json
|
||||
{
|
||||
"capabilities": {
|
||||
"model": "Qwen3.5-35B-A3B-UD-Q4_K_XL.gguf",
|
||||
"vision": false,
|
||||
"context_window": 192000,
|
||||
"max_output_tokens": 16384
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Downstream MCP Servers
|
||||
|
||||
| Server | Host | URL |
|
||||
|--------|------|-----|
|
||||
| argos | miranda.incus | `http://miranda.incus:25534/mcp` |
|
||||
| neo4j_cypher | circe.helu.ca | `http://circe.helu.ca:22034/mcp` |
|
||||
| caliban | caliban.incus | `http://caliban.incus:22062/mcp` |
|
||||
| rommie | caliban.incus | `http://caliban.incus:22061/mcp` |
|
||||
| gitea | miranda.incus | `http://miranda.incus:25535/mcp` |
|
||||
| grafana | miranda.incus | `http://miranda.incus:25533/mcp` |
|
||||
| korax | korax.helu.ca | `http://korax.helu.ca:20261/mcp` |
|
||||
| angelia | ouranos.helu.ca | `https://ouranos.helu.ca/mcp/` |
|
||||
| github | local (Docker stdio) | `ghcr.io/github/github-mcp-server` |
|
||||
| context7 | local (stdio) | `npx -y @upstash/context7-mcp` |
|
||||
| time | local (stdio) | `mcp-server-time` |
|
||||
|
||||
## Notes
|
||||
|
||||
- **Python 3.13** required (`fast-agent-mcp` pins `>=3.13`)
|
||||
- **Runtime:** [Pallas](https://git.helu.ca/r/pallas) — `pallas-mcp @ git+ssh://git@git.helu.ca:22022/r/pallas.git`
|
||||
- **Transport:** StreamableHTTP (`/mcp`) throughout — not SSE
|
||||
- **LLM:** OpenAI-compatible API at `http://nyx.helu.ca:22079/v1` (personal Qwen model)
|
||||
- **Logging:** Console output — stdout → syslog → Alloy → Loki in production
|
||||
- **Port scheme:** registry at 24100, agents 24101–24149, sub-agents 24150–24199
|
||||
218
docs/mentor.md
Normal file
218
docs/mentor.md
Normal file
@@ -0,0 +1,218 @@
|
||||
# mentor
|
||||
|
||||
Work agents for Daedalus — powered by [Pallas](https://git.helu.ca/r/pallas).
|
||||
|
||||
Mentor is a pure agent project: Python agent definitions + YAML configuration.
|
||||
The runtime (serving, registry, health checks, multimodal support) lives in Pallas.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Daedalus Backend — FastAPI
|
||||
│ MCP over StreamableHTTP
|
||||
▼
|
||||
Pallas MCP Bridge (pallas.server:main)
|
||||
│ reads agents.yaml for topology
|
||||
│ reads fastagent.config.yaml for LLM + model capabilities
|
||||
│
|
||||
├── Registry → /.well-known/mcp/server.json (agent discovery)
|
||||
├── Jarvis → kernos, rommie, argos, neo4j_cypher, athena, time
|
||||
├── Jeffrey → neo4j_cypher, athena, research, time
|
||||
├── Ann → research, argos, neo4j_cypher, athena, angelia, time
|
||||
├── Alan → research, argos, athena, neo4j_cypher, time
|
||||
├── AWS SA → aws_knowledge, aws_docs, aws_pricing, argos, context7
|
||||
├── Research → argos, neo4j_cypher
|
||||
└── Tech Research → context7, github, argos
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
.
|
||||
├── agents.yaml # Deployment topology — agents, ports, host, namespace
|
||||
├── fastagent.config.yaml # LLM provider, MCP servers, model capabilities (committed)
|
||||
├── fastagent.secrets.yaml # API keys and tokens (gitignored — never commit)
|
||||
├── agents/ # Agent definitions (FastAgent @fast.agent decorators)
|
||||
│ ├── jarvis.py
|
||||
│ ├── jeffrey.py
|
||||
│ ├── ann.py
|
||||
│ ├── alan.py
|
||||
│ ├── aws_sa.py
|
||||
│ ├── research.py
|
||||
│ └── tech_research.py
|
||||
├── systemd/
|
||||
│ └── mentor.service
|
||||
├── pyproject.toml
|
||||
└── .env.example
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### `agents.yaml` — Deployment Topology
|
||||
|
||||
Single source of truth for agent names, ports, dependencies, host, and namespace.
|
||||
Read by Pallas at startup.
|
||||
|
||||
```yaml
|
||||
name: mentor
|
||||
version: "1.0.0"
|
||||
host: puck.incus
|
||||
namespace: ca.helu.mentor
|
||||
registry_port: 24200
|
||||
|
||||
agents:
|
||||
jarvis:
|
||||
module: agents.jarvis
|
||||
port: 24201
|
||||
title: Jarvis
|
||||
description: "Work execution assistant — task management, meetings, daily operations"
|
||||
depends_on: [research]
|
||||
# ...
|
||||
```
|
||||
|
||||
To deploy a different agent group, swap `agents.yaml` — no code changes needed.
|
||||
Override the config path with `PALLAS_AGENTS_CONFIG` env var.
|
||||
|
||||
### `fastagent.config.yaml` — LLM + Model Capabilities
|
||||
|
||||
Committed to the repo. Contains LLM provider settings and explicit model capability
|
||||
declarations.
|
||||
|
||||
```yaml
|
||||
default_model: openai.global.anthropic.claude-opus-4-6-v1
|
||||
|
||||
model_capabilities:
|
||||
vision: false
|
||||
context_window: 200000
|
||||
max_output_tokens: 32000
|
||||
```
|
||||
|
||||
The `model_capabilities` section declares capabilities explicitly rather than
|
||||
inferring from the model name. Exposed in the registry for Daedalus to use when
|
||||
routing requests (e.g., vision-capable agents).
|
||||
|
||||
### `fastagent.secrets.yaml` — API Keys and Tokens
|
||||
|
||||
Gitignored — never commit. Place in the repo root alongside `fastagent.config.yaml`.
|
||||
|
||||
```yaml
|
||||
openai:
|
||||
api_key: "your-key-here"
|
||||
|
||||
mcp:
|
||||
servers:
|
||||
angelia:
|
||||
headers:
|
||||
Authorization: "Bearer your-token"
|
||||
# ...
|
||||
```
|
||||
|
||||
## Quickstart
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- **Python 3.13+** (`fast-agent-mcp` pins `>=3.13`)
|
||||
- **Node.js / npm** — for the `context7` stdio MCP server (`npx -y @upstash/context7-mcp`)
|
||||
- **Docker** — for the `github` stdio MCP server
|
||||
- **`uv` / `uvx`** at `/usr/local/bin/uvx` — required by the `aws_docs` and
|
||||
`aws_pricing` stdio MCP servers. fast-agent's stdio client sanitizes `PATH`
|
||||
before spawning subprocesses (via `mcp.client.stdio.get_default_environment()`),
|
||||
so `fastagent.config.yaml` references `uvx` by absolute path. Install
|
||||
system-wide — this matches the Ansible production deploy
|
||||
(`virgo/ansible/mentor/deploy.yml`) so dev and prod configs are identical:
|
||||
|
||||
```bash
|
||||
sudo sh -c 'curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR=/usr/local/bin sh'
|
||||
```
|
||||
|
||||
Do **not** use the default per-user install (`~/.local/bin/uvx`) — the config
|
||||
will not find it at runtime under systemd or under pallas' sanitized PATH.
|
||||
|
||||
```bash
|
||||
# 1. Install dependencies (Python 3.13 required)
|
||||
source ~/env/mentor/bin/activate
|
||||
pip install -e .
|
||||
|
||||
# 2. Configure secrets
|
||||
cp fastagent.secrets.yaml.example fastagent.secrets.yaml
|
||||
# Edit: set api_key and service tokens
|
||||
|
||||
# 3. Start all agents
|
||||
mentor
|
||||
|
||||
# 4. Verify
|
||||
curl http://localhost:24201/mcp
|
||||
|
||||
# 5. Start a single agent
|
||||
mentor --agent jarvis
|
||||
```
|
||||
|
||||
## Daedalus Integration
|
||||
|
||||
Daedalus connects to agents via the MCP Python SDK's `streamable_http_client`.
|
||||
|
||||
Registry endpoint: `http://<host>:<registry_port>/.well-known/mcp/server.json`
|
||||
|
||||
The registry includes model capabilities on each agent entry:
|
||||
|
||||
```json
|
||||
{
|
||||
"capabilities": {
|
||||
"model": "global.anthropic.claude-opus-4-6-v1",
|
||||
"vision": false,
|
||||
"context_window": 200000,
|
||||
"max_output_tokens": 32000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Deployment (systemd)
|
||||
|
||||
```bash
|
||||
# 1. Copy project to /srv/mentor
|
||||
sudo cp -r . /srv/mentor
|
||||
sudo chown -R mentor:mentor /srv/mentor
|
||||
|
||||
# 2. Install into venv
|
||||
cd /srv/mentor
|
||||
source ~/env/mentor/bin/activate
|
||||
pip install -e .
|
||||
|
||||
# 3. Configure secrets
|
||||
cp fastagent.secrets.yaml.example fastagent.secrets.yaml
|
||||
# Fill in API keys and tokens
|
||||
|
||||
# 4. Install and start systemd service
|
||||
sudo cp systemd/mentor.service /etc/systemd/system/
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now mentor
|
||||
sudo systemctl status mentor
|
||||
```
|
||||
|
||||
## Downstream MCP Servers
|
||||
|
||||
| Server | Host | URL |
|
||||
|--------|------|-----|
|
||||
| argos | miranda.incus | `http://miranda.incus:25534/mcp` |
|
||||
| neo4j_cypher | circe.helu.ca | `http://circe.helu.ca:22034/mcp` |
|
||||
| kernos | caliban.incus | `http://caliban.incus:22021/mcp` |
|
||||
| rommie | caliban.incus | `http://caliban.incus:22031/mcp` |
|
||||
| gitea | miranda.incus | `http://miranda.incus:25535/mcp` |
|
||||
| grafana | miranda.incus | `http://miranda.incus:25533/mcp` |
|
||||
| angelia | ouranos.helu.ca | `https://ouranos.helu.ca/mcp/` |
|
||||
| athena | ouranos.helu.ca | `https://athena.ouranos.helu.ca/mcp/` |
|
||||
| kairos | ouranos.helu.ca | `https://kairos.ouranos.helu.ca/mcp/` |
|
||||
| github | local (Docker stdio) | `ghcr.io/github/github-mcp-server` |
|
||||
| context7 | local (stdio) | `npx -y @upstash/context7-mcp` |
|
||||
| time | local (stdio) | `mcp-server-time` |
|
||||
| aws_knowledge | knowledge-mcp.global.api.aws | `https://knowledge-mcp.global.api.aws` |
|
||||
| aws_docs | local (stdio) | `uvx awslabs.aws-documentation-mcp-server@latest` |
|
||||
| aws_pricing | local (stdio) | `uvx awslabs.aws-pricing-mcp-server@latest` |
|
||||
|
||||
## Notes
|
||||
|
||||
- **Python 3.13** required (`fast-agent-mcp` pins `>=3.13`)
|
||||
- **Runtime:** [Pallas](https://git.helu.ca/r/pallas) — `pallas-mcp @ git+ssh://git@git.helu.ca:22022/r/pallas.git`
|
||||
- **Transport:** StreamableHTTP (`/mcp`) throughout — not SSE
|
||||
- **Logging:** Console output — stdout → syslog → Alloy → Loki in production
|
||||
- **Port scheme:** registry at `registry_port`, agents at configured ports in `agents.yaml`
|
||||
Reference in New Issue
Block a user