Clarify recommended project structure and organization patterns for AgentKit-based apps

[astern-puffins]

AgentKit is flexible and can be used in many different ways, but new users may struggle to understand how to structure a real-world project around it. The repository does not currently provide guidance on recommended file structure, separation of concerns, or scaling patterns for larger agent-based applications.

Problem Description

Developers building with AgentKit may be unsure about:

• where to define agents vs tools vs providers
• how to organize long-running agents vs request-based agents
• how to separate configuration, execution logic, and orchestration
• how to scale from a simple demo to a production-ready setup

Without guidance, teams often invent their own structures, leading to inconsistent patterns and harder-to-maintain codebases.

Expected Behavior

• Developers should have a reference for organizing AgentKit projects.
• Examples should demonstrate clean separation of concerns.
• Guidance should help teams avoid common structural pitfalls.

Steps to Reproduce

1. Start a new project using AgentKit.
2. Add multiple agents, tools, and providers.
3. Attempt to organize the codebase in a scalable way.
4. Notice the lack of official guidance or examples.

Proposed Solution

• Add a documentation section or guide such as “Project Structure & Architecture”.
• Provide one or two example directory layouts (small app vs larger app).
• Explain recommended separation between:
  • agent definitions
  • tools/providers
  • configuration and runtime wiring
• Keep guidance opinionated but optional.