Writing and Publishing Agent Cards

Course: Agent Discovery & Agent Cards

Level: Beginner to Medium

Type: Individual

Duration: 5 to 7 days

Objective

This assignment tests your understanding of why agent discovery exists, what every field in an Agent Card communicates, and how to publish a valid, discoverable Agent Card from an A2A server. By completing this assignment, you will have written Agent Cards from scratch, identified and fixed common authoring mistakes, served cards via both FastAPI and FastA2A, and built a dynamic endpoint whose card reflects real-time skill availability.

Problem Statement

You are required to author Agent Cards for two hypothetical agents, identify and fix errors in a deliberately broken Agent Card, and publish your own Agent Card from a working Python server. The final task requires you to build a dynamic Agent Card endpoint whose published skills change based on a runtime flag, simulating a real production scenario where a backend service may be temporarily unavailable.

Tasks

Task 1: Discovery Fundamentals Research (15 marks)

• Find two real-world examples of .well-known endpoints used on the web (for example, .well-known/openid-configuration or .well-known/security.txt). For each, describe: what it serves, who consumes it, and how Agent Cards follow the same pattern.

• Write a short explanation (150 to 200 words) of why hardcoding agent URLs and skill names into a Client Agent is a scalability and maintenance problem. Use a concrete scenario with at least three agents to illustrate what breaks.

• Draw or describe a simple diagram showing the difference between a system where agents are wired together manually and one where they use Agent Cards for discovery. Include at least four agents in your example.

Task 2: Write Agent Cards by Hand (25 marks)

• Write a complete agent.json file for a hypothetical 'Invoice Extractor' agent. The agent must have two skills: one that extracts structured data from a PDF invoice and one that validates an extracted invoice against a business rules schema. Every field must be populated: id, name, description, version, skills (with id, name, description, inputModes, outputModes, input schema, output schema, and at least one example per skill), and an authentication block using API key auth.

• Write a second agent.json for a hypothetical 'Translation Agent' that supports three skills: translate text, detect language, and batch translate a list of strings. Include inputModes and outputModes for each skill.

• For both cards, write a 100 to 150 word explanation of each skill description — specifically how you wrote it to be matchable by an LLM doing semantic skill matching, not just readable by a human.

• Review the three poorly written skill descriptions below and rewrite each one. For each rewrite, explain in one to two sentences what was wrong with the original and why your version is better. Originals: (a) name: 'process', description: 'does the processing task'; (b) name: 'get_data', description: 'returns data from the source'; (c) name: 'run_analysis', description: 'runs an analysis on the input'.

Task 3: Identify and Fix a Broken Agent Card (20 marks)

• You are given the following Agent Card JSON. Identify every error, missing required field, and structural problem. List each issue with a one-sentence explanation of why it is a problem for a Client Agent trying to use this card.

• Broken card to analyse:{  "name": "DataAgent",  "skills": [    {      "name": "Summarise",      "description": "does stuff"    },    {      "id": "translate",      "description": "translates things"    }  ],  "url": "http://dataagent/api"}

• Produce a corrected, complete version of the card that a Client Agent could actually consume. Add any missing required fields with sensible values. The fixed card must be valid JSON and follow the A2A Agent Card specification.

• Write a 100 to 120 word explanation of what would happen at runtime if a Client Agent tried to use the broken card — at which step in the discovery workflow would each error surface?

Task 4: Publish an Agent Card via FastAPI and FastA2A (25 marks)

• Write a FastAPI server (server_static.py) that serves a handcrafted agent.json at the correct .well-known/agent.json path. The server must return the correct Content-Type header (application/json) and a Cache-Control header (max-age=3600).

• Start the server and fetch the card using curl or httpx. Confirm the response headers and body are correct. Include the full curl output (including headers) in your submission.

• Write a second server (server_fasta2a.py) using FastA2A that auto-generates and serves an Agent Card from the agent's metadata. Confirm that the auto-generated card appears at .well-known/agent.json.

• Compare the two published cards side by side. List any differences in structure or content between the manually authored card and the FastA2A-generated card, and explain whether those differences matter for a Client Agent.

Task 5: Build a Dynamic Agent Card Endpoint (15 marks)

• Extend your FastAPI server to serve a dynamic Agent Card at .well-known/agent.json. The card must include a skill called 'pdf_extractor' that is marked as available (include it in the skills array) only when an environment variable PDF_SERVICE_AVAILABLE is set to true. When the variable is false or absent, the skill must be omitted from the response.

• Demonstrate the dynamic behaviour: run the server with PDF_SERVICE_AVAILABLE=true and fetch the card, then set PDF_SERVICE_AVAILABLE=false and fetch it again. Include both responses in your submission.

• Write a 100 to 130 word explanation of why you chose to omit the skill entirely rather than include it with an 'unavailable' flag. What are the trade-offs of each approach? When would you choose the other approach?

Bonus (Optional — up to +10 Marks)

• Add a /validate endpoint to your FastAPI server that accepts a JSON body and returns a structured validation report: which required fields are present, which are missing, and whether all skill descriptions meet a minimum word count of 10 words.

