addAgent method

void addAgent(
  1. Agent agent, {
  2. String? path,
  3. ContextProvider? contextProvider,
  4. bool hideGetSnapshot = false,
  5. bool hideAbort = false,
})

Serves agent using the layout remoteAgent(url: '<base><path>') expects. Companion routes are mounted only when the agent supports them:

  • POST <path>: runs a turn (streams with ?stream=true). Always.
  • POST <path>/getSnapshot: reads a snapshot. Server-managed agents (defined with a session store), unless hideGetSnapshot.
  • POST <path>/abort: aborts a detached turn. Agents whose store can signal the running turn (the metadata's abortable), unless hideAbort.

So a client-managed agent gets only its turn route. The hide* flags can only remove supported routes, never force-mount unsupported ones (those could only answer with an error). Missing or unrecognized metadata counts as unsupported. To serve a companion route anyway, mount its action yourself:

router.addAction(agent.abortAgentAction, path: '/myAgent/abort');

path defaults to '/<agent name>'. contextProvider applies to every mounted route, so reading or aborting a snapshot is authorized the same way as running a turn. Future Genkit versions may add more companion routes here (each with its own hide* flag).

Throws an ArgumentError if path is invalid (see GenkitRouter.addAction; / is rejected too, since the companion routes are nested under it) or if any of the paths is already registered. Routes are added all or nothing, so after a failure none of them are served.

Implementation

void addAgent(
  Agent<dynamic> agent, {
  String? path,
  ContextProvider? contextProvider,
  bool hideGetSnapshot = false,
  bool hideAbort = false,
}) {
  final base = path ?? '/${agent.action.name}';
  // addRoutes validates the rest; '/' alone is only invalid here, because
  // the companions would become '//getSnapshot' and '//abort'.
  if (base == '/') {
    throw ArgumentError.value(path, 'path', "must not be '/'");
  }
  final capabilities = _capabilitiesOf(agent);
  addRoutes(this, [
    (action: agent.action, path: base),
    if (capabilities.snapshots && !hideGetSnapshot)
      (action: agent.getSnapshotDataAction, path: '$base/getSnapshot'),
    if (capabilities.abortable && !hideAbort)
      (action: agent.abortAgentAction, path: '$base/abort'),
  ], contextProvider: contextProvider);
}