const agent = await sdk.intelligence.createAgent({
  agent_id:             'booking-agent',
  name:                 'Booking Assistant',
  owner_domain:         'myapp.gao',
  version:              '1.0.0',
  description:          'Handles restaurant and salon bookings',
  purpose:              'booking_management',
  risk_tier_default:    'LOW',
  allowed_capabilities: [
    'intelligence:agent:run',
    'intelligence:sandbox:execute',
    'transport:message:send',
    'settlement:intent:create',
  ],
  status: 'active',
})

console.log(agent.agent_id) // "booking-agent"

---

### Run Agent — Streaming (Recommended)

for await (const chunk of sdk.intelligence.runAgentStream(agent.agent_id, userIntent)) {
  switch (chunk.type) {
    case 'text':
      // Append text to chat UI as it streams
      appendText(chunk.delta)
      break
    case 'tool_use':
      // Show which tool the agent is using
      showToolCard(chunk.tool, chunk.input)
      break
    case 'artifact':
      // Agent produced output — show download/view card
      showArtifactCard(chunk.artifact_id, chunk.artifact_type)
      break
    case 'step':
      // Planning/execution step update
      updateProgress(chunk.step)
      break
    case 'done':
      // Session complete
      finalizeSession(chunk.session_id)
      break
    case 'error':
      handleError(chunk.error)
      break
  }
}

---

Run Agent — Batch

for await (const event of sdk.intelligence.watchSession(sessionId)) {
  switch (event.type) {
    case 'state_change':  console.log('State:', event.state);    break
    case 'task_complete': console.log('Task done:', event.task); break
    case 'artifact':      showArtifact(event.artifact_id);       break
    case 'error':         handleError(event.error);              break
  }
}

// Pause (can resume later)
await sdk.intelligence.pauseAgent(agentId)

// Resume
await sdk.intelligence.resumeAgent(agentId)

// Revoke (permanent — cannot undo)
await sdk.intelligence.revokeAgent(agentId)

// Enable safe mode (all actions require human approval)
await sdk.intelligence.setSafeMode(agentId, true)

---

### Artifacts

Every meaningful agent output is stored as an immutable artifact.

// List artifacts for a domain
const artifacts = await sdk.intelligence.artifacts.list('myapp.gao')
// Get artifact metadata
const artifact = await sdk.intelligence.artifacts.get(artifactId)
// artifact.artifact_type — 'report' | 'dataset' | 'application' | 'code_bundle' | ...
// artifact.content_hash  — sha256 for integrity verification
// artifact.taint_state   — 'clean' | 'tainted'
// artifact.version       — version number
// Download artifact content
const data = await sdk.intelligence.artifacts.download(artifactId)
// → Uint8Array (file content)

Scheduler

Run agents automatically on a schedule or triggered by events.

// Cron — daily at 9am Chicago time
const job = await sdk.intelligence.scheduler.create({
  agent_id:          'report-agent',
  owner_domain:      'myapp.gao',
  trigger_type:      'cron',
  trigger_config:    { expression: '0 9 * * *', timezone: 'America/Chicago' },
  priority:          'normal',
  retry_policy:      { max_retries: 3, backoff: 'exponential' },
  execution_target:  'server',

// Webhook — trigger via HTTP POST
const job = await sdk.intelligence.scheduler.create({
  agent_id:       'order-processor',
  owner_domain:   'myapp.gao',
  trigger_type:   'webhook',
  trigger_config: { secret: crypto.randomUUID() },
})

// Event — trigger on Gao system event
const job = await sdk.intelligence.scheduler.create({
  trigger_type:   'event',
  trigger_config: { event_type: 'payment.confirmed', domain: 'myapp.gao' },
})

Trigger Types

Type

Config

Use

`cron`

`{ expression, timezone }`

Recurring time-based

`webhook`

`{ secret }`

HTTP-triggered

`event`

`{ event_type, domain }`

System event-triggered

`interval`

`{ seconds }`

Fixed interval

`threshold`

`{ metric, operator, value }`

Data condition-triggered

---

Tool Calls

const result = await sdk.intelligence.tools.call(
  'sandbox.execute_python',
  { code: 'print(1 + 1)', timeout_seconds: 10 },
  capability
)
// result.output  — tool output
// result.success — boolean
// result.artifact_ids — artifacts created by tool

import { useAgent } from '@gao/system-sdk/react'

function AgentChat({ agentId }: { agentId: string }) {
  const { run, session, streaming, artifacts, error } = useAgent(sdk, agentId)
  const [input, setInput] = useState('')

  return (
    <div>
      {/* Show streaming text */}
      {streaming && ``<StreamingText text={session?.streamBuffer}  />``}

      {/* Show artifacts when ready */}
      {artifacts.map(a => ``<ArtifactCard key={a.artifact_id} artifact={a}  />``)}

      {/* Input */}
      <input value={input} onChange={e => setInput(e.target.value)} />
      <button onClick={() => run(input)}>Send</button>

      {error && ``<ErrorMessage error={error}  />``}
    </div>
  )
}

---

Session States

State

Meaning

`initializing`

Session being set up

`planning`

Agent decomposing the request

`policy_check`

Policy Gate evaluating planned actions

`pending_approval`

Waiting for human approval (high-risk action)

`executing`

Active execution in progress

`suspended`

Paused — can resume

`completed`

Finished successfully

`failed`

Terminated with error

`cancelled`

Cancelled by user or system

---

Model Routing

GAR automatically routes to the right model based on task complexity:

Task Type

Model Used

Simple Q&A, classification, scheduled automation

`claude-haiku-4-5` (fast, cost-efficient)

Document analysis, code generation, app building

`claude-sonnet-4-5` (powerful)

Complex multi-step reasoning

`claude-sonnet-4-5`

You don’t control model selection directly — GAR optimizes for cost and quality based on the task.

---

Common Patterns

Booking Agent

)) {
  if (chunk.type === 'text')     appendToChat(chunk.delta)
  if (chunk.type === 'artifact') showBookingConfirmation(chunk)
}

Report Generation

const session = await sdk.intelligence.runAgent(
  'report-agent',
  'Generate sales report for last 30 days as PDF'
)

// Poll for completion
let result
do {
  await sleep(2000)
  result = await sdk.intelligence.getSession(session.session_id)
} while (result.state === 'executing')

if (result.state === 'completed') {
  const pdfArtifact = result.context.artifacts[0]
  const pdf = await sdk.intelligence.artifacts.download(pdfArtifact.artifact_id)
}

)) {
  if (chunk.type === 'step') console.log('→', chunk.step)
  if (chunk.type === 'done') console.log('Automation complete')
}