• Write a third Agent Card for a real agent you have built or plan to build. Explain how you would publish it and how a Client Agent would discover it.

• Serve your dynamic Agent Card with a Last-Modified response header that updates whenever the set of available skills changes. Explain how a Client Agent could use this header for efficient caching.

Evaluation Rubric

Criteria	Marks
Discovery Fundamentals Research	15
Agent Cards Authored by Hand	25
Broken Card Identification and Fix	20
Published via FastAPI and FastA2A	25
Dynamic Agent Card Endpoint	15
Total	100

Deliverables

• invoice_extractor_agent.json and translation_agent.json — your two hand-authored Agent Cards.

• broken_card_analysis.md — your annotated list of errors in the broken card and the corrected version.

• server_static.py — the FastAPI server serving the static Agent Card.

• server_fasta2a.py — the FastA2A server serving the auto-generated card.

• server_dynamic.py — the dynamic Agent Card server with the conditional skill.

• Terminal output or screenshots showing: curl responses with headers for both servers, both dynamic card responses (PDF_SERVICE_AVAILABLE=true and false).

• A README.md with instructions for running each server and the environment variable required for the dynamic endpoint.

Submission Guidelines

Submit your work via the course LMS (for example, Moodle or Google Classroom).

File Naming Convention: <YourName>_AgentDiscovery_Assignment1.zip

Inside the ZIP: 

• invoice_extractor_agent.json

• translation_agent.json

• broken_card_analysis.md

• server_static.py

• server_fasta2a.py

• server_dynamic.py

• requirements.txt

• README.md

• screenshots/ (folder with terminal output images or curl responses)

Deadline: 7 days from the date of release.

Late Submission Policy

• Up to 24 hours late: 10% penalty applied to the final mark.

• 24 to 48 hours late: 20% penalty applied to the final mark.

• Beyond 48 hours: submission will not be accepted.

Important Instructions

• Agent Card JSON must be valid and parseable. Run your JSON through a validator before submitting.

• Skill descriptions must be written for LLM-assisted semantic matching, not just human readability. Vague descriptions (e.g. 'processes data') will result in a deduction on Task 2.

• The Content-Type and Cache-Control headers are required for full marks on Task 4. A response without correct headers is not a compliant Agent Card endpoint.

• The dynamic endpoint must read the environment variable at request time, not at server startup. The card must change without restarting the server.

• Plagiarism of any kind will result in disqualification from the assignment.

Guidance and Tips

• When writing skill descriptions, think like a Client Agent LLM that has never seen your code. Ask: if I only had this description, could I confidently decide whether this skill can handle my task?

• For the input and output schemas, use JSON Schema format with a type field and a properties object. At minimum include the key fields a caller would need to know about.

• To test dynamic behaviour without restarting the server, set the environment variable in your shell (export PDF_SERVICE_AVAILABLE=true on Mac/Linux, set PDF_SERVICE_AVAILABLE=true on Windows) before starting the server each time.

• For Task 3, start by listing every field that is required by the A2A Agent Card specification and check which ones are missing. Then look for semantic problems (e.g. vague descriptions, missing schemas).

• Compare your FastA2A-generated card against your hand-authored card field by field. Differences are expected — the goal is to understand what FastA2A generates automatically and what you may need to customise.

Instructor Note

The most common mistake in this assignment is writing skill descriptions that describe the implementation rather than the capability. A Client Agent's LLM does not read your code — it reads the description field. Every word in that field either helps or hurts the agent's ability to match the right skill to the right task. A submission that demonstrates genuine thought about how another agent will read your card will always score higher than one that merely satisfies the structural requirements.

Call to Action

Ready to transform your business with AI-powered intelligence that accelerates insights, enhances decision-making, and unlocks the full value of your data?

Codersarts is here to help you turn complex data workflows into efficient, scalable, and evidence-driven AI systems that empower teams to make smarter, faster, and more confident decisions.

Whether you’re a startup looking to build AI-driven products, an enterprise aiming to optimize operations through data science, or a research organization advancing innovation with intelligent data solutions, we bring the expertise and experience needed to design, develop, and deploy impactful AI systems that drive measurable business outcomes.

Get Started Today

Schedule an AI & Data Science Consultation:

Book a 30-minute discovery call with our AI strategists and data science experts to discuss your challenges, identify high-impact opportunities, and explore how intelligent AI solutions can transform your workflows and performance.

Request a Custom AI Demo:

Experience AI in action with a personalized demonstration built around your business use cases, datasets, operational environment, and decision workflows — showcasing practical value and real-world impact.

Email: contact@codersarts.com

Contact Us

Transform your organization from data accumulation to intelligent decision enablement — accelerating insight generation, improving operational efficiency, and strengthening competitive advantage.

Partner with Codersarts to build scalable AI solutions including RAG systems, predictive analytics platforms, intelligent automation tools, recommendation engines, and custom machine learning models that empower your teams to deliver exceptional results.

Contact us today and take the first step toward next-generation AI and data science capabilities that grow with your business ambitions.