Guides /
Getting started / Building your first custom agent
1
Name and describe it clearly“Legal Review Agent” says what it's for at a glance; “Agent 3” doesn't. Names propagate into the Timeline, mentions, and audit log everywhere it acts.
2
Write a specific system promptNot “be helpful” — describe exactly how it should behave, and what it should hand off to a human instead of deciding itself.
3
Grant only the tools it needsStart narrow. It's easy to add more later, much harder to walk back something it already did with a tool it shouldn't have had.
4
Set its default approval policyAnything with an external effect should need a human by default until you've watched it work reliably.
5
Run it in a real session before relying on itWatch its first few responses closely — this is cheaper than finding a problem after it's automated and unattended.
Name it for what it does
This sounds cosmetic but isn't — an agent's name shows up in the Timeline, in @mentions, in approval requests, and in the audit log every time it acts. “Research Agent” is unambiguous six months from now; “Agent 3” is not.
Writing a system prompt that actually constrains behavior
A vague prompt (“You're a helpful research assistant”) produces vague, inconsistent behavior. Be specific about what it should do, and — just as important — what it should explicitly not decide on its own:
“You are a careful legal reviewer. Flag contract terms, pricing commitments, and compliance language for human review rather than approving them yourself. Never send anything externally without explicit approval.”
Every tool you grant becomes something this agent can do, unsupervised, unless you mark it as needing approval. Map out the actual outcomes you need first, then grant only what's required to produce them — see A practical guide to agent permissions and approvals for the deeper reasoning here.
💡 If you're connecting an agent built with an external framework (LangChain, CrewAI, and similar) instead of building natively, the same permission and approval rules apply — an externally hosted agent never gets to skip human oversight just because it lives outside Orvoq.
Test before you deploy
Run your new agent in a normal, attended session first — not immediately as an unattended scheduled Run. Watching its first handful of responses live is the cheapest way to catch a bad system prompt or an overly broad tool grant, before it's running on a schedule with nobody watching.