[WIP] Agent Builder initial docs (hidden from TOC and search engines)

[leemthompo]

Warning

We are merging this in hidden mode. The pages will be live but not indexed by search engines or visible in the docs TOC/nav.

Information architecture

IA for this very early draft:

• A main landing page elastic-agent-builder.md providing an overview of the feature
• Six subpages:
  1. get-started.md - Setup instructions for enabling and using the feature
  2. chat.md - Information about the chat interface
  3. agent-builder-agents.md - Documentation on creating and configuring AI agents
  4. tools.md - Detailed guide for creating and using tools
  5. programmatic-access.md - APIs and integration options (MCP and A2A servers)
  6. limitations-known-issues.md - Current limitations and known issues

Do we need more granular subpages?

• We might want to break out programmatic access into three subpages if we need to go into a lot of detail: API, MCP, A2A.
• We could also nest the 3 primitives: Conversations, Agents, Tools under a higher-level section titled "Primitives" or something to keep the docs nav tidy

This would change the IA to the following:

docs/
└── solutions/
    └── search/
        ├── elastic-agent-builder.md (main landing page)
        └── agent-builder/ (directory)
            ├── get-started.md
            │
            ├── primitives.md 
            │   ├── conversations.md
            │   ├── agent-builder-agents.md
            │   └── tools.md
            │
            ├── programmatic-access.md
            │   ├── api.md
            │   ├── mcp-server.md
            │   └── a2a-server.md
            │
            └── limitations-known-issues.md

[github-actions]

🔍 Preview links for changed docs

• solutions/search/agent-builder/a2a-server.md
• solutions/search/agent-builder/agent-builder-agents.md
• solutions/search/agent-builder/chat.md
• solutions/search/agent-builder/get-started.md
• solutions/search/agent-builder/kibana-api.md
• solutions/search/agent-builder/limitations-known-issues.md
• solutions/search/agent-builder/mcp-server.md
• solutions/search/agent-builder/programmatic-access.md
• solutions/search/agent-builder/tools.md
• solutions/search/elastic-agent-builder.md

[oren-zohar]

This is really great, thank you @leemthompo!
Some comments:

1. get-started.md
   • It states that the feature will be available in ECH, and not in Serverless:
   • I think Chat is probably going to change (cc @joemcelroy @akm-esco)
2. conversations.md
   • pretty empty for now, so I ignored it since it's still a draft
3. agent-builder-agents.md
   • Chat endpoint will need to be updated
   • Do we want to add another step at the end to navigate back to conversations and select the new agent?
4. tools.md
   • Chat endpoint refs, and tool names are outdated - see Tools Strategy, or link with @joemcelroy
5. programmatic-access.md
6. limitations-known-issues.md
   • Should be resolved by release time

[seanstory]

Thanks for starting this, Liam!

For the programmatic bit - in Elasticsearch, I'd expect us to link to an API Reference that would be in a separate area of the docs. Is there not an existing pattern for this with Kibana APIs?

[danajuratoni]

Self-managed will most likely be kept in sync with "Stack"

[leemthompo]

thx @danajuratoni! I wasn't sure whether usage of EIS meant it wouldn't be available to self-managed users, so just stuck this in the first draft as a placeholder :)

[jedrazb]

couple of nits! looking good

[jedrazb]

Endpoint where the A2A service can be accessed for a2a communication. This is what you point other agents to.

We should mention that both a2a endpoints also require api key authentication! classic for ES

[jedrazb]

https://a2aprotocol.ai/docs/guide/a2a-protocol-specification-python#protocol-flow-diagram

[leemthompo]

adding as comment TODOs 👍

[leemthompo]

For the programmatic bit - in Elasticsearch, I'd expect us to link to an API Reference that would be in a separate area of the docs. Is there not an existing pattern for this with Kibana APIs?

@seanstory yup we'll just have an overview here in the narrative docs and then we'll link to the Kibana API docs

[leemthompo]

We are going to merge these changes with the pages hidden from the TOC and they also won't be indexed by search engines

That will allow us to add docs URLs in Kibana and we can cut tickets for the follow up work for these pages

[florent-leborgne]

Haven't reviewed, just approving as per your last comment @leemthompo

[szabosteve]

Approve to unblock.