Auxot
Docs Pricing Login

What Is an Agent?

An agent is an AI assistant with a defined identity, purpose, and set of capabilities. Each one has a name, a personality written in plain language, and access to whatever tools it needs for its job.

Think of agents as specialized team members: a code reviewer who follows your style guide, a support assistant who knows your product, an ops agent who can query your infrastructure. Users talk to agents in the Auxot chat UI — the agent’s configuration shapes everything about how it responds.

Every Auxot installation comes with a built-in admin agent that manages the platform itself: creating other agents, configuring tools and skills, viewing system status, and so on. You interact with it through the chat UI, in plain language.

Creating an Agent

There are two ways to create an agent:

Settings → Agents → + Add Agent — fill in a name, description, and personality directly in the UI.

Admin agent chat — describe what you want in plain language:

Create an agent called "Support Bot" with this personality:
"You are a friendly support assistant for Acme. Help users with billing,
account issues, and product questions. Be concise and direct."

The admin agent will create it and ask if you want to add skills, tools, or other configuration. Either path produces the same result.

To update, rename, or delete an agent later, go back to Settings → Agents and use the edit controls, or ask the admin agent.

Each user has their own separate conversation history with every agent, so sessions don’t bleed between users.

Teams and Visibility

Business and Enterprise: Agents can be scoped to a specific team. Mention it when creating the agent, or ask the admin agent later:

Make the Code Reviewer agent only visible to the Engineering team

Running the Agent Worker

Every agent needs a running agent worker — a process that connects to Auxot and powers the agent’s identity and capabilities. Auxot handles conversations and LLM inference; the worker handles file access, code execution, and anything that needs to touch local resources.

You can run the worker anywhere:

  • Your local machine, while developing or testing
  • A Docker container on a server or cloud VM
  • A Kubernetes pod in a production environment

Step 1 — Create the agent and get a worker key

Go to Settings → Agents → + Add Agent, create the agent, then open it and generate a worker key from the agent detail page.

Or ask the admin agent:

Create an agent called "Code Reviewer" and generate a worker key

Either way you’ll receive an agnt.… key. Save it — it’s shown once and not stored.

Step 2 — Set up the agent’s workspace folder

The agent reads its identity and files from a folder on your machine. At minimum, create a file called SOUL.md — this is the agent’s personality, written in plain English:

mkdir -p ~/agents/code-reviewer
cat > ~/agents/code-reviewer/SOUL.md << 'EOF'
# Code Reviewer

You are a meticulous code reviewer with deep expertise in Go and TypeScript.
Your job is to catch bugs, suggest improvements, and enforce the team's style guide.
Be direct and specific in your feedback.
EOF

You can scaffold a fuller workspace structure with:

npx @open-gitagent/gitagent init ~/agents/code-reviewer

Step 3 — Run the agent

With Docker (recommended):

docker run -d \
  --name code-reviewer \
  -e AUXOT_AGENT_KEY=agnt.abc123... \
  -e AUXOT_ROUTER_URL=https://your-auxot-instance.com \
  -v ~/agents/code-reviewer:/agent \
  --restart unless-stopped \
  ghcr.io/auxothq/auxot-agent:latest

Or run the binary directly:

AUXOT_AGENT_KEY=agnt.abc123... \
  AUXOT_ROUTER_URL=https://your-auxot-instance.com \
  auxot-agent --dir ~/agents/code-reviewer

Once running, the agent connects to Auxot and appears online in the agent list. If it goes offline, no jobs are dispatched until it reconnects.

For production deployments, see the Deployment Guide →.

Updating the Agent’s Identity

Edit SOUL.md or any other file in the workspace folder, then restart the worker process. The agent re-reads the folder on reconnect and the new identity takes effect immediately.

What Agents Can Do

Agents that run on your machine can read and write files, run shell commands, and remember things across sessions — all within the workspace folder you mounted.

On top of that, you can grant any agent access to external tools:

  • Web search — search the web and fetch URLs
  • MCP tools — GitHub, Postgres, Slack, or any MCP server configured in your Tool Worker Policy

External tool access is off by default. Ask the admin agent to enable what each agent needs:

Give the Code Reviewer agent access to GitHub

Credentials for external tools never touch the agent’s machine — they’re resolved and injected by Auxot’s tools infrastructure.