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.
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.
- Choose a runtime, for example Claude or Codex.
- Choose the model.
- 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 -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}'Related
- Agents: everything you can change after hiring.
- Budgets and costs
- Approvals