Documentation / AI Agents

AI Agents runtime

Run long-lived or event-driven agents with managed deployments, durable memory, scoped credentials, human approval gates, and step-level traces.

Python + Node.jsGit or CLI deployManaged HTTPSUpdated 13 Aug 2026

Runtime model

An AI agent is a deployable Darwa service. Each agent has an entry point, runtime, environment, triggers, and an explicit set of tools. A run starts from a trigger and remains isolated from other runs while using the agent's approved memory and secrets.

AgentVersioned code, runtime settings, tools, memory policy, and secrets.

TriggerA webhook, schedule, queue event, or manual request that starts a run.

RunOne execution with its own state, logs, token usage, and final outcome.

ApprovalA paused action that requires a workspace member to allow or reject it.

Create and deploy an agent

Create an AI Agent from the dashboard, connect a repository, and choose the command that starts your process. Keep provider keys and other credentials in encrypted environment variables rather than in the repository.

darwa.yaml

kind: ai_agent
name: invoice-recovery
runtime: python3.12
entry: python -m agents.recovery

health:
  path: /health

triggers:
  - webhook: billing-events
  - schedule: "0 9 * * 1-5"

terminal

# Create from the dashboard
open https://darwa.com/dashboard/projects/new?service=agent

# Or deploy the linked service from its repository
darwa deploy . --project invoice-recovery

Runtime contract

The process must remain running and answer its configured health check. Darwa restarts an unhealthy process and records the restart in the service event stream.

Triggers

Triggers decide when a run begins. Use webhooks for external events, schedules for recurring work, queues for asynchronous workloads, and manual runs while testing.

Trigger	Use it for	Delivery behavior
Webhook	Provider callbacks and application events	Signed request with retry
Schedule	Reports, reviews, and periodic automation	Cron in the configured timezone
Queue	Bursty or high-volume asynchronous work	Acknowledgement with retry policy
Manual	Testing and operator-initiated tasks	Started from dashboard or API

darwa.yaml

triggers:
  - webhook: stripe-invoice-failed
  - schedule: "0 9 * * 1-5"
    timezone: Asia/Kolkata
  - queue: billing-events
    attempts: 5
    backoff: exponential

Memory

Run state is temporary. Store durable customer or task context in long-term memory, and use semantic search only for information the agent is allowed to retrieve. Choose stable, workspace-specific keys so unrelated customers never share a record.

agents/recovery.py

from darwa import memory

profile = memory.get("customer:cus_9F21")
memory.set("customer:cus_9F21", {"last_outcome": "recovered"})

related = memory.search(
    "payment failures resolved after card update",
    namespace="invoice-recovery",
    k=5,
)

Sensitive data

Do not place passwords, private keys, full payment-card data, or unnecessary personal data in agent memory. Use encrypted secrets for credentials and store only the minimum context a run needs.

Tools and secrets

Tools are denied until granted. Scope every grant to the smallest useful action, resource, and environment. Secret values are encrypted, injected at runtime, and never returned by the read APIs.

terminal

darwa tools grant invoice-recovery postgres:read --tables invoices,customers
darwa tools grant invoice-recovery gmail:send --from billing@example.com
darwa tools deny  invoice-recovery stripe:refunds

Control	Purpose
Action scope	Restricts read, write, send, or execute capabilities.
Resource scope	Limits tables, buckets, senders, repositories, or accounts.
Environment scope	Keeps preview credentials separate from production.
Audit record	Records the tool, run, arguments summary, duration, and outcome.

Human approvals

Place approval gates before actions with financial, customer, security, or destructive impact. The run pauses without repeating earlier steps, then continues only after an authorized workspace member approves it.

darwa.yaml

approvals:
  - tool: stripe.refund
    when: amount > 1000
    notify: finance
  - tool: database.delete
    always: true
    notify: workspace-admins

Runs, logs, and traces

Every run shows its trigger, release, duration, status, model usage, tool calls, approval waits, and errors. Use the trace to understand a decision without exposing raw secret values.

TimelineOrdered model, tool, memory, approval, and application-log steps.

UsageInput/output tokens and attributed model cost for the run.

OutcomeCompleted, failed, cancelled, timed out, or waiting for approval.

ReleaseExact deployment and source revision that handled the run.

Operational guidance

Make webhook and queue handlers idempotent because delivery can be retried.
Set timeouts and maximum attempts for every external tool call.
Use approval gates for refunds, outbound messages, access changes, and deletion.
Separate preview and production tools, memory namespaces, and secrets.
Review failed runs and token usage before increasing concurrency.

Manage deployed agents in the AI Agents dashboard, or read the REST API and CLI reference for platform automation.