HumalikeHUMALIKE

Agent Lifecycle

Understanding the complete lifecycle of agents from creation to deletion.

Lifecycle Overview

Every agent goes through distinct phases. Understanding these phases helps you build reliable integrations and handle edge cases gracefully.

CREATED
REST API
CONNECTED
WebSocket
ACTIVE
Processing
ENDED
Cleanup
HUMA-0.1 Only
Join CallIn CallLeave Call
1

Created

An agent is created via the REST API. At this point, the agent exists in the database but isn't doing anything yet. It's waiting for a client to connect.

Can Do
  • Query agent details via REST
  • Update agent configuration
  • Delete the agent
  • Connect via WebSocket
Cannot Do
  • Send messages to agent
  • Receive responses
  • Join voice calls
Should Do
  • Store the agent ID securely
  • Note the expiresAt if using TTL
  • Connect promptly to start interacting
Time-Limited Agents: If you set ttlSeconds when creating, the agent will automatically expire and be deleted after that duration, even if never connected.
2

Connected

A WebSocket connection is established between your client and the agent. The agent is now ready to receive events and respond. Multiple clients can connect to the same agent simultaneously.

Requirements

Agent exists
Not expired
Valid API key
You own the agent
Can Do
  • Send messages and events
  • Receive agent responses
  • Monitor agent status
  • Join voice calls (HUMA-0.1)
  • Disconnect gracefully
Cannot Do
  • Change agent type
  • Transfer to another user
Should Do
  • Handle connection errors
  • Implement reconnection logic
  • Listen for status changes
  • Track expiration time

Possible Connection Errors

MISSING_AGENT_IDNo agent ID provided
UNAUTHORIZEDInvalid or missing API key
AGENT_NOT_FOUNDAgent doesn't exist
AGENT_EXPIREDTTL has elapsed
3

Active (Processing)

The agent is actively processing events and responding. During this phase, the agent cycles through different processing states as it works on your requests.

IDLE
THINKING
ACTING
Automatically returns to IDLE when complete
Can Do
  • Send additional events (queued)
  • Receive status updates
  • Receive tool call requests
  • Send tool results back
  • Interrupt with new context
Cannot Do
  • Change agent configuration mid-processing
  • Cancel already-executed actions
Should Do
  • Show status indicators to users
  • Handle tool calls promptly
  • Implement cancellation for long tools
  • Update your UI based on status

Voice Calls (HUMA-0.1 Only)

HUMA-0.1 agents can join Daily.co voice calls for real-time spoken interaction. This is a sub-phase within the Active state - the agent must be connected before joining a call.

Connected
In Voice Call
Connected

Room Events

room_joinedJoined successfully
room_leftLeft the call
participant_joinedUser joined

Audio Events

transcriptUser speech text
speakAgent speech text
vad_startVoice detected
Fatal Error: If you receive transcriber_fatal_error, the speech recognition has failed permanently. The agent will disconnect from the call. You should notify the user and optionally reconnect.
4

Ended

The agent's lifecycle ends either through explicit deletion, expiration, or cleanup. Once ended, the agent cannot be recovered.

Manual Deletion

You call DELETE /api/agents/:id. Best practice: disconnect clients first.

TTL Expiration

The ttlSeconds has elapsed. Clients receive AGENT_EXPIRED.

System Cleanup

Inactive agents may be cleaned up by the system. Configure retention policies as needed.

Expiration Sequence

1

If in a voice call, the agent leaves the call automatically

2

All connected clients receive an AGENT_EXPIRED error

3

All WebSocket connections are terminated

4

The agent is permanently deleted from the database

Can Do
  • Create a new agent
  • Handle the expiration gracefully in UI
Cannot Do
  • Reconnect to the agent
  • Recover agent data
  • Extend the TTL after expiration

Best Practices

Connection Management

  • Always handle connection errors and implement reconnection logic
  • Check expiresAt before connecting
  • Gracefully handle disconnections in your UI

Time-Limited Agents

  • Choose TTL that covers your expected session plus buffer time
  • Consider creating a new agent before expiration for seamless handoff
  • Use TTL for temporary sessions that auto-cleanup

Voice Calls

  • Always send leave-daily-room before disconnecting
  • Handle transcriber errors by notifying users
  • Monitor participant events to show who's in the call

Resource Cleanup

  • Delete agents when no longer needed
  • Track agent creation in long-running apps
  • Prefer TTL for temporary/ephemeral sessions