> For the complete documentation index, see [llms.txt](https://docs.orbitfin.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.orbitfin.ai/orbit-api-reference/a2a/5.-a2a-best-practices.md).

# 5. A2A Best Practices

These apply to every A2A service on the platform.

**Call by default; don't let the outer agent guess.** If the user's message might fall within a connected service's scope, call it to confirm rather than answering from the outer agent's own knowledge. One unnecessary call costs far less than one wrong guess.

**Carry the `contextId` across turns.** Multi-turn interactions advance step by step. Include the `contextId` on every request — without it, the service treats each call as a brand-new interaction and cannot continue the previous draft or task.

**Pass results through with minimal rewriting.** Responses are already designed for display: structured data plus readable text. The less the outer agent paraphrases, the higher the fidelity. If you must paraphrase, still copy structured facts — numbers, lists, identifiers — verbatim rather than restating them from memory.

**Turn auth and network failures into human-readable messages.** Never surface a raw error stack to the end user. Catch the exception, show something plain ("Temporarily unable to connect — please try again."), and keep retry available.

**Use `SendStreamingMessage` when progress should be visible.** For long-running interactions, the SSE streaming method lets users watch intermediate progress instead of waiting on a single blocking response.

**Never hard-code a service's capability list.** Capabilities grow over time. Read the Agent Card at runtime for the current set of Skills instead of maintaining a static copy in your own code.