Skopik Scoutskopik

Agents & Live Brain

An Agent is Skopik's durable identity noun. While execution compute and sessions are ephemeral, an Agent's identity, standing instructions, live brain files, installed skills, model defaults, capability boundaries, and spending budgets persist indefinitely.

Use an existing Agent when knowledge, memory, and context should accumulate across many tasks. For quick one-off work, you can also open a Session without specifying an Agent, and Skopik will instantiate one from the default Template.

Create an Agent

When creating an Agent, name is an immutable lowercase kebab-case identifier. Human-facing details such as displayName, description, and instructions can be updated at any time.

const agent = await skopik.agents.create({
	name: 'market-analyst',
	displayName: 'Market Intelligence Analyst',
	title: 'Senior Market Researcher',
	description: 'Synthesizes market data, financial filings, and competitive landscapes.',
	instructions: 'Always cite primary sources. Distinguish observed data from model inference. Be concise.',
	status: 'active',
	defaultModelId: 'openai/gpt-5.6-luna',
	defaultReasoning: 'high',
	canWrite: true,
	canWebSearch: true,
	canWebBrowse: true,
	canSpawnAgents: false,
	dailyBudgetUsd: 10,
	weeklyBudgetUsd: 50,
	files: [
		{
			path: 'AGENTS.md',
			content: '# Analyst Operating Guide\n\n1. Check SEC filings first.\n2. Summarize key metrics.\n',
			contentType: 'text/markdown',
		},
		{
			path: 'references/guidelines.md',
			content: '# Valuation Guidelines\n\nPrefer EV/NTM Revenue multiples for software companies.\n',
			contentType: 'text/markdown',
		},
	],
})

console.log('Created agent:', agent.agentId, agent.slug)

Idempotent setup with upsert

For automated deployments, migration scripts, and continuous integration, use skopik.agents.upsert(). It creates the Agent if the name does not yet exist and updates mutable fields if it already does:

const agent = await skopik.agents.upsert({
	name: 'market-analyst',
	displayName: 'Market Intelligence Analyst',
	instructions: 'Always cite primary sources and include explicit confidence ratings.',
	status: 'active',
	canWebSearch: true,
	canWebBrowse: true,
})

files provided in upsert() only seed newly created Agents. To avoid overwriting memory accumulated by an existing Agent, upsert() does not clobber an existing brain; update brain files explicitly via the Files API.

Status lifecycle & capability controls

Field Possible Values Platform Effect
status draft, active, paused, archived Only active Agents can start new Sessions. draft and paused reject new runs.
defaultModelId Model identifier string Default LLM selected when a Session does not explicitly override it.
defaultReasoning minimal, low, medium, high, xhigh, max Default reasoning/thinking effort level.
canWrite boolean Grants write-capable tool execution (when the Session permission also permits it).
canWebSearch boolean Allows live web search tools.
canWebBrowse boolean Enables interactive web browser rendering and scraping.
canSpawnAgents boolean Permits delegating work to autonomous child Sessions.
dailyBudgetUsd number Hard spend ceiling over a rolling 24-hour window.
weeklyBudgetUsd number Hard spend ceiling over a rolling 7-day window.

Capabilities operate as a hard upper bound: a Session's permission mode cannot grant a capability that the underlying Agent does not have.

Manage Agent brain files

Every Agent owns a live, versionless brain directory tree. Address files using the Agent's agentId as the target parameter. Paths are relative POSIX paths without leading slashes:

const locator = {
	target: agent.agentId,
	path: 'references/industry-glossary.md',
}

// Write or update a reference file
await skopik.files.writeText(locator, {
	content: '# Industry Glossary\n\nARR: Annual Recurring Revenue.\nNDR: Net Dollar Retention.\n',
	contentType: 'text/markdown',
})

// Read a brain file
const text = await skopik.files.readText(locator)

// List brain files under a folder
const { data: files } = await skopik.files.list({
	target: agent.agentId,
	path: 'references',
})

Standard brain layout conventions

Path Purpose
AGENTS.md Core identity, operating guidelines, and tone rules read on every turn.
MEMORY.md Durable long-term memory, learned user preferences, and synthesized facts.
references/ Supporting knowledge base documents, glossaries, schemas, and policies.
skills/ Installed Skills copied from the catalog. Each skill owns a skills/{skillName}/ subfolder.

Safe concurrent edits with ETags

Files return an etag string. Supply ifMatch on updates to guarantee you only overwrite the version you previously inspected:

const current = await skopik.files.stat({
	target: agent.agentId,
	path: 'MEMORY.md',
})

await skopik.files.writeText(
	{ target: agent.agentId, path: 'MEMORY.md' },
	{
		content: `${currentText}\n- User prefers executive summary format.\n`,
		ifMatch: current.etag,
	},
)

If another process or turn updated MEMORY.md in the meantime, the request fails safely with HTTP 412 Precondition Failed (file_precondition_failed), allowing you to re-read and reconcile.

See Files & Brain Storage for complete file operations including pre-signed S3 upload and download URLs.

List, update, and archive Agents

// List all active agents
const { data: agents, page } = await skopik.agents.list({
	status: 'active',
	limit: 50,
})

// Fetch single agent
const current = await skopik.agents.get(agent.agentId)

// Update mutable settings and budget
const updated = await skopik.agents.update(agent.agentId, {
	displayName: 'Lead Strategic Analyst',
	defaultReasoning: 'xhigh',
	weeklyBudgetUsd: 75,
})

// Archive agent (soft-delete)
await skopik.agents.delete(agent.agentId)

Deleting an Agent archives its identity. Historical Sessions, billing records, and transcripts remain available for auditing, while new Sessions cannot be opened with the archived Agent.

Launch a Session with the Agent

const session = await skopik.sessions.open({
	agent: agent.agentId,
	prompt: 'Produce a valuation brief comparing Stripe and Adyen.',
	permission: 'ask',
})

See Sessions for streaming, steering, approvals, client tools, structured outputs, and environment execution.