domyn-agents

Build AI agents in Python or YAML, run them on any model, and work with them from the terminal.

Documentation · Examples · Contributing

Domyn Agents is a powerful and extensible agent harness. It works with any model, from Domyn's, to other OSS models running in vLLM, or closed model providers. Domyn Agents is provided with an extensive cli for setup and configuration.

Domyn Agents also allows to build your own agents. Define them with the Python library or a YAML config, give them tools, let them hand work to each other, and require a person's approval for any tool that should not run unsupervised. domyn run runs the agents you build too.

Installation

Domyn Agents is published on PyPI as part of domyn (the GitHub repository is domyn-agents).

For the terminal agent, install the domyn command. On macOS (Apple Silicon) and Linux, the installer brings its own Python:

curl -fsSL https://github.com/domynai/domyn-agents/releases/latest/download/install.sh | sh

or install it with uv, on Python 3.11 or later:

uv tool install "domyn[cli]"

To install the development version from the repository instead, use uv tool install "domyn[cli] @ git+https://github.com/domynai/domyn-agents".

To build agents in a Python project (Python 3.11 or later), add it as a dependency:

uv add domyn

With pip, run pip install "domyn[cli]". Agents import from domyn.agents (from domyn.agents import Agent, Runner). Optional extras add integrations: tracing (OpenTelemetry), langchain, langgraph, slack, telegram and audio (local speech to text).

Getting started

Start it in the directory you want to work on:

domyn run

The first time, a setup wizard asks for a provider, a model and an API key, and saves them under ~/.domyn/. Then you chat with the agent. It can read the files in this directory freely, and it asks for your approval before it writes a file or runs a command: once, for the rest of the conversation, in this project, or always.

Conversations are saved, and domyn run --resume picks one up where you left it. Type /help in a session to see its commands. See Interactive sessions.

To build your own agents, in Python or in YAML, see the documentation or the examples.

Features

• Any model: vLLM, OpenAI, Anthropic, Cerebras, OpenRouter or any OpenAI-compatible endpoint, with native tool calling or a prompt-based protocol for endpoints without it.
• Tools: Python functions, streaming tools, remote MCP servers, and built-in file and shell tools confined to a workspace.
• Multi-agent: agents hand work to each other, with control over what each one sees and whom it can call. Remote agents take part like local ones.
• Human in the loop: a tool can wait for approval, remembered for one call, a conversation or longer, and rules or hooks can decide some calls on their own.
• Skills: teach agents reusable know-how with SKILL.md files, loaded only when a task needs them.
• Standing instructions: SOUL.md and AGENTS.md files that shape every conversation.
• Long conversations: the conversation is compacted before it outgrows the model's context window.
• Hooks: run your code before and after agents and tools, to log, validate or change what they do.

Documentation

The documentation has guides for the terminal agent and for building agents, and a reference for the CLI, the YAML schema and the event types.

Contributing

Contributions are welcome. Search the issues first; anything beyond a small fix starts from an issue a maintainer has accepted. CONTRIBUTING.md explains how to propose a change, set up the environment, run the tests and the checks, and build the documentation site. If you work with a coding agent, have it follow AGENTS.md. Everyone taking part is expected to follow the code of conduct.

To report a security vulnerability, see SECURITY.md rather than opening an issue.

License

Domyn Agents is released under the Apache License 2.0.