Communication style

How agents adapt explanations, vocabulary, and detail level to each user

Agents should feel like a senior colleague who knows when to explain and when to move quickly. A new developer should not have to understand Kubernetes vocabulary before deploying an app. A platform engineer should not have to read beginner explanations before getting to the diagnosis.

Proficiency profiles

Profile	Best for	How the agent speaks
Beginner	Developers who have shipped code but not operated infrastructure	Everyday language, one step at a time, UI prompts before actions.
Intermediate	Developers who know containers and platforms like Vercel, Railway, or Heroku	Container-level vocabulary, short explanations for infrastructure terms.
Advanced	Backend engineers familiar with Docker, Kubernetes basics, logs, and deployment configuration	Correct Kubernetes terms, concise explanations, YAML or diffs when useful.
Expert	Platform engineers, SREs, and infrastructure teams	Direct technical detail, tradeoffs, raw resource names, and fewer confirmations for routine actions.

Users should be able to change this at any time with a control such as Talk to me as: Beginner / Intermediate / Advanced / Expert. The agent should not silently change someone’s level based on writing style.

Akua should remember the user’s default per workspace. A session can override it for a single conversation, and the session should show where the active style came from: user default, session override, agent default, or system default.

The profile changes presentation, not reasoning quality. The agent should still inspect the same logs, events, repository change requests, resources, and evidence. Beginner mode should put the plain-language summary first, while keeping technical details available. Expert mode should surface the technical detail immediately.

Same issue, different language

Each example below describes the same diagnosis. Only the explanation changes; the underlying evidence stays the same.

Beginner

Agent: Found it. Your app is trying to use a database, but no database is
connected yet.

I can set one up and connect it for you. It should take about a minute.

[Approval: Set up database] [Not now]

Intermediate

Agent: Your container exits because DATABASE_URL is missing. I can create a
Postgres instance and inject the connection string, or you can provide an
existing database URL.

[Create Postgres] [Use existing database]

Advanced

Agent: Pod is in CrashLoopBackOff. Last log line:
Error: connect ECONNREFUSED 127.0.0.1:5432

The app expects Postgres on localhost, but no database runs in the pod.
Use a Secret-backed DATABASE_URL or deploy Postgres separately.

[Create repository change request]

Expert

Agent: CrashLoopBackOff caused by DB connection to 127.0.0.1:5432.
No sidecar or local Postgres present. Recommend Secret-backed DATABASE_URL
and readiness gate after migration check.

I can patch values and create a repository change request.

Learning mode

Learning mode is separate from proficiency. When enabled, the agent adds short, expandable explanations for concepts the user has not seen before.

Example

Agent: I’ll start your app on one of your servers.

Learn the technical term:
In Kubernetes, this is called scheduling a pod onto a node. A pod is the running
copy of your app, and a node is a server in your cluster.

Learning notes should not repeat forever. Once a user has seen a concept, the agent can move on and gradually use more precise vocabulary.

This creates a small memory surface: Akua needs to remember which concepts a user has seen in a workspace. That memory should be visible, editable, and removable like other user preferences. It should not be inferred from private writing style or used to silently change the user’s selected profile.

Vocabulary mapping

Concept	Beginner	Intermediate	Advanced	Expert
Cluster	your group of servers	your cluster	cluster	cluster
Pod	your running app	your container	pod	pod
Deployment	your app	your deployment	Deployment	Deployment
Namespace	project space	namespace	namespace	namespace
Helm chart	app installer	app package	Helm chart	Helm chart
Secret	stored password	secret	Secret	Secret
Liveness probe	health check	health check	liveness probe	liveness probe
CrashLoopBackOff	your app keeps crashing	container restart loop	CrashLoopBackOff	CrashLoopBackOff
ImagePullBackOff	could not download your app	image pull error	ImagePullBackOff	ImagePullBackOff
Rollback	go back to the previous version	roll back	rollback to revision	shift traffic to previous revision

Related topics

Examples

See realistic deployment, investigation, and compute recommendation flows.

Configure an agent

Set communication style, runtime policy, grants, and triggers.