Agentic AIs is an interesting trend that is transforming how we interact with technology moving from simple task completion to autonomous problem-solving and strategic decision-making.

How can technical writers help build Agentic AI?

Good documentation is essential for building agentic AI, enabling AI agents to interact effectively and safely with various systems. Machine-ready documentation is content that is structured and formatted in a way that allows AI agents and other automated systems to easily access, parse, and understand the information. It is designed to be both human-readable and machine-friendly, ensuring that AI can effectively utilize the provided content.

Here are some key ideas a technical writer can adopt to improve the Agent Experience (AX)¹:

• Structured Content: Use a structured format like markdown to present information. This makes it easier for AI agents to parse and understand the documentation. Markdown also enables fixed processing methods, which are useful for AI tools. DITA is also an option.
• API Documentation: Agentic AI relies on APIs to interact with external systems², so it’s critical that technical writers create thorough API documentation. This includes details about functions, parameters, data formats, and expected responses. The documentation should be easily understood by both humans and machines.
• Machine-Readable Formats: Create documentation that is not only human-readable but also machine-friendly. This ensures that AI agents can easily access and process the required information. For example, the llms.txt proposal suggests a specific markdown format for this purpose, including file lists of URLs where further information is available.

Here are some key guidelines that can help writing content:

• Contextual Information: Provide background information and guidance that helps LLMs understand the purpose and functionality of different systems.³ This helps AI agents make informed decisions ⁴] This context should be clear and concise, and provide the necessary details for an AI to navigate different systems.
• Clear Examples: Use concrete examples to explain how AI agents can use different tools and APIs. This helps AI agents understand the practical applications and how to apply the information. Use cases and practical applications help agents understand how they should use different systems.
• Guardrails and Constraints: Document any rules, constraints, and security protocols that AI agents must follow. This ensures safe, efficient usage and prevents misuse of systems. These guardrails should be clear and easy for AI agents to interpret and adhere to.

Another idea to think about is that of Reusable APIs. Machine-ready documentation should emphasize reusable APIs with examples and use cases to guide agents in their application. This ensures agents can efficiently interact with systems especially when agents work across domains⁵.

• [?] How can writers use Agentic AI?

Footnotes

1. Introducing AX: Why Agent Experience Matters describes the Agent Experience ↩

2. Agentic AI The Rise of Agents ↩

3. Working with AI ↩

4. What is Agentic AI? ↩

5. Anthropic’s Model Context Protocol, provides a framework for how AI agents can interact with external systems in a structured way. ↩