Skip to Content
kosemdocs
Concepts

Agents

How agents work in projects, what tools and files they use, how visibility and secrets work, and how you watch them as they run.

An agent is an AI conversation that works inside a project. You start an agent with a task, and it thinks with one of the project's models, runs commands in its own environment, reads attached files, searches the web, asks you questions and publishes static sites. Everything an agent does stays in its append-only transcript, which streams live in the console and through the API.

How an agent works

Each agent has a configuration set when it starts and updated later as config-change events in its transcript:

  • Model and reasoning effort: an alias of one of the project's LLM Gateway models and an optional reasoning effort. You can switch either between turns.
  • Tools: the capabilities the agent can call, chosen from what the project's policies allow:
    • Commands (exec) run shell commands and background jobs in the agent's environment, with optional per-command secrets injection.
    • Files (read_file, write_file) read, write and edit files in the environment, and read_user_file, copy_user_file and view_image work with files people attach to messages.
    • Web (web_search, web_fetch) searches the web and reads web pages.
    • Questions (ask_question) pauses the agent (AWAITING_INPUT) until a person or script answers.
    • Access requests (request_access) pauses the agent (AWAITING_INPUT) to ask a person for a project access profile or secret.
    • Sites (publish_site) publishes static sites from the environment.
    • Todo list (todo_write) tracks multi-step plans visible in the console.
  • Instructions: optional project-specific guidance added on top of kosem's own instructions.
  • Environment: the image, vCPUs, memory, disk, environment variables and idle/stopped timeouts of the agent's own Linux environment.
  • Model call limit: the maximum number of model calls the agent makes after someone last wrote to it (default 1,000, up to 2,000 or the project's policy cap) before pausing so a loop can't run unchecked. Writing to the agent lets it continue.

Background jobs and watching

When a command runs longer than its timeout or starts in the background, it continues as a background job in the environment. If the agent asks to be notified when the job finishes, kosem keeps the environment running, shows the agent as Watching in the console, and wakes the agent automatically to continue its turn once the job ends. Jobs started without notification, such as a dev server, don't keep the environment awake and end when it stops.

Attached files and retention

People can attach up to 20 files to a message (up to 50 MiB per file and 1 GiB per agent, bounded by the organization's File storage quota: 1 GiB on Hobby, 25 GiB on Pro and 250 GiB on Team). Images and PDFs are shown to models that read them, and the agent can read text files or copy any attachment into its environment to process with commands.

Inactive agents, their transcripts and their attached files are kept for 90 days on Hobby, 365 days on Pro, and until deleted on Team and Enterprise (where Owners and Policy Admins can shorten retention to 7–365 days in Settings › Data retention). Deleting an agent frees its attached files and environment while keeping daily usage totals.

Visibility and access

An agent isn't an IAM principal, and nobody grants an agent a role. What an agent can do comes from its configuration, its project's policies and the access profiles and secrets people explicitly grant it.

  • Project visibility (default): everyone in the project whose role lets them see agents can read the transcript, and writers can message it.
  • Private visibility: only the agent's creator, people and groups it's explicitly shared with (Agent Viewer or Agent Writer), and project Owners or Agents Admins can see it.

Every agent keeps per-person unread state, so finished agents or ones waiting for answers appear under Needs you in the console without clearing them for teammates.

Why it works this way

  • Config and grants instead of agent roles. Keeping agents out of IAM prevents an agent from escalating privileges across a project: it only calls models its project exposes, uses tools policies allow, and reads secrets a person with access deliberately granted.
  • Append-only transcripts. Config changes, messages, tool runs and secret grants are recorded in sequence, so teammates can join a multi-day agent conversation and see exactly what changed and why.

On this page