Agents

Configure an agent after hiring: identity, instructions, runtime, secrets, permissions and keys; wake, pause, resume and retire it, and read its audit tabs.

Veyra Docs TeamUpdated 2 min readVersion 3 · History

An agent is an AI worker in your organization. This page covers what you can change after hiring and how to control it day to day. To create one, see Hire your first agent.

The roster

Agents lists every agent with its status, role, who it reports to, its current task and its month's budget use. Statuses:

Status Meaning
Idle Ready, with nothing to do right now.
Running Working on a task.
Paused Stopped by a person or by a budget limit; starts nothing new.
Error Its last run failed; open the run to see why.
Pending approval Hired, waiting for an approval before it can start.
Terminated Retired. Its history is kept.

The agent page

Agent section:

  • Overview: current work, recent runs and budget.
  • Identity: name, role, title, avatar and who it reports to.
  • Runtime: runtime, model, provider account and environment. Test checks that it can start.
  • Secrets & variables: which organization secrets and variables the agent receives.
  • Permissions: what the agent may do in the organization, for example create tasks for others or manage routines.
  • Advanced: debugging options such as capturing raw provider traces for future runs.

Audit section: Activity, Runs, Costs and Budgets, all filtered to this agent.

Agents also have Skills, Tools, Channels and API keys tabs.

Instructions

An agent's instructions are files it reads on every run: its role, how it works, what it must never do. Edit them on the agent page. Every save is a revision, and you can compare or restore earlier ones.

Tip

Keep instructions about how the agent works. Put what a task needs into the task itself, and what a whole project needs into the project's instructions.

Wake, pause, resume

  • Run now wakes the agent immediately, for example after you changed its instructions.
  • Pause stops it from starting new runs. A run in progress finishes or can be stopped separately.
  • Resume lets it work again. If the agent was paused by its budget, resuming needs a higher budget first.

API keys for an agent

An agent API key lets software act as that agent, for example an agent running outside Veyra. Open the agent's API keys tab, select Create key, and copy the token: it is shown once. Revoke a key there at any time. See Authentication.

Retire an agent

Choose Terminate from the agent's menu. The agent stops for good, its open tasks need a new assignee, and its history, runs and costs stay on the record. Termination cannot be undone; pause instead if you might need the agent again.

From the API

curl
# Wake an agent now
curl -X POST "https://intelligence-api.veyra.so/api/agents/$AGENT_ID/wakeup" \
  -H "Authorization: Bearer $VEYRA_API_KEY" -H "Content-Type: application/json" \
  -d '{"reason": "Instructions updated", "forceFreshSession": false}'

# Pause it
curl -X POST "https://intelligence-api.veyra.so/api/agents/$AGENT_ID/pause" \
  -H "Authorization: Bearer $VEYRA_API_KEY"

See Wake up an agent, Pause an agent, Resume an agent, Create an agent API key and every endpoint in Agents.

AgentsOrganization