google-gemini/gemini-cli · error

Agent '${agentName}' not found.

Error message

Agent '${agentName}' not found.

What it means

Thrown by `sendMessageStream` when no client is registered under `agentName` in the `clients` map. The method is a generator; before delegating to the A2A client it looks up `clients.get(agentName)` and refuses to proceed on `undefined`, because there is no transport to stream over.

Source

Thrown at packages/core/src/agents/a2a-client-manager.ts:206

    this.agentCards.clear();
    debugLogger.debug('[A2AClientManager] Cache cleared.');
  }

  /**
   * Sends a message to a loaded agent and returns a stream of responses.
   * @param agentName The name of the agent to send the message to.
   * @param message The message content.
   * @param options Optional context and task IDs to maintain conversation state.
   * @returns An async iterable of responses from the agent (Message or Task).
   * @throws Error if the agent returns an error response.
   */
  async *sendMessageStream(
    agentName: string,
    message: string,
    options?: { contextId?: string; taskId?: string; signal?: AbortSignal },
  ): AsyncIterable<SendMessageResult> {
    const client = this.clients.get(agentName);
    if (!client) throw new Error(`Agent '${agentName}' not found.`);

    const messageParams: MessageSendParams = {
      message: {
        kind: 'message',
        role: 'user',
        messageId: uuidv4(),
        parts: [{ kind: 'text', text: message }],
        contextId: options?.contextId,
        taskId: options?.taskId,
      },
    };

    try {
      yield* client.sendMessageStream(messageParams, {
        signal: options?.signal,
      });
    } catch (error: unknown) {
      const prefix = `[A2AClientManager] sendMessageStream Error [${agentName}]`;

View on GitHub (pinned to 5024443c72)

Solutions

1. Ensure `loadAgent(agentName, ...)` has resolved successfully before calling sendMessageStream with that name.
2. Check `manager.getAgentCard(agentName)` (or `getClient(agentName)`) is non-undefined before sending.
3. Verify the exact name spelling and casing against the name used at load time.
4. If loading is async, await it (or guard the send behind its completion) before dispatching messages.

Example fix

// before
await manager.loadAgent('reviewer', { url });
for await (const r of manager.sendMessageStream('Reviewer', 'hi')) {} // casing typo

// after
for await (const r of manager.sendMessageStream('reviewer', 'hi')) {}

function assertAgentLoadedForSend(manager: A2AClientManager, name: string) {
  if (!manager.getClient(name)) {
    throw new Error(`Agent '${name}' not loaded. Call loadAgent first.`);
  }
}

assertAgentLoadedForSend(manager, 'reviewer');
for await (const r of manager.sendMessageStream('reviewer', msg)) {}

function isAgentReadyToSend(manager: { getClient(n: string): unknown }, name: string): boolean {
  return manager.getClient(name) !== undefined;
}

try {
  for await (const r of manager.sendMessageStream(name, msg)) {}
} catch (e) {
  if (e instanceof Error && e.message.endsWith('not found.')) {
    await manager.loadAgent(name, opts); // lazy load then retry once
    return;
  }
  throw e;
}

When it happens

Trigger: Calling `sendMessageStream('reviewer', ...)` before `loadAgent('reviewer', ...)` has completed; using a name that was never loaded; a typo in the agent name; the agent was loaded under a different alias than the one being messaged.

Common situations: Skipping the loadAgent step in a bootstrap script; an orchestrator that dispatches by name from config but config and registration drift; race where sendMessageStream is invoked before the async loadAgent resolves; casing mismatch (`Reviewer` vs `reviewer`).

Related errors

• Agent with name '${name}' is already loaded.
• Duplicate skill name "${skill.name}" found at multiple locat
• Failed to parse inline agent card JSON for agent '${name}':
• Agent card is missing.
• Invalid taskId: ${taskId}

AI-assisted analysis of google-gemini/gemini-cli@5024443c72 (2026-08-12). Data as JSON: /api/errors/8657b18958bb3b17. Report an issue: GitHub.