Agent Basics

An agent in AiQarus is a configured AI entity that performs tasks autonomously while maintaining full traceability and control.

What Makes AiQarus Agents Different

Most “AI agents” in the market are essentially workflow automation tools with an LLM wrapper. AiQarus agents exhibit genuine intelligence:

Agent Components

Every agent is defined by these components:

1. Identity

name: "Employee Offboarding Agent"
description: "Handles secure offboarding of departing employees"
project: "HR Operations"

2. System Prompt

The core instructions that define behavior:

You are an HR offboarding specialist. Your responsibilities:
1. Gather information about the departing employee
2. Assess security risk based on access and departure type
3. Create a prioritized action plan
4. Execute revocations and knowledge transfer
5. Generate completion report

Always explain your reasoning. Pause for approval on high-risk actions.

3. Model Configuration

4. Capabilities (Tools)

Agents must be explicitly granted access to tools:

tools:
  - okta_list_user_apps
  - okta_revoke_access
  - github_list_repos
  - github_transfer_ownership
  - slack_send_message
  - memory_read
  - memory_write

5. Constraints

Safety limits that prevent runaway behavior:

constraints:
  max_steps: 25
  max_duration_seconds: 600
  max_tokens_per_run: 50000

6. Interactivity

How the agent interacts with humans:

interactivity:
  mode: key_decisions  # autonomous | key_decisions | conversational
  risk_threshold: 50   # Pause when risk score exceeds this

Agent Lifecycle

┌──────────┐      ┌──────────┐      ┌──────────────┐      ┌──────────┐
│  DRAFT   │─────▶│  ACTIVE  │─────▶│  DEPRECATED  │─────▶│ ARCHIVED │
└──────────┘      └──────────┘      └──────────────┘      └──────────┘
     │                  │
     │                  └── Immutable, runnable
     └── Editable, not runnable

State Transitions

Creating an Agent

Option 1: Agent Builder UI

The visual wizard guides you through each component:

1. Navigate to Agents → Create Agent
2. Fill in basic information
3. Write system prompt
4. Select tools and capabilities
5. Configure constraints
6. Set interactivity mode
7. Review and activate

See Agent Builder UI for detailed walkthrough.

Option 2: GraphQL API

Create agents programmatically:

mutation CreateAgent($input: CreateAgentInput!) {
  createAgent(input: $input) {
    id
    name
    status
    version
  }
}

See API Reference for full schema.

Best Practices

Write Clear System Prompts

• Be specific about the agent’s role and responsibilities
• List expected inputs and outputs
• Explain when to escalate vs proceed autonomously
• Include examples for complex scenarios

Set Appropriate Constraints

• Start conservative, loosen as you gain confidence
• Consider the worst-case scenario for max_steps
• Set duration limits based on expected complexity

Grant Minimal Capabilities

• Only grant tools the agent actually needs
• Review tool access during security audits
• Use capability namespaces for fine-grained control

Plan for Human Oversight

• Use key_decisions mode for most business processes
• Define clear escalation criteria
• Test the approval workflow before production