Agent

The Agent module enables your application to communicate with an AI Agent built in the ART Agent Builder. It allows you to send prompts, receive strongly typed responses as a stream of events, and respond to the agent whenever it requests input during task execution.

Prerequisites

• The ADK is installed, authenticated, and connected. See Installation if you haven't set this up yet.
• An agent has been created and deployed using the Agent Builder, and you have its agentId.

Workflow

Each agent communicates over its own dedicated channel. The ADK manages this channel internally and exposes three core classes, allowing you to work with strongly typed Dart objects instead of raw network frames.

Class	Description
Agent	Represents a single AI agent identified by its agentId. Reuse the same Agent instance for all conversations with that agent.
AgentThread	Represents a single conversation with an agent. Each thread has a unique threadId that is automatically included with every request, enabling the server to maintain conversation state.
Run	Represents a single prompt–response cycle within a thread. It manages the lifecycle of a request and provides access to the agent's final response when the run completes.

Quick start

The following example shows the basic workflow for sending a prompt to an agent and handling the response:

// 1. Get the agent and start a conversation.
Agent agent = adk.agent('your-agent-id');

// 2. Start a thread
AgentThread thread = agent.thread();

// 3. Run a prompt and wait for the final response.
Run run = await thread.run('Plan a 3-day trip to Goa');
AgentOutput al result = await run.done();
print(result.message);

// 4.Listen for agent events
await thread.listen((AgentEventEnvelope envelope) {
  switch (envelope.event) {
    ...
  }
}

This example illustrates the complete interaction workflow with an agent. The following sections describe each step in detail, including event processing, handling human-input requests, and managing errors.

1. Connect to an agent

Get an agent instance from the connected Adk instance. The channel subscription is established lazily — it is established automatically the first time the agent is used, and reused after that:

Agent agent = adk.agent('your-agent-id');

2. Start a thread

An AgentThread represents a single conversation with an agent. Every message sent through the thread automatically includes its unique threadId, enabling the server to maintain conversation context and associate responses with the correct thread:

AgentThread thread = agent.thread();

print(thread.threadId); 

3. Run a prompt

Call thread.run(...) to send a prompt to the agent. The method returns a Run, which represents the lifecycle of a single prompt–response interaction. A run begins when the prompt is submitted, progresses as the agent processes the request, and completes when the agent returns its final response:

Run run = await thread.run('Plan a 3-day trip to Goa');

final AgentOutput result = await run.done();
print(result.message);

The following sequence diagram shows the complete lifecycle of a run when the agent does not request human input.

4. Listen for agent events

While run.done() provides the final AgentOutput for a run, many applications also need to observe intermediate events, such as progress updates or requests for additional user input. To receive these events, register a listener using thread.listen():

await thread.listen((AgentEventEnvelope envelope) {
  switch (envelope.event) {
    case 'agent_general_response':
      final output = envelope.content as AgentOutput;
      print('Answer: ${output.message}');
      break;
    case 'human_input_request':
      final request = envelope.content as HumanInputRequest;
      print('Agent needs input: ${request.prompt}');
      break;
    case 'agent_error_response':
      final error = envelope.content as AgentError;
      print('Error [${error.code}]: ${error.message}');
      break;
    case 'agent_wait_response':
      final wait = envelope.content as AgentWait;
      print('Waiting on agent: ${wait.waitingForAgentId}');
      break;
    case 'planner_correction_request':
      final correction = envelope.content as PlannerCorrection;
      print('Revising plan: ${correction.reason}');
      break;
    default:
      // Any event the ADK does not model arrives as UnknownAgentEvent.
      final unknown = envelope.content as UnknownAgentEvent;
      print('Unknown event ${unknown.event}: ${unknown.content}');
      break;
  }
});

Event catalog

Every event payload implements EnvelopeMeta, which provides the following routing metadata:

• threadId — The conversation to which the event belongs.
• refId — The unique identifier of this event.
• agentId — The identifier of the agent that emitted the event.
• replyTo — The refId of the event to which this event is responding.

These fields may contain empty strings if the server does not populate them.

Event	Body	Ends the run?	Key fields
agent_general_response	AgentOutput	Yes — run.done() completes successfully.	message, data, metadata
agent_error_response	AgentError	Yes — run.done() throws an AgentError.	code, message, details
human_input_request	HumanInputRequest	No — the run waits for user input.	prompt, expectedResponseType, timeout, context, schema
agent_wait_response	AgentWait	No — progress notification only.	waitingForAgentId, reason, progress, timeout
planner_correction_request	PlannerCorrection	No — progress notification only.	correctionRequired, reason, newGoal, suggestedAgents

The listener callback receives an AgentEventEnvelope for every inbound event.

Member	Type	Description
event	String	The event name. Use this value to determine the event type and dispatch the corresponding handler.
content	Object	The typed event payload. Cast it to the appropriate class based on the value of event.
isKnown	bool	Indicates whether the event is one of the event types recognized by the ADK.

The run lifecycle

A Run progresses through a small set of well-defined states during its lifetime. Understanding these states clarifies when run.done() completes successfully with the final AgentOutput, and when it throws an exception.

Diagnostics with trace

While a Run is in progress, the agent may emit trace frames containing diagnostic and telemetry information, such as heartbeats, checkpoints, and deadlock-detection signals. Trace frames are delivered separately from the normal event stream and are intended for observability, progress reporting, and debugging:

await thread.listenTrace((dynamic frame) {
  print('trace: $frame');
});

Error handling

A Run can complete successfully or fail. When awaiting run.done(), handle the two possible failure types separately, as each represents a different class of error:

try {
  AgentOutput answer = await run.done();
  print(answer.message);
} on AgentError catch (e) {
  print('The run failed: [${e.code}] ${e.message}');
} on StateError catch (e) {
  print('This run was replaced by a newer one.');
}

Error codes

Code	Meaning
HUMAN_INPUT_TIMEOUT	The user did not respond to a human_input_request before its timeout expired
TRANSPORT_ERROR	The underlying WebSocket connection failed while the Run was in progress. The ADK converts this transport failure into an AgentError so that run.done() fails consistently with other runtime errors
RUN_REJECTED	The run was rejected before producing a terminal event

Complete example

The following example starts a conversation, displays each event, answers a question automatically, and prints the result:

Future<void> talkToAgent(Adk adk) async {
  // A handle to the agent, and a fresh conversation.
  Agent agent = adk.agent("your-agent-id");
  AgentThread thread = agent.thread();

  // Display each event as it arrives (registered before run()).
  await thread.listen((AgentEventEnvelope envelope) {
    print('event: ${envelope.event}');
  });

  // Respond to any question the agent asks. (Use real UI in your Application.)
  thread.feedbackRequest((HumanInputRequest request, Run run) async {
    print('agent asks: ${request.prompt}');
    if (!run.isClosed()) {
      await run.sendFeedback('Budget 50k, 20-25 December');
    }
  });

  // Optional: progress telemetry.
  await thread.listenTrace((dynamic frame) => print('trace: $frame'));

  // Send the prompt and wait for the final response.
  Run run = await thread.run('Plan a 3-day trip to Goa');

  try {
    AgentOutput answer = await run.done();
    print('Done: ${answer.message}');
  } on AgentError catch (e) {
    print('Failed: [${e.code}] ${e.message}');
  } on StateError catch (e) {
    print('Run superseded: ${e.message}');
  }
}

API reference