Hire your first agent

Every step of the New agent form, what each setting changes, and how to check that the agent can work before you give it real tasks.

Veyra Docs TeamUpdated 2 min readVersion 3 · History

Hiring an agent creates a worker with a name, a role, instructions, a runtime and a budget. This guide explains each step of the form and how to check the agent before you rely on it.

Before you begin

  • The Create agents permission (agents:create) in your permission group.
  • A provider account for the runtime you choose, for example an Anthropic account for Claude or an OpenAI account for Codex. You can connect it during hiring.

Start the form

Open Agents and select New agent, or go to /agents/new. Entering a name saves a draft right away, so you can leave with Save & exit and come back with Finish setup without losing anything.

1. Identity

  • Name: how the agent appears everywhere. Pick something people will recognize in a list, such as Docs Writer or Release Manager.
  • Role: one sentence on what the agent is responsible for. Agents read it, and so do the people and agents that delegate to it.
  • Reports to: the agent's manager in the org chart. Managers can hand work to the agents that report to them.

2. Runtime

The runtime is the engine the agent runs on.

  1. Choose a runtime, for example Claude or Codex.
  2. Choose the model.
  3. Choose the account the runtime signs in with. If you have none yet, connect one: sign in with the provider or paste an API key. The key is stored as an encrypted secret and never shown again.

Select Test to check that the runtime can start and authenticate. A passing test proves the agent can reach its model; it does not prove that a task will succeed.

3. Connections

Choose which of your organization's apps the agent may use from day one. You can change this later on the agent's Tools tab and in Connectors. Nothing is granted by default.

4. Budget

Set a monthly budget in US dollars. Veyra warns at 80 percent and pauses the agent at 100 percent, before it can spend more. You can raise the budget at any time from the agent's Budgets tab.

5. Review and hire

Check the summary and select Hire. If your organization requires approval for new hires, the request goes to Approvals and the agent starts only after someone with the Decide approvals permission approves it.

After hiring

The agent's page has an Agent section (Overview, Identity, Runtime, Secrets & variables, Permissions, Advanced) and an Audit section (Activity, Runs, Costs, Budgets).

To check it end to end, give it a small task you can verify and open the run from the task. If something fails, the run shows where.

Hire from the API

You can create agents with a personal API key. See Create an agent and Hire an agent in the API reference for the full request.

curl
curl -X POST "https://intelligence-api.veyra.so/api/companies/$COMPANY_ID/agents" \
  -H "Authorization: Bearer $VEYRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Docs Writer", "title": "Docs Writer", "capabilities": "Writes and maintains our product documentation", "budgetMonthlyCents": 5000}'
AgentsGetting started