An introduction to agents and agentic AI, including Sage's vision for the future.
First, watch this video to learn about Sage's current vision for AI agents.
The AI Agent as a user persona
Our products have always been built with human users as the focus. That remains true.
But a new type of user is emerging: the AI agent — a software system that acts autonomously, completes tasks, and interacts with our products programmatically, on behalf of a human.
This document introduces the AI agent as an additional user persona. It covers how agent needs differ from human needs, and what those differences mean for how we design, build, and document our products.
There are third-party agents that can interact with interfaces visually, the way a human would: clicking, scrolling, and reading screens rather than calling APIs. For reasons including data security, this is not the current vision at Sage.
Our agents access our products programmatically through APIs. But in order for these agents to deliver accurate and consistent results, our products must be optimised for them. This requires product teams to be aware of agent needs and to design, build, and test with those needs in mind.
What is an AI agent?
An AI agent is a software system that perceives its environment, makes decisions, and takes actions to achieve a defined goal without requiring a human to direct each step.
Agents interact with products by calling APIs, reading structured data, and executing sequences of tasks. They do not read interfaces the way a human does. They do not improvise. They follow the contracts and structures we provide.
Key distinction: A human user interprets intent. An AI agent executes instructions.
Human user vs. AI agent
| Human user | AI agent | |
|---|---|---|
| Navigates via | Visual interface (UI) | API calls, structured data |
| Interprets | Context, layout, metaphor | Schema, field names, response codes |
| Handles ambiguity | Infers and adapts | Fails or halts |
| Reads errors | On screen, in natural language | Machine-readable status codes |
| Needs permissions | Role-based access | Intent-based, least-privilege scoping |
| Pace | Variable, exploratory | Programmatic, sequential |
| Feedback loop | Visual, immediate | Structured responses, logs |
| Recovers from failure | Tries again, asks for help | Retries, escalates, or stops |
| Support content | Help articles, tooltips | API docs, schema definitions |
| Authentication | Login, session | API keys, OAuth tokens, scoped credentials |
1. Meet the agent
The AI agent is not a replacement for the human persona. It's an additional actor in the system, one that operates on behalf of a human but interacts with our products in fundamentally different ways.
Characteristics of the AI agent persona
- Acts autonomously within a defined scope
- Has no visual perception — it reads data, not screens
- Requires consistency and predictability to function correctly
- Cannot fill in gaps with common sense or contextual reasoning
- May operate as part of a larger chain of agents (see Architecture patterns)
Design implication: When designing a feature or flow, ask: If an agent needs to do this, what does it need from us?
The answer is almost always:
- clear structure
- explicit contracts
- reliable responses
2. The agent journey
A human journey is typically mapped as steps through a UI:
Discover → explore → act → confirm
An agent journey follows a different shape:
Intent → Interpretation → Action → Accountability
| Stage | What happens | What agents need |
|---|---|---|
| Intent | A human or orchestrator assigns a goal | A well-defined task scope |
| Interpretation | The agent reads available APIs and data | Self-describing endpoints, complete schemas |
| Action | The agent executes one or more operations | Consistent, predictable responses |
| Accountability | Results are logged, surfaced, or escalated | Structured outputs, audit trails |
Design implication: Design agent journeys as contracts, not flows. Each stage should have explicit inputs, outputs, and failure states, not assumed context.
3. Navigation for machines
Human navigation relies on visual hierarchy, layout, and affordance. Agents do not see any of that.
For agents, navigation is structural.
- APIs are the interface: endpoint design determines what the agent can reach
- Schema is the signage: field names, types, and constraints tell the agent where it is and what it can do
- Error responses are the feedback: a well-formed error response is as important as a success response
What good agent navigation looks like
- Consistent endpoint naming conventions
- Stable API versioning with clear deprecation paths
- Logical resource hierarchy that reflects real-world relationships
- Comprehensive error codes with actionable messages (not just "400 Bad Request")
What poor agent navigation looks like
- Endpoints that behave differently depending on undocumented state
- Error messages written only for human readers ("Oops, something went wrong")
- Inconsistent field names across related endpoints (user_id vs userId vs uid)
4. Affordance and interactivity
Traditional affordance is a visual signal: a button looks clickable, a field looks editable.
Agents do not respond to visual signals.
For agents, affordance is semantic: it comes from how well an API describes itself.
Affordance for agents
| Human affordance | Agent equivalent |
|---|---|
| Button label | Endpoint name and HTTP method |
| Inline field hint | Parameter description in API spec |
| Permission error message | 403 response with reason |
| Required field indicator | required: true in schema |
| Helper text | Example values in spec |
| Confirmation dialog | Duplicate-request protection (the system recognises and safely ignores repeated identical calls) |
Interactivity for agents
Interactivity for agents is not about clicks or gestures. It's about
- Predictable response contracts: the same input returns the same output shape
- Retry-safe operations: endpoints that can be called more than once without causing duplicate actions or unintended side effects
- Graceful degradation: partial success responses, not binary pass/fail
- Machine-readable error states: structured error objects with code, message, and resolution fields
5. Content guidelines
Content strategy for agent users operates on 2 tracks.
Track 1: UI and data content
Content that agents consume directly must be structured and unambiguous.
| Element | Human version | Agent version |
|---|---|---|
| Labels | "First name" | Field: first_name, type: string |
| Status | "Your payroll run is being processed" | status: "payroll_processing" |
| Errors | "Something went wrong" | { "code": "PAYROLL_PERIOD_LOCKED", "message": "This pay period is locked for editing", "action": "contact_administrator" } |
| Date/time | "Last updated 3 hours ago" | ISO 8601: 2025-03-10T09:00:00Z |
Guidelines
- Use consistent, predictable field names across the product
- Avoid natural language for status values — use numeric codes
- Provide machine-readable errors alongside any human-readable messages
- Use standard formats for dates, currencies, and identifiers
Track 2: Support and developer content
Agents are configured by people: developers, product teams, and system integrators. Support content must serve them.
What to document for agent users
- Authentication methods and credential scoping
- Rate limits, quotas, and throttling behaviour
- All error codes with resolution guidance
- Webhook payloads and event schemas
- Versioning and deprecation policy
- Sandbox and testing environments
Writing principles for developer documentation
- Lead with what the reader needs to do, not what the system does
- Every code example should be runnable
- Errors and edge cases deserve as much documentation as the happy path
6. Access and permissions
Agent access requires a different approach to permissions than human access.
Humans typically receive role-based access (admin, editor, viewer). Agents should receive intent-based, least-privilege access, scoped narrowly to what the agent is specifically trying to achieve.
Why this matters
Agents lack human judgment. They will use whatever access they are given. They will not pause to question whether an action is appropriate. Broad permissions given to an agent create broad risk.
Principles for agent access
| Principle | What it means in practice |
|---|---|
| Least privilege | Grant only the permissions the agent's task requires |
| Intent-scoped | Permissions tied to a specific use case, not a generic role |
| Time-limited | Credentials and tokens expire; require re-authorisation |
| Auditable | All agent actions logged with timestamp, agent ID, and action taken |
| Revocable | Access can be removed immediately without disrupting the wider system |
Design implication: Treat agent credentials the way you would treat a contractor's building pass: limited to specific areas, valid for a specific period, and revocable at any time.
7. Architecture patterns
Understanding how agents are structured helps inform how our product supports them.
Single agent
The simplest arrangement. One AI model operates with a defined set of tools and a clear task scope.
Human → [Agent] → Product API
Design consideration: The agent is the only point of failure. Error handling, logging, and fallbacks must all be explicit.
Multi-agent (orchestrated)
Multiple agents collaborate, with one orchestrating the others.
Human → [Orchestrator agent]
├── [Agent A] → Product API
├── [Agent B] → Product API
└── [Agent C] → External service
Design consideration: Context must be passed explicitly between agents. Our APIs should not assume the calling agent has memory of previous calls.
Multi-agent (peer-to-peer)
Agents interact directly without a central orchestrator. More complex, harder to trace.
Human → [Agent A] ⇄ [Agent B] ⇄ [Agent C] → Product API
Design consideration: This pattern increases the risk of tasks cycling indefinitely between agents without resolution. Our systems should enforce timeouts, maximum retry counts, and escalation paths.
General architecture principles
- Design APIs as if they will be called by agents with no prior context
- Log every agent interaction with enough detail to reconstruct what happened
- Build explicit circuit-breakers for runaway or looping agent behaviour
- Never assume a calling agent has memory of a previous session
8. Human oversight
Autonomous does not mean unmonitored.
Agents act on behalf of humans, but humans must remain in control. Our products should be designed to preserve that control at every layer.
Oversight principles
| Principle | What to build |
|---|---|
| Transparency | Users can see what agents have done, in plain language |
| Auditability | All agent actions are logged and retrievable |
| Controllability | Users can pause, revoke, or override agent actions |
| Escalation | Agents can identify when to stop and ask a human |
| Accountability | It is always clear which agent took which action and why |
When to require human confirmation
Agents should not proceed autonomously when an action is:
- Irreversible (deletion, financial transaction, data export)
- Outside the defined scope of the agent's task
- Ambiguous in a way the agent cannot resolve
- High risk by any reasonable definition
Design implication: Build confirmation gates and escalation hooks into agent-facing APIs. The agent must be able to say "I need a human to approve this." And the product must be able to receive and act on that signal.