AI Agents

The agents resource dispatches deployed agents into rooms (optionally placing an outbound call), and manages cloud deployments under agents.deployment.

note

New to agents? Build one with the AI Agents SDK and deploy it with Agent Cloud. This page covers driving those deployed agents from the Server SDK.

Dispatch an agent

Node.js

const dispatch = await client.agents.dispatch({
  agentId: "agent_123",
  roomId: "abcd-efgh-ijkl", // or meetingId
  roomOptions: { joinMeeting: true, vision: false },
});
dispatch.jobId;
dispatch.status;

Go

dispatch, err := client.Agents.Dispatch(ctx, videosdk.DispatchAgentParams{
	AgentID:     "agent_123",
	RoomID:      "abcd-efgh-ijkl", // or MeetingID
	RoomOptions: &videosdk.AgentRoomOptions{JoinMeeting: videosdk.Bool(true), Vision: videosdk.Bool(false)},
})
fmt.Println(dispatch.JobID, dispatch.Status)

Rust

let dispatch = client.agents().dispatch(DispatchAgentParams {
    agent_id: Some("agent_123".into()),
    room_id: Some("abcd-efgh-ijkl".into()), // or meeting_id
    room_options: Some(AgentRoomOptions {
        join_meeting: Some(true),
        vision: Some(false),
        ..Default::default()
    }),
    ..Default::default()
}).await?;
println!("{:?} {:?}", dispatch.job_id, dispatch.status);

Options: agentId (required), roomId / meetingId (one required), roomOptions, sipOptions (when present, the dispatch also places an outbound call), metadata, versionId.

Deploy a pre-built image

A single call runs the entire pipeline: it creates the deployment, its version (auto-activated), and, when env vars are set, a secret to hold them.

Node.js

const deployment = await client.agents.deploy({
  name: "voice-assistant",
  image: "registry.videosdk.live/acme/agent:1.4",
  env: { OPENAI_API_KEY: "sk-..." },
  scaling: { min: 1, max: 20 },
});
deployment.id;

Go

deployment, err := client.Agents.Deployment.Create(ctx, videosdk.DeployAgentParams{
	Name:    "voice-assistant",
	Image:   "registry.videosdk.live/acme/agent:1.4",
	Env:     map[string]string{"OPENAI_API_KEY": "sk-..."},
	Scaling: &videosdk.AgentScaling{Min: videosdk.Int(1), Max: videosdk.Int(20)},
})
fmt.Println(deployment.ID)

Rust

let deployed = client.agents().deployment().create(DeployAgentParams {
    name: "voice-assistant".into(),
    image: Some("registry.videosdk.live/acme/agent:1.4".into()),
    env: HashMap::from([("OPENAI_API_KEY".into(), "sk-...".into())]),
    scaling: Some(AgentScaling { min: Some(1), max: Some(20) }),
    ..Default::default()
}).await?;
println!("{}", deployed.deployment.id);

Options: name and image (a tag string, or a full image object) (required), env, scaling (max ≤ 50), profile (cpu-small, cpu-medium, cpu-large), region, agentId, webhook.

Manage deployments

Node.js

await client.agents.deployment.list({ agentId: "agent_123" });
await client.agents.deployment.get("dep_1");
await client.agents.deployment.getLatestVersion("dep_1");
await client.agents.deployment.delete("dep_1", { force: true });
await client.agents.deployment.setVersionActive(versionId, true); // false stops the version

Go

client.Agents.Deployment.List(ctx, videosdk.ListDeploymentsParams{AgentID: videosdk.String("agent_123")})
client.Agents.Deployment.Get(ctx, "dep_1")
client.Agents.Deployment.GetLatestVersion(ctx, "dep_1")
client.Agents.Deployment.Delete(ctx, "dep_1", true)          // force
client.Agents.Deployment.SetVersionActive(ctx, versionID, true, false) // activate, force

Rust

client.agents().deployment().list(ListDeploymentsParams {
    agent_id: Some("agent_123".into()),
    ..Default::default()
}).await?;
client.agents().deployment().get("dep_1").await?;
client.agents().deployment().get_latest_version("dep_1").await?;
client.agents().deployment().delete("dep_1", true).await?;                     // force
client.agents().deployment().set_version_active(version_id, true, false).await?; // activate, force

Logs

Historical console logs (default: the last 24 hours).

Node.js

for await (const line of await client.agents.deployment.logs("dep_1", { roomId })) {
  console.log(line.log);
}

Go

logs, err := client.Agents.Deployment.Logs(ctx, "dep_1", videosdk.ListDeploymentLogsParams{RoomID: videosdk.String(roomID)})
for _, entry := range logs.Data {
	fmt.Println(entry.Log)
}

Rust

let logs = client.agents().deployment().logs("dep_1", ListDeploymentLogsParams {
    room_id: Some(room_id.clone()),
    ..Default::default()
}).await?;
for entry in logs.data {
    println!("{}", entry.log);
}

The dispatch result

Returned by dispatch.

Field	Type	Description
jobId	string	Id of the created dispatch job.
status	string	Dispatch status.
workerId	string	Id of the worker handling the job.
roomId	string	Room the agent joined.
agentId	string	The dispatched agent id.
success	boolean	Whether the dispatch was accepted.

The deployment object

Returned by agents.deployment.list and get. agents.deploy returns these same fields plus the created version (a version object), and a secretId when env vars were set.

Field	Type	Description
id	string	The deployment id.
agentId	string	Id of the agent this deployment runs.
name	string	Deployment name.
template	string	Template the deployment was created from.
status	string	Deployment status.
envSecret	string	Id of the attached env secret, if any.

The version object

Returned by agents.deployment.getLatestVersion, and nested as version on a deploy result.

Field	Type	Description
id	string	The version id.
deploymentId	string	Id of the parent deployment.
region	string	Region the version runs in.
minReplica	number	Minimum replica count.
maxReplica	number	Maximum replica count.
status	string	Version status.
active	boolean	Whether this is the active, running version.
versionTag	string	Your version tag, if set.

The log entry

Returned by agents.deployment.logs.

Field	Type	Description
log	string	The log line text.
timestamp	string	When the line was emitted.
metadata	object	Structured context for the entry, if any.