An agent is the unit AiHummer puts in front of a conversation. Each agent has
a persona, its own model, a structured prompt and a set of skills, and every
change to it is versioned. Agents are managed from the web admin UI and through
the admin API under /v1/admin/agents/*.
This page covers what an agent is made of, how the structured “G3” prompt is
assembled, and how an agent can safely edit its own profile.
The agent registry
The registry is a full CRUD catalogue of agents. For each agent you define an
identity, a persona, the model it runs on and the skills it can use. Because the
gateway is multitenant, agents live inside a workspace and are isolated like any
other tenant data.
Persona — the voice and behaviour of the agent, rendered into a stable,
cache-friendly layer of the system prompt.
Per-agent model — each agent can pin its own model and provider, so a
cheap agent and a flagship agent can coexist in the same workspace.
Skills — per-agent and shared skills render a “Skills” block into the
prompt; they describe capabilities, not weights.
[!NOTE]
A per-agent model is independent of routing. Model-tier routing (simple /
standard / complex) chooses a model class for a turn, while the per-agent
model is the agent’s own default. See
Routing.
Versions, rollback and clone
Every meaningful change to an agent is captured as a version. This makes
agent configuration auditable and reversible: you can review what changed,
roll back to an earlier version, or clone an agent to use it as the
starting point for a new one. Version and profile resources live under
/v1/admin/agents/* (profile, sections, skills, versions).
[!TIP]
Clone a working agent before a large persona or prompt rewrite. If the new
direction does not pan out, the original is still one rollback away.
The structured “G3” prompt
Instead of a single free-text system prompt, AiHummer uses a structured
agent profile (internally “G3”). The identity is decomposed into fields
rather than buried in prose, and the rest of the prompt is built from named
sections plus an onboarding block. The orchestrator renders these into
the layered system prompt, keeping the stable parts (identity, persona,
sections) in a cacheable prefix and appending volatile data last.
The structure makes a profile easy to edit field by field, easy to diff between
versions, and predictable to render — there is no hidden prompt soup.
An agent can be allowed to edit its own profile using self-edit tools — for
example to refine a section or update its onboarding. This is deliberately
guarded:
Self-edits go through the approval gate: a proposed change is recorded and
must be approved by a human before it takes effect. A rejected change is never
applied.
The change is captured as a new version, so a self-edit is as auditable
and reversible as any manual edit.
[!WARNING]
Self-editing is powerful. Keep it behind the approval gate so an agent cannot
silently rewrite its own identity. Review proposed self-edits the same way you
review any privileged change.
Mail passwords go to the vault
If an agent’s configuration includes mail credentials (for the mail tool),
the password is written to the encrypted credential vault, not stored in the
profile or rendered into the prompt. Secrets never enter the model context.
Runtime policy: context, sessions and child agents
Since version 1.3 an agent has a runtime policy — the runtime_policy
field in the admin API (/v1/admin/agents on create and update). It is a
strictly validated JSON object with "version": 1: an empty {} restores the
defaults, omitting the field on update keeps the previous policy, and unknown
fields or out-of-range values are rejected. The policy grants no tools and
widens no rights — it only sets budgets and deadlines. Cloning an agent and
handing a turn over to it inherit the policy.
context — the history budget: max_tokens, reserve_tokens and
history_share decide how much history enters a request;
max_history_messages bounds the message window, bootstrap_max_chars the
size of the profile block. With an explicit context, older messages are
compacted into a summary in batches before the current request is built.
pruning — clean-up of stale tool results: by age (ttl_seconds),
protecting the latest replies (keep_last_assistants), a soft trim
(soft_trim_ratio, head_chars, tail_chars) and a full replacement with
the placeholder text above hard_clear_ratio. User text, images and the
full history in the database are untouched.
memory_flush — before compaction a tools-disabled agent writes a
short note on goals, decisions and open items (soft_threshold_tokens);
the latest three notes of the same conversation are mixed into the context
as unreviewed reference.
session — the conversation lifecycle: idle_reset_minutes starts a
fresh context after a pause (raw history is kept), index_prune_after_days
and index_max_entries drop old conversations from the default list without
deleting them. scope = per-peer (one conversation per verified user
across channels) or per-channel-peer (a separate conversation per channel).
children — child agents: max_depth (up to 4), max_concurrent (up
to 8 per run tree), max_per_parent (up to 5), timeout_seconds (up to 48
hours, never longer than the parent) and archive_after_minutes — when
finished runs leave the default list. The values override the global
AIHUMMER_SUBAGENT_MAX_DEPTH and AIHUMMER_SUBAGENT_TIMEOUT_SEC for this agent.
max_iterations (1–256) — the step limit of the function-calling loop
for reviewed scenarios with many delegations.
app — only for the AiHummer app: reasoning_effort, service_tier
and the quick-reply mode direct_completion (auto or always with
max_tokens up to 4096 and timeout_ms up to 60,000).
interaction — explicit session grants: user_ids,
session_agent_ids, spawn_agent_ids, the session_visibility (self,
agent or granted), session_send, tool denies for child calls
(child_tool_deny, child_leaf_tool_deny) and elevated_telegram_user_ids
— a subset of user_ids allowed to request explicitly elevated code_exec
(approvals are not bypassed). There are no wildcards and no tenant-wide
grants.
Admin API
Agents and their structured profiles are managed under the admin API, which is
OIDC-gated and audited:
An **agent** is the unit AiHummer puts in front of a conversation. Each agent has
a persona, its own model, a structured prompt and a set of skills, and every
change to it is versioned. Agents are managed from the web admin UI and through
the admin API under `/v1/admin/agents/*`.
This page covers what an agent is made of, how the structured "G3" prompt is
assembled, and how an agent can safely edit its own profile.
## The agent registry
The registry is a full CRUD catalogue of agents. For each agent you define an
identity, a persona, the model it runs on and the skills it can use. Because the
gateway is multitenant, agents live inside a workspace and are isolated like any
other tenant data.
- **Persona** — the voice and behaviour of the agent, rendered into a stable,
cache-friendly layer of the system prompt.
- **Per-agent model** — each agent can pin its own model and provider, so a
cheap agent and a flagship agent can coexist in the same workspace.
- **Skills** — per-agent and shared skills render a "Skills" block into the
prompt; they describe capabilities, not weights.
> [!NOTE]
> A per-agent model is independent of routing. Model-tier routing (simple /
> standard / complex) chooses a model class for a turn, while the per-agent
> model is the agent's own default. See
> [Routing](/en/v1.0/concepts/routing).
## Versions, rollback and clone
Every meaningful change to an agent is captured as a **version**. This makes
agent configuration auditable and reversible: you can review what changed,
**roll back** to an earlier version, or **clone** an agent to use it as the
starting point for a new one. Version and profile resources live under
`/v1/admin/agents/*` (profile, sections, skills, versions).
> [!TIP]
> Clone a working agent before a large persona or prompt rewrite. If the new
> direction does not pan out, the original is still one rollback away.
## The structured "G3" prompt
Instead of a single free-text system prompt, AiHummer uses a **structured
agent profile** (internally "G3"). The identity is **decomposed into fields**
rather than buried in prose, and the rest of the prompt is built from named
**sections** plus an **onboarding** block. The orchestrator renders these into
the layered system prompt, keeping the stable parts (identity, persona,
sections) in a cacheable prefix and appending volatile data last.
The structure makes a profile easy to edit field by field, easy to diff between
versions, and predictable to render — there is no hidden prompt soup.
```text
G3 profile
├── identity fields (decomposed: name, role, ...)
├── sections (named, ordered prompt blocks)
└── onboarding (first-run guidance)
```
## Self-editing behind an approval gate
An agent can be allowed to **edit its own profile** using self-edit tools — for
example to refine a section or update its onboarding. This is deliberately
guarded:
- Self-edits go through the **approval gate**: a proposed change is recorded and
must be approved by a human before it takes effect. A rejected change is never
applied.
- The change is captured as a new **version**, so a self-edit is as auditable
and reversible as any manual edit.
> [!WARNING]
> Self-editing is powerful. Keep it behind the approval gate so an agent cannot
> silently rewrite its own identity. Review proposed self-edits the same way you
> review any privileged change.
### Mail passwords go to the vault
If an agent's configuration includes mail credentials (for the `mail` tool),
the password is written to the **encrypted credential vault**, not stored in the
profile or rendered into the prompt. Secrets never enter the model context.
## Runtime policy: context, sessions and child agents
Since version 1.3 an agent has a **runtime policy** — the `runtime_policy`
field in the admin API (`/v1/admin/agents` on create and update). It is a
strictly validated JSON object with `"version": 1`: an empty `{}` restores the
defaults, omitting the field on update keeps the previous policy, and unknown
fields or out-of-range values are rejected. The policy grants no tools and
widens no rights — it only sets budgets and deadlines. Cloning an agent and
handing a turn over to it inherit the policy.
- **`context`** — the history budget: `max_tokens`, `reserve_tokens` and
`history_share` decide how much history enters a request;
`max_history_messages` bounds the message window, `bootstrap_max_chars` the
size of the profile block. With an explicit context, older messages are
compacted into a summary in batches before the current request is built.
- **`pruning`** — clean-up of stale tool results: by age (`ttl_seconds`),
protecting the latest replies (`keep_last_assistants`), a soft trim
(`soft_trim_ratio`, `head_chars`, `tail_chars`) and a full replacement with
the `placeholder` text above `hard_clear_ratio`. User text, images and the
full history in the database are untouched.
- **`memory_flush`** — before compaction a tools-disabled agent writes a
short note on goals, decisions and open items (`soft_threshold_tokens`);
the latest three notes of the same conversation are mixed into the context
as unreviewed reference.
- **`session`** — the conversation lifecycle: `idle_reset_minutes` starts a
fresh context after a pause (raw history is kept), `index_prune_after_days`
and `index_max_entries` drop old conversations from the default list without
deleting them. `scope` = `per-peer` (one conversation per verified user
across channels) or `per-channel-peer` (a separate conversation per channel).
- **`children`** — child agents: `max_depth` (up to 4), `max_concurrent` (up
to 8 per run tree), `max_per_parent` (up to 5), `timeout_seconds` (up to 48
hours, never longer than the parent) and `archive_after_minutes` — when
finished runs leave the default list. The values override the global
`AIHUMMER_SUBAGENT_MAX_DEPTH` and `AIHUMMER_SUBAGENT_TIMEOUT_SEC` for this agent.
- **`max_iterations`** (1–256) — the step limit of the function-calling loop
for reviewed scenarios with many delegations.
- **`app`** — only for the AiHummer app: `reasoning_effort`, `service_tier`
and the quick-reply mode `direct_completion` (`auto` or `always` with
`max_tokens` up to 4096 and `timeout_ms` up to 60,000).
- **`interaction`** — explicit session grants: `user_ids`,
`session_agent_ids`, `spawn_agent_ids`, the `session_visibility` (`self`,
`agent` or `granted`), `session_send`, tool denies for child calls
(`child_tool_deny`, `child_leaf_tool_deny`) and `elevated_telegram_user_ids`
— a subset of `user_ids` allowed to request explicitly elevated `code_exec`
(approvals are not bypassed). There are no wildcards and no tenant-wide
grants.
## Admin API
Agents and their structured profiles are managed under the admin API, which is
OIDC-gated and audited:
| Resource | Purpose |
|---|---|
| `/v1/admin/agents` | List, create, update, delete agents (CRUD) |
| `/v1/admin/agents/.../profile` | The structured G3 profile (identity fields) |
| `/v1/admin/agents/.../sections` | Named prompt sections |
| `/v1/admin/agents/.../skills` | Per-agent skills |
| `/v1/admin/agents/.../versions` | Version history, rollback and clone |
## Where to next
- Understand how agents run a turn and spawn helpers in
[Orchestration & sub-agents](/en/v1.0/concepts/orchestration-subagents).
- See how an incoming message reaches a specific agent in
[Routing](/en/v1.0/concepts/routing).
- Give your agents long-term memory with
[Memory (Einstein)](/en/v1.0/concepts/memory-einstein).
