What are agents?

Agents are autonomous workers that can execute complex multi-step workflows, make intelligent decisions based on conditions, and learn from past executions. Unlike simple workflows that follow a fixed sequence of steps, agents can reason about their tasks, choose which tools to use, and adapt their approach based on the results of previous actions.

Agents run in sandboxed cloud environments with full access to your configured integrations. They can be triggered manually, on a schedule, or by events — just like workflows — but they operate with a higher degree of autonomy and intelligence.

Agent architecture

Each agent consists of four core components:

• Instructions — Natural language or YAML-based directions that define what the agent should accomplish, its constraints, and how it should behave. Think of instructions as a job description for your agent.
• Tools — The set of integrations and built-in capabilities the agent can use. An agent with access to Slack, GitHub, and a database can read messages, create pull requests, and query data autonomously.
• Memory — Optional persistent storage that lets agents learn from past runs. Agents with memory enabled can remember previous decisions, avoid repeating mistakes, and improve their performance over time.
• Guardrails — Safety constraints that prevent agents from taking unwanted actions. These include approval requirements for high-impact operations, spending limits, and restricted operations.

Creating an agent

Create a new agent from the dashboard by navigating to Agents → New Agent, or use the CLI for a faster setup:

okinawa agent create --name "Lead Processor" --model default

This creates a basic agent with default settings. To customize during creation:

okinawa agent create \\\n --name "Lead Processor" \\\n --model advanced \\\n --tools slack,salesforce,sendgrid \\\n --memory enabled \\\n --max-steps 25 \\\n --timeout 300

The --model flag selects the AI model powering your agent. default balances speed and capability, while advanced provides deeper reasoning at the cost of slightly longer execution times.

Writing effective instructions

Agent instructions are the most important part of configuration. Well-written instructions lead to reliable, predictable behavior. Here's a framework for writing great instructions:

instructions:\n goal: |\n Process incoming leads from the website contact form.\n Enrich each lead with company data from Salesforce.\n Score the lead based on company size and engagement.\n Route high-value leads to the sales team immediately.\n\n constraints:\n - Never send more than 5 Slack messages per hour\n - Always verify email format before creating CRM contacts\n - Do not create duplicate Salesforce leads\n - Wait at least 60 seconds between API calls to avoid rate limits\n\n behavior:\n - If the lead score is above 80, send an immediate Slack alert to #sales-leads\n - If the lead score is between 50-80, add to the nurture campaign in HubSpot\n - If the lead score is below 50, log for future analysis only\n - Always include the company name, lead score, and source in notifications

Tool configuration

Grant agents access to specific tools and integrations. Each tool can be configured with fine-grained permissions:

tools:\n - name: slack\n permissions:\n - sendMessage\n - readChannels\n restrictions:\n allowed_channels: ["#sales-leads", "#marketing"]\n \n - name: salesforce\n permissions:\n - createLead\n - updateContact\n - searchAccounts\n restrictions:\n max_api_calls_per_run: 50\n \n - name: sendgrid\n permissions:\n - sendEmail\n restrictions:\n allowed_templates: ["welcome-v2", "nurture-sequence-1"]

By explicitly defining what each tool can do, you ensure the agent operates within safe boundaries even when making autonomous decisions.

Memory and learning

Enable the memory system to let agents learn from past executions. Memory works in three modes:

• Session memory — Remembers context within a single agent run. Useful for multi-step processes where later steps need data from earlier ones.
• Workflow memory — Persists across runs of the same agent. The agent remembers how it handled similar situations before and can apply those learnings.
• Global memory — Shared across all agents in your workspace. Agents can learn from each other's experiences and build on collective knowledge.

Configure memory in the agent settings:

memory:\n enabled: true\n mode: workflow\n retention: 90d\n max_entries: 1000\n include:\n - successful_resolutions\n - error_patterns\n - user_preferences

Guardrails and approvals

For agents that perform sensitive operations, configure approval workflows:

guardrails:\n require_approval:\n - action: delete*\n message: "Agent wants to delete: {{action.target}}"\n - action: sendEmail\n when: "{{action.recipients | length}} > 10"\n message: "Agent wants to email {{action.recipients | length}} recipients"\n - action: salesforce.updateOpportunity\n when: "{{action.fields.amount}} > 50000"\n message: "Agent wants to update opportunity worth ${{action.fields.amount}}"\n\n spending_limits:\n per_run: 1.00\n per_day: 10.00\n per_month: 100.00\n\n rate_limits:\n max_actions_per_minute: 30\n max_api_calls_per_run: 100

When a guardrail triggers, the agent pauses and sends an approval request to the designated approvers via Slack, email, or the dashboard. Approvers can approve, reject, or modify the proposed action.

Monitoring agent performance

Track your agents' performance from the Agents → Monitoring dashboard:

• Execution metrics — Success rate, average duration, steps per run, and cost per execution
• Decision logs — See why the agent chose each action, with full reasoning chains
• Error analysis — Identify recurring failure patterns and common edge cases
• Memory insights — View what the agent has learned and how it's applying past knowledge

Set up alerts for abnormal behavior: high error rates, unexpected cost spikes, or guardrail violations. All monitoring data is available via the API for integration with your existing observability stack.