Skip to main content
An agent is a named set of standing instructions and resource requirements inside a slate. ContextLayer runs those instructions as jobs. Each job receives a task prompt and has its own conversation and computer. Start hosted jobs through the API or let a schedule start them. Build an agent walks through authoring the files and running a first job.

​
An agent’s files

The agent’s name is its directory name. Pushing main publishes it, and jobs read its instructions from the latest commit on main. An agent uses only the resources in its own declaration; it does not inherit the app’s requirements. The app and agents share a namespace per resource kind. If both declare the same database slug, they refer to the same logical database and must agree on its mode. They use the same stored database when that mode selects the same Owner. Different people’s viewer-mode databases remain separate. Resources explains declarations and modes.

​
Model and authentication

A hosted agent runs on an Anthropic model. Declare and supply one of these provider secrets: If both are declared, the API key takes precedence. The secret’s owner or viewer mode selects who supplies the credential, independently of which model the agent uses. The default model is claude-haiku-4-5. To choose another, declare an ANTHROPIC_MODEL secret and save a full Anthropic model ID as its value. A changed model applies to new jobs. See Secrets.

​
Jobs

When a job starts, ContextLayer reads the agent’s definition, resolves its declared resources for the job’s actor, and starts a fresh conversation and Linux computer. The actor is the person or app the job acts for. The resolved resources stay fixed for that job. Jobs do not share conversations or computer files. They can share persistent resources: for example, a digest job can read the owner-mode notes database that the app writes to. A new job gets a fresh computer, but the database keeps its existing rows. Conversation and result records persist independently of the computer, so inspecting a completed job does not require its scratch files to remain available. Start a job with a prompt through the API: Start an agent job with a prompt. A job you start acts for you. If the agent declares viewer-mode resources, your setup for them must be complete first. Anyone who can view a private slate can start jobs and read results for their own jobs and jobs acting for the app. Managing the slate is required to inspect transcripts, usage, live execution, or schedules, and to abort or delete jobs. These operations can reveal agent instructions and private data. Deleting a job releases its computer. It does not undo database writes or actions the job has already performed in connected services.
Public slates cannot run agent jobs yet.

​
Schedules

A schedule is a Markdown file in agents/<name>/schedules/. Its YAML front matter sets cron, a five-field cron expression in UTC; its body is the prompt. The file name without .md is the schedule’s name.
agents/digest/schedules/weekly.md
This schedule starts a job every Monday at 09:00 UTC with “Summarize last week’s notes.” as its prompt. The prompt supplies the task for that run; instructions.md still supplies the standing instructions. Schedules are installed after each successful deployment. When a person first becomes a slate member, their schedules are installed after their databases have been provisioned and migrated. Each firing starts a fresh job using the latest commit on main, through the same preparation path as an API job. Who a scheduled job acts for depends on the agent’s own declaration:
  • An agent that declares no viewer-mode resources is app-scoped: each scheduled run acts for the app. An owner-mode shared-database digest can run once for the whole slate.
  • An agent that declares any viewer-mode resource is member-scoped: each scheduled run acts for a particular slate member, with schedules installed for the members. A personal-inbox digest can run separately for each member.
Scope follows the agent’s requirements, including its connections, databases, and secrets. The app’s declaration does not determine an agent’s scope.

​
Tools a hosted agent gets

  • The computer. read, write, edit and bash work on the job’s Linux computer, which has no internet access. Files there are scratch space: they last only while the computer runs, and it stops after ten minutes without activity.
  • database_query. Parameterized SQL against the agent’s declared databases. Writes persist immediately and are shared with the app and with other jobs that use the same database.
  • Connection tools. For each declared connection, the actions of its toolkit, named <connection-slug>__<ACTION>. They run with the account assigned to that connection; the agent never sees its credentials.
The agent uses Code Mode to discover connection tools and coordinate calls in a short script. Connection tools are available through Code Mode; computer tools and database_query can also be called directly. A Code Mode script reaches the job’s tools without gaining general computer or network access. The computer’s lack of internet access does not prevent authorized connection tools from calling their external services.

​
Run an agent locally

The CLI’s agent command runs an agent from the checkout with the Claude Agent SDK and your own Claude authentication; see npx @usecontextlayer/cli agent --help. This is a local development run, not a hosted job. It reads the checkout’s instructions, works in the checkout, and uses database_query for the local databases. It does not use hosted jobs or hosted database contents. The command starts the development server, so it needs your CLI login when the app declares connections. See Build an agent for the local workflow